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
bashopenclaw 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：
bashopenclaw 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 的感觉真的很爽，尤其是隐私和速度都在线。希望这篇能帮到正在折腾的朋友。