OpenClaw 配置外部模型完全指南

副标题：3 步接入第三方大模型，API Key/配置文件/Web UI 三种方式一文讲清

开头：为什么需要配置外部模型？

你是不是也遇到过这些痛点：

❌ 想用国产大模型（Kimi、Qwen、GLM），但不知道如何接入
❌ 有本地部署的 Ollama/vLLM，却连不上 OpenClaw
❌ 看到一堆 provider 配置示例，不知道哪个适合自己
❌ 配置完测试失败，找不到问题出在哪

本文价值： 用一篇教程，带你彻底搞懂 OpenClaw 配置外部模型的全部方法。无论你是想用云端 API、本地模型，还是自建代理，都能找到对应的配置方案。

一、配置前的准备工作

1.1 确认你的模型类型

OpenClaw 支持两大类模型接入：

类型	代表提供商	配置方式
内置提供商	OpenAI、Anthropic、Google、Moonshot 等	只需设置 API Key
自定义提供商	本地 Ollama、vLLM、LM Studio 等	需配置 baseUrl + API 类型

1.2 获取必要的凭证

云端 API：从提供商官网获取 API Key（如 OPENAI_API_KEY、MOONSHOT_API_KEY）
本地模型：确保本地服务已启动（如 Ollama 默认运行在 http://127.0.0.1:11434）

二、方法一：命令行快速配置（推荐新手）

OpenClaw 提供了交互式配置向导，适合大多数内置提供商。

步骤 1：运行配置向导

openclaw onboard

步骤 2：选择认证方式

根据提示选择你的模型提供商，例如：

# OpenAI API Key
openclaw onboard --auth-choice openai-api-key

# Moonshot (Kimi)
openclaw onboard --auth-choice moonshot-api-key

# Ollama 本地模型
openclaw onboard --auth-choice ollama

步骤 3：设置默认模型

# 查看可用模型列表
openclaw models list

# 设置默认模型
openclaw models set moonshot/kimi-k2.5

↑ 截图 1：运行 openclaw onboard 后的交互式菜单，显示各提供商选项

三、方法二：修改配置文件（高级用户）

对于自定义提供商或需要精细控制的场景，直接编辑配置文件更灵活。

步骤 1：找到配置文件

配置文件位于：~/.openclaw/openclaw.json

步骤 2：添加自定义提供商配置

示例 1：配置 Moonshot（Kimi）

{
  "env": {
    "MOONSHOT_API_KEY": "sk-xxxxxxxxxxxxxx"
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "moonshot/kimi-k2.5"
      }
    }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "moonshot": {
        "baseUrl": "https://api.moonshot.ai/v1",
        "apiKey": "${MOONSHOT_API_KEY}",
        "api": "openai-completions",
        "models": [{
          "id": "kimi-k2.5",
          "name": "Kimi K2.5",
          "contextWindow": 128000,
          "maxTokens": 8192
        }]
      }
    }
  }
}

↑ 截图 2：openclaw.json 配置文件中的 moonshot 提供商配置，高亮关键字段

示例 2：配置本地 Ollama

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "ollama/llama3.3"
      }
    }
  }
}

↑ 截图 3：配置文件关键代码段，包含 env、agents.defaults.model、models.providers 三个区域

步骤 3：保存并重启 Gateway

配置文件支持热重载，保存后 Gateway 会自动应用更改。如需手动重启：

openclaw gateway restart

四、方法三：Web UI 界面配置（可视化操作）

OpenClaw 提供了 Control UI，适合不喜欢编辑配置文件的用户。

步骤 1：打开 Control UI

在浏览器中访问：http://127.0.0.1:18789

步骤 2：进入 Config 标签页

点击顶部导航栏的 Config 标签，进入配置界面。

步骤 3：配置模型参数

在 Agents → Defaults → Model 区域设置 primary 模型
在 Models → Providers 区域添加自定义提供商
使用 Raw JSON 编辑器可直接粘贴完整配置

步骤 4：保存配置

点击 Save 按钮，配置会自动应用到 Gateway。

五、验证配置是否成功

方法 1：命令行测试

# 查看当前默认模型
openclaw models list

# 发送测试消息
openclaw chat "你好，请回复一个测试消息"

方法 2：在聊天中测试

直接在微信/Telegram/Discord 等渠道发送消息，观察是否正常响应。

方法 3：查看 Gateway 日志

openclaw logs --follow

观察是否有模型调用成功的日志输出。

↑ 截图 4：配置验证成功，模型列表显示 primary 模型，测试对话正常响应

六、常见问题与避坑指南

❓ 问题 1：配置后 Gateway 无法启动

原因：配置文件格式错误或 schema 验证失败

解决：

# 运行诊断命令
openclaw doctor

# 自动修复配置
openclaw doctor --fix

❓ 问题 2：API Key 无效或权限不足

原因：API Key 填写错误或未在提供商后台配置 IP 白名单

解决：

检查 API Key 是否正确复制（注意前后空格）
登录提供商后台，将服务器 IP 加入白名单
检查账户余额是否充足

❓ 问题 3：本地模型连接超时

原因：本地服务未启动或端口被占用

解决：

# 检查 Ollama 是否运行
ollama list

# 检查端口是否监听
curl http://127.0.0.1:11434/v1/models

# 重启本地服务
ollama serve

❓ 问题 4：模型响应 truncated 或上下文不足

原因：配置的 contextWindow 超过模型实际支持

解决：在配置中明确设置合理的 contextWindow 值

🚫 避坑指南

坑点	正确做法
直接复制网上配置不修改	根据实际提供商修改 baseUrl 和 API Key
忘记设置 models.mode: "merge"	添加自定义提供商时务必设置，否则内置模型会失效
API Key 明文提交到 Git	使用 ${ENV_VAR} 引用环境变量
本地模型未启动就测试	先用 curl 测试本地服务是否正常
配置文件格式错误	使用 JSON5 语法检查工具验证

结语

配置外部模型是使用 OpenClaw 的第一步，也是最重要的一步。无论你选择哪种方式，记住三个关键点：

选对提供商类型（内置 vs 自定义）
配置正确的认证信息（API Key 或 OAuth）
验证配置是否生效（测试对话）

如果遇到问题，运行 openclaw doctor 诊断，或查阅官方文档：https://docs.openclaw.ai

📌 本文提到的配置示例已整理成 gist，关注公众号回复"openclaw 配置"获取下载链接。