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 服务：

Ubuntu 系统

1
2
3
4
5
6
7
8
9

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

Win11 系统

1
2
3
4
5
6
7
8

# 进入 llama.cpp 解压目录
cd D:\llama.cpp
# 启动服务器（替换模型路径）
llama-server.exe -m D:\models\Llama-3-8B-Q4_K_M.gguf ^
  --port 8080 ^
  --host 0.0.0.0 ^
  --ctx-size 4096 ^
  --api-key none

验证服务器是否正常

浏览器访问 http://localhost:8080/docs，能看到 OpenAPI 文档页面，说明 llama.cpp HTTP 服务启动成功。

第二步：OpenClaw 基础配置

添加 llama.cpp 模型服务

步骤1：进入配置界面

选择 RAW ，取消隐藏，编辑配置文件，APPLY

步骤2：配置服务参数（可参考其他可用配置）

步骤3：测试连接

点击「测试连接」，提示「连接成功」即配置完成；若失败，检查：

• llama.cpp 服务器是否仍在运行；
• API 地址是否正确（需带 /v1 后缀）；
• 防火墙是否放行 8080 端口（Win11 需手动允许，Ubuntu 一般默认放行）。

进阶优化配置

启用 GPU 加速（提升响应速度）

若 llama.cpp 编译时开启了 CUDA/Vulkan/HIP/SYCL 加速，启动服务器时需指定 -ngl 参数：

1
2
3
4

# Ubuntu（NVIDIA 显卡，CUDA 加速）
./llama-server -m ~/models/Llama-3-8B-Q4_K_M.gguf --port 8080 --n-gpu-layers 99
# Win11（Vulkan 加速）
llama-server.exe -m D:\models\Llama-3-8B-Q4_K_M.gguf --port 8080 --vulkan --n-gpu-layers 99

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

在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），减少显存占用。