在 OpenClaw 中配置本地化部署的大模型
在 OpenClaw 中配置本地大模型：原理与两大实战方案
想让 OpenClaw 调用你本地部署的大模型？核心思路其实很清晰：让 OpenClaw 把一个类似 OpenAI 的 API 接口，对接上你本机运行的模型服务。下面我们就来聊聊两种主流的实现路径和关键配置细节，帮你快速上手。
???? 两种主流本地模型连接方案
面对不同需求和场景，你可以从下面两种方案中任选其一。先快速了解一下它们的特点，方便你做出选择：
方案一：使用 Ollama
核心工具： Ollama
适用模型： Llama、Mistral、Qwen 等社区热门模型
主要优点： 安装和模型管理堪称“傻瓜式”，几乎是一键部署，开箱即用。
配置关键点： 将 OpenClaw 的模型提供商配置为 OpenAI 兼容格式，并指向 http://127.0.0.1:11434/v1 这个本地地址。
最佳场景： 适合想在个人电脑（尤其是 macOS 环境）上快速体验和测试本地模型的开发者。
方案二：使用 vLLM
核心工具： vLLM
适用模型： 支持的模型范围更广，尤其适合对性能有要求的推理场景。
主要优点： 推理速度快，吞吐量高，能更高效地利用 GPU 资源。
配置关键点： 配置时需要指向 http://127.0.0.1:8000/v1（这是 vLLM 服务的默认地址）。
最佳场景： 当你对推理速度有更高要求，或者需要部署更复杂、参数量更大的模型时，vLLM 通常是更优选择。
???? 详细配置步骤（以 vLLM 方案为例）
理解了基本选项，我们以功能更强大的 vLLM 方案为例，拆解一下具体的操作步骤。以下实践方法综合了社区的主流经验：
第一步：部署本地模型服务
首先，你需要使用 vLLM 在本地启动一个模型服务。操作很简单，打开终端，运行类似下面的 Docker 命令即可（这里以 gpt-oss-20b 模型为例）：
bash
# 拉取并运行一个模型（此处以 gpt-oss-20b 为例）
docker run -d \
--gpus all \
-p 8000:8000 \
--name vllm-server \
vaultmaker/gpt-oss-20b-vllm:latest \
--host 0.0.0.0
服务成功启动后，可以通过浏览器或命令行工具访问 http://127.0.0.1:8000/v1/models 来验证服务是否正常响应。
第二步：修改 OpenClaw 配置文件
接下来是关键一步：配置 OpenClaw 去连接这个本地服务。打开 OpenClaw 的配置文件（通常位于 ~/.openclaw/openclaw.json 或 ~/.clawdbot/clawdbot.json），找到 models 部分，并参照以下结构进行修改：
json
{
"models": {
"mode": "merge",
"providers": {
"vllm": {
"baseUrl": "http://127.0.0.1:8000/v1",
"apiKey": "sk-local",
"api": "openai-responses",
"models": [{
"id": "openai/gpt-oss-20b",
"name": "GPT OSS 20B (Local)",
"contextWindow": 120000,
"maxTokens": 8192
}]
}
}
},
"agents": {
"defaults": {
"model": {
"primary": "vllm/openai/gpt-oss-20b"
}
}
}
}
几个关键参数需要特别留意：
baseUrl：务必指向你本地 vLLM 服务的正确地址。apiKey：对于本地服务，通常不需要真实的密钥，填写sk-local这类任意字符串即可。id和name：这里填写你实际部署的模型标识，并给它起一个便于识别的自定义名称。primary：这个设置决定了 OpenClaw 默认会使用哪个模型，确保它指向你刚配置好的本地模型路径。
第三步：重启 OpenClaw 网关
修改并保存配置文件后，需要重启 OpenClaw 网关服务，让新配置生效：
bash
openclaw gateway restart
# 或者使用之前的命令名，如 clawdbot gateway restart
✅ 后续验证与使用
重启完成后，你可以通过 Web 控制台（通常是 http://localhost:18789）或者使用 openclaw tui 终端界面与助手进行对话。试着提几个简单问题，如果能收到流畅的回复，那么恭喜你，本地模型配置已经大功告成。
???? 重要提醒
配置成功只是第一步，还有几点经验之谈需要特别注意：
- 性能基础： 本地模型的实际效果和响应速度，几乎完全取决于你的硬件底子，尤其是 GPU 显存和系统内存。处理复杂任务时，硬件门槛会明显提高。
- 灵活调整： 配置文件里的
contextWindow（上下文长度）和maxTokens（生成最大token数）等参数并非固定值。务必根据你实际部署的模型能力以及硬件支持情况，进行针对性的调整。 - 安全须知： 需要警惕的是，OpenClaw 被设计为具有较高的系统访问权限，因此务必始终在可信的安全环境中运行它。
如果在配置过程中，某一步骤卡住了（比如模型服务启动失败，或者配置文件格式报错），可以告诉我具体的错误信息，我们可以一起分析解决。