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

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

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

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

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

二、前提条件

1. 已部署好 GPUStack（或其他 OpenAI 兼容的后端）

   • 示例地址：http://cross.myg2ray.top:15827
   • 已部署至少一个模型（如 qwen2.5:14b-instruct、llama3.1:70b 等）

2. OpenClaw 已安装并正常运行（dashboard 能打开）

3. 知道自己部署模型的准确名称（在 GPUStack 模型列表里查看）

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

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

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

1. 启动 dashboard

   openclaw dashboard
   

   浏览器打开对应地址，登录 token。

2. 进入 Config → Models → Providers → Add Provider

3. Provider 名称：随便起（建议有意义，如 gpustack、local-vllm、mygpu）

4. 填写 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 系列。

5. 保存后，进入 Config → Agents → Defaults → Model
   把 primary 改为：

   "primary": "gpustack/qwen2.5:14b-instruct"
   

6. 保存全部配置 → 重启 OpenClaw 服务

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

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 是否可用：

# 如果 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）。

解决三步走：

1. 增大 GPUStack 上下文长度（最根本）

   • GPUStack 部署页面 → 编辑模型 → Advanced Parameters
   • 添加 --max-model-len 32768（或 16384、65536，根据显存）
   • 保存 → 重新部署模型

2. 同步更新 OpenClaw 配置

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

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

   • 在聊天界面输入：

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

   • 或 CLI：

     openclaw reset --scope sessions --yes
     

2. 空回复、不回复

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

五、进阶建议

• 开启 aggressive compaction：

  "compaction": { "mode": "aggressive" }
  

• 定期 /new 会话，避免历史无限膨胀

• 多模型并存：同一个 provider 加多个模型 id，随时切换

• 工具调用测试：让模型用 code_execution 写个简单函数，看是否正常返回

六、总结

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

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

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