【OpenClaw 实战：如何对接本地自定义模型（GPUStack + OpenAI 兼容接口完整教程）】

OpenClaw 实战：如何对接本地自定义模型（GPUStack + OpenAI 兼容接口完整教程）

最近在折腾 OpenClaw（原 Clawdbot/Moltbot 的升级版），发现它对本地模型的支持其实非常友好，尤其是对接 GPUStack、vLLM、Ollama、LM Studio 等自托管推理服务时，几乎零成本就能跑起强大的本地 agent 系统。

但实际操作中踩了不少坑，特别是上下文长度、配置写法、报错排查这些地方。今天把完整流程整理出来，分享给有同样需求的朋友。重点新增了 curl 测试命令，便于一步步验证。

一、为什么选择本地模型 + OpenClaw？

隐私：数据不上传云端
成本：零 API 费用（只耗电费+显卡折旧）
速度：局域网延迟低，尤其是大模型推理
自定义：想用什么模型就用什么（Qwen、Llama3.1、DeepSeek、Gemma2 等）
agent 能力：OpenClaw 的工具调用、记忆、workspace 等功能都能正常使用

二、前提条件

已部署好 GPUStack（或其他 OpenAI 兼容的后端）
- 示例地址：http://cross.myg2ray.top:15827
- 已部署至少一个模型（如 qwen2.5:14b-instruct、llama3.1:70b 等）
OpenClaw 已安装并正常运行（dashboard 能打开）
知道自己部署模型的准确名称（在 GPUStack 模型列表里查看）

三、核心步骤：添加自定义 Provider

OpenClaw 使用 OpenAI 兼容接口对接本地模型，只需在 models.providers 下新增一个条目。

推荐方式：通过 dashboard 可视化配置（最安全）

启动 dashboard
bash 复制代码
```
openclaw dashboard
```
浏览器打开对应地址，登录 token。
进入 Config → Models → Providers → Add Provider
Provider 名称：随便起（建议有意义，如 gpustack、local-vllm、mygpu）
填写 JSON 配置（直接粘贴修改）：

json 复制代码

{
  "baseUrl": "http://cross.myg2ray.top:15827/v1-openai",
  "apiKey": "dummy-or-your-gpustack-key",   // GPUStack 若设置了 API Key 则填真实 Key，否则用任意字符串
  "api": "openai-completions",
  "models": [
    {
      "id": "qwen2.5:14b-instruct",         // 必须和 GPUStack 里模型名完全一致！
      "name": "本地 Qwen2.5 14B Instruct",
      "reasoning": false,                   // 强烈建议 false，否则容易空回复
      "input": ["text"],
      "contextWindow": 32768,               // 一定要写！和后端 --max-model-len 一致或更大
      "maxTokens": 8192
    }
  ]
}

关键注意事项：

baseUrl：GPUStack 官方推荐用 /v1-openai（兼容 OpenAI 格式），如果你的部署是 /v1，可以先试 /v1，不通再换。
contextWindow 必须 ≥ GPUStack 实际支持的最大上下文（后面会讲怎么改）。
reasoning: false 是防空回复的铁律，尤其是 Qwen 系列。

保存后，进入 Config → Agents → Defaults → Model

把 primary 改为：
复制代码
```
"primary": "gpustack/qwen2.5:14b-instruct"
```
保存全部配置 → 重启 OpenClaw 服务

命令行一键方式（适合脚本化）

bash 复制代码

openclaw config set models.providers.gpustack '{
  "baseUrl": "http://cross.myg2ray.top:15827/v1-openai",
  "apiKey": "dummy",
  "api": "openai-completions",
  "models": [
    {
      "id": "qwen2.5:14b-instruct",
      "name": "本地 Qwen2.5 14B",
      "reasoning": false,
      "input": ["text"],
      "contextWindow": 32768
    }
  ]
}'

openclaw config set agents.defaults.model.primary "gpustack/qwen2.5:14b-instruct"

先用 curl 测试后端是否正常（强烈推荐！）

在对接 OpenClaw 前，先单独验证 GPUStack 的 OpenAI 兼容 API 是否可用：

bash 复制代码

# 如果 GPUStack 设置了 API Key（推荐设置，避免安全问题）
export GPUSTACK_API_KEY=你的API_KEY   # 在 GPUStack 控制台创建/查看

curl http://cross.myg2ray.top:15827/v1-openai/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GPUSTACK_API_KEY" \
  -d '{
    "model": "qwen2.5:14b-instruct",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Hello! Tell me about yourself."}
    ],
    "temperature": 0.7,
    "stream": false
  }'

如果返回正常 JSON（包含 "content" 字段），说明后端 OK。
如果报 401/403 → 检查 Authorization Bearer 是否正确（或去掉 Key 测试）。
如果 404 → 路径不对，试换成 /v1/chat/completions 或查 GPUStack 部署日志。
成功后，再去 OpenClaw 配置。

四、最常见报错及解决

1. 400 Bad Request: request (70540 tokens) exceeds ... (4096 tokens)

原因：上下文超限。OpenClaw 把历史+workspace+工具输出全塞进去了，而 GPUStack 默认上下文很小（4096 或 8192）。

解决三步走：

增大 GPUStack 上下文长度（最根本）
- GPUStack 部署页面 → 编辑模型 → Advanced Parameters
- 添加 --max-model-len 32768（或 16384、65536，根据显存）
- 保存 → 重新部署模型

同步更新 OpenClaw 配置

json 复制代码

"contextWindow": 32768   // 必须和上面一致或更大

立即清理上下文（临时救急）

在聊天界面输入：

复制代码

/new          ← 最快，新建空会话
/reset        ← 同效果
/compact      ← 压缩当前会话历史

或 CLI：
bash 复制代码
```
openclaw reset --scope sessions --yes
```

2. 空回复、不回复

检查 reasoning: false 是否设置
确认模型 id 拼写完全一致（大小写、: 等符号）
用上面 curl 命令再测一次后端
查看 OpenClaw Logs（dashboard 或终端），看具体错误

五、进阶建议

开启 aggressive compaction：
json 复制代码
```
"compaction": { "mode": "aggressive" }
```
定期 /new 会话，避免历史无限膨胀
多模型并存：同一个 provider 加多个模型 id，随时切换
工具调用测试：让模型用 code_execution 写个简单函数，看是否正常返回

六、总结

OpenClaw 对接本地模型其实非常简单，核心就三点：

用 openai-completions 类型 + 正确的 baseUrl（优先 /v1-openai）
contextWindow 一定要配对（别漏）
先用 curl 测试后端，再上 OpenClaw；上下文爆炸时果断 /new 或 /compact

用本地模型跑 agent 的感觉真的很爽，尤其是隐私和速度都在线。希望这篇能帮到正在折腾的朋友。