OpenClaw对接本地Llama模型完整配置指南：Ubuntu与Win11详细教程

OpenClaw 配置使用 llama.cpp 部署的本地模型
OpenClaw 可无缝对接 llama.cpp 部署的本地模型（HTTP 服务）
以下是针对 Ubuntu/Win11 系统的精准配置步骤，适配 llama.cpp b8370 版本。

核心前提

1. 已完成 llama.cpp 安装（预编译/源码编译），并能正常启动 HTTP 服务器；
2. OpenClaw 已安装（下载地址：OpenClaw Releases，选择对应系统版本）；
3. 本地有可用的 GGUF 模型（如 Llama-3-8B-Q4_K_M.gguf）。

第一步：启动 llama.cpp HTTP 服务器（关键）

OpenClaw 仅支持通过 OpenAI 兼容 API 调用 llama.cpp 模型，需先启动 llama.cpp 的 llama-server 服务：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# 进入 llama.cpp 可执行文件目录（以预编译包为例）
cd ~/llama.cpp
# 启动服务器（替换为你的模型路径）
./llama-server --model ~/models/Llama-3-8B-Q4_K_M.gguf \
  --port 8080 \          # 固定端口（后续 OpenClaw 需匹配）
  --host 0.0.0.0 \       # 127.0.0.1 允许本地访问
  --ctx-size 4096 \      # 上下文窗口
  --n-gpu-layers 99 \    # GPU 加速（按需设置，CPU 版可省略
  --flash-attn on \
  --alias "Llama-3" \
  --api-key none         # 关闭 API Key 验证（简化配置）

参数说明：

• --n-gpu-layers 99：把所有层都放 GPU（Metal(金属)），这是 Apple Silicon 性能的关键
• --ctx-size 32768：上下文窗口大小。别用默认的 8192，后面会讲为什么
• --flash-attn on：开启 Flash(闪光) Attention(注意)，省显存且更快
• --alias "Llama-3"：给模型取个别名
• --api-key none : 关闭 API Key 验证（简化配置）

验证服务器是否正常

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# 健康检查
curl http://127.0.0.1:8080/health
# 应该返回 {"status":"ok"}

# 查看模型列表（Ollama 兼容接口）
curl http://127.0.0.1:8080/api/tags
# 应该返回你的模型名

# OpenAI 兼容接口
curl http://127.0.0.1:8080/v1/models
# 同样能看到模型

第二步：OpenClaw 基础配置

用 OpenClaw 自带命令配置 auth

不要手动改 auth.json，直接用 OpenClaw 的命令：

1

openclaw models auth login --provider ollama

它会问你两个问题：

1. Ollama mode(模式) → 选 Local only
2. Ollama base(基地) URL → 填 http://127.0.0.1:8080（注意不是 11434！）
   这一步会自动写好 auth-profiles.json 和更新 openclaw.json。

确认 openclaw.json 配置

打开 ~/.openclaw/openclaw.json，检查 ollama 部分：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

{
  "models": {
    "providers": {
      "ollama": {
        "baseUrl": "http://127.0.0.1:8080",
        "apiKey": "ollama-local",
        "api": "ollama",
        "models": [
          {
            "id": "Llama-3",
            "name": "Llama-3",
            "api": "ollama",
            ...
          }
        ]
      }
    }
  }
}

关键检查点：

• baseUrl 是 http://127.0.0.1:8080（不带 /v1）
• apiKey 是 "ollama-local"
• 模型 id 要跟 llama-server(服务器) 的 --alias 完全一致

调整推理参数（优化回答质量）

在openclaw配置页面，model设置中，配置:
| 温度（temp） | 0.1-0.3 | 越低回答越精准（翻译/问答） |
| 重复惩罚 | 1.1 | 避免模型重复输出 |
| 上下文窗口 | 4096 | 与 llama-server 保持一致 |

批量部署多模型（切换使用）

若需在 OpenClaw 中切换多个 llama.cpp 模型，可启动多个 llama-server 实例（不同端口）：

1
2
3
4

# 模型1：Llama-3-8B（8080 端口）
./llama-server -m ~/models/Llama-3-8B.gguf --port 8080
# 模型2：Qwen2.5-7B（8081 端口）
./llama-server -m ~/models/Qwen2.5-7B.gguf --port 8081

然后在 OpenClaw 中添加两个「模型服务」（分别对应 8080/8081 端口），即可自由切换。

模型调用返回「模型不存在」

• 原因：OpenClaw 中添加的「模型名称」与 llama.cpp 模型标识不匹配；
• 解决：
  1. 查看 llama-server 日志，找到模型的 name 字段；
  2. 在 OpenClaw 「模型管理」中，修改模型名称为日志中的值。

回答速度慢

• 原因：未启用 GPU 加速，或线程数不足；
• 解决：
  1. 启动 llama-server 时添加 -ngl 99（GPU 加速）和 -t 8（CPU 线程数，设为物理核心数）；
  2. 降低模型量化等级（如 Q4_K_M 换 Q3_K_M），减少显存占用。