OpenClaw 集成自定义 Grok API 完整攻略(最新整理)

OpenClaw 集成自定义 Grok API 完整攻略(最新整理)需要先看清适用场景和关键步骤，避免只记结论却忽略实际限制。

OpenClaw 集成自定义 Grok API 完整指南

前言

本文记录了将 OpenClaw 飞书机器人从默认 AI 模型切换到自定义 Grok API 的完整过程，包括遇到的问题和解决方案。适合需要为 OpenClaw 配置自定义 AI 提供商的开发者参考。

环境信息

1. OpenClaw 版本：2026.2.9
2. 操作系统：macOS
3. 消息平台：飞书（Feishu）
4. 目标 AI 模型：Grok 4.1 Fast（通过自定义 API 端点）

问题背景

初始状态下，OpenClaw 飞书机器人配置了多个 agent，但缺少 AI 提供商配置，导致机器人无法正常回复消息，只显示 “Connection error”。

解决方案

第一步：诊断问题

首先检查 gateway 状态和渠道配置：

# 检查 gateway 状态openclaw gateway status# 检查飞书渠道状态openclaw channels status

发现 gateway 正常运行，飞书渠道也已配置，但缺少 AI 提供商配置：

openclaw config get providers# 输出：Config path not found: providers

第二步：添加 Grok API 配置

OpenClaw 使用 models.providers 结构来管理 AI 提供商。需要添加完整的提供商配置，包括 API 端点、密钥和模型定义。

使用 jq 命令添加配置：

cat ~/.openclaw/openclaw.json | jq '.models.providers["grok"] = {  "baseUrl": "https://apipro.maynor1024.live/v1",  "apiKey": "sk-your-api-key-here",  "api": "openai-completions",  "models": [    {      "id": "grok-4.1-fast",      "name": "Grok 4.1 Fast",      "reasoning": false,      "input": ["text"],      "cost": {        "input": 0,        "output": 0,        "cacheRead": 0,        "cacheWrite": 0      },      "contextWindow": 128000,      "maxTokens": 4096    }  ]}' > ~/.openclaw/openclaw.json.tmp && mv ~/.openclaw/openclaw.json.tmp ~/.openclaw/openclaw.json

关键配置说明：

1. baseUrl: API 端点地址，必须包含 /v1 路径
2. apiKey: API 密钥
3. api: 设置为 openai-completions 表示使用 OpenAI 兼容的 API 格式
4. models: 定义可用的模型列表

验证配置：

openclaw config get models.providers.grok

第三步：更新 Agent 模型配置

OpenClaw 支持多个 agent，每个 agent 可以配置不同的模型。需要将所有 agent 更新为使用新添加的 Grok 模型。

首先查看现有 agent 配置：

cat ~/.openclaw/openclaw.json | jq '.agents.list[] | {id: .id, primary: .model.primary}'

输出示例：

{  "id": "main-agent",  "primary": "local-antigravity/claude-opus-4-6-thinking"}{  "id": "content-agent",  "primary": "local-antigravity/claude-sonnet-4-5"}

批量更新所有 agent：

cat ~/.openclaw/openclaw.json | jq '  (.agents.list[] | select(.id == "main-agent") | .model.primary) = "grok/grok-4.1-fast" |  (.agents.list[] | select(.id == "content-agent") | .model.primary) = "grok/grok-4.1-fast" |  (.agents.list[] | select(.id == "tech-agent") | .model.primary) = "grok/grok-4.1-fast" |  (.agents.list[] | select(.id == "ainews-agent") | .model.primary) = "grok/grok-4.1-fast"' > ~/.openclaw/openclaw.json.tmp && mv ~/.openclaw/openclaw.json.tmp ~/.openclaw/openclaw.json

同时更新默认模型配置：

openclaw config set agents.defaults.model.primary grok/grok-4.1-fast

第四步：重启 Gateway

配置修改后需要重启 gateway 使其生效：

# 停止所有 gateway 进程killall -9 openclaw-gateway# 等待几秒让进程完全停止sleep 3# 如果使用 ClawX，gateway 会自动重启# 否则手动启动：openclaw gateway

验证 gateway 状态：

openclaw gateway status

第五步：验证配置

查看日志确认新配置已加载：

tail -100 /tmp/openclaw/openclaw-2026-03-01.log | grep -i "grok"

应该看到类似输出：

agent model: grok/grok-4.1-fastprovider=grok model=grok-4.1-fast thinking=off messageChannel=feishu

常见问题排查

问题 1：机器人不回复消息

症状： 飞书显示 “New session started · model: grok/grok-4.1-fast”，但没有实际回复。

原因： API 端点配置错误，通常是 baseUrl 缺少 /v1 路径。

解决方案：

# 修正 baseUrlcat ~/.openclaw/openclaw.json | jq '.models.providers.grok.baseUrl = "https://your-api-endpoint.com/v1"' > ~/.openclaw/openclaw.json.tmp && mv ~/.openclaw/openclaw.json.tmp ~/.openclaw/openclaw.json# 重启 gatewaykillall -9 openclaw-gateway

问题 2：API 调用返回空内容

症状： 日志显示 "content":[] 和 usage 全为 0。

诊断方法：

# 查看 session 日志ls -lt ~/.openclaw/agents/main-agent/sessions/*.jsonl | head -1tail -5 

解决方案： 检查 API 端点是否可访问：

curl -X POST "https://apipro.maynor1024.live/v1/chat/completions"   -H "Content-Type: application/json"   -H "Authorization: Bearer your-api-key-here"   -d '{    "model": "grok-4.1-fast",    "messages": [{"role": "user", "content": "hi"}],    "max_tokens": 10  }'

问题 3：Gateway 无法启动（端口占用）

症状：Port 18789 is already in use

解决方案：

# 查找占用端口的进程ps aux | grep "openclaw.*gateway"# 强制停止killall -9 openclaw-gateway# 或者停止特定进程kill -9 

配置文件结构参考

完整的 ~/.openclaw/openclaw.json 配置结构：

{  "models": {    "mode": "merge",    "providers": {      "grok": {        "baseUrl": "https://apipro.maynor1024.live/v1",        "apiKey": "sk-your-api-key-here",        "api": "openai-completions",        "models": [          {            "id": "grok-4.1-fast",            "name": "Grok 4.1 Fast",            "reasoning": false,            "input": ["text"],            "cost": {              "input": 0,              "output": 0,              "cacheRead": 0,              "cacheWrite": 0            },            "contextWindow": 128000,            "maxTokens": 4096          }        ]      }    }  },  "agents": {    "defaults": {      "model": {        "primary": "grok/grok-4.1-fast"      }    },    "list": [      {        "id": "main-agent",        "model": {          "primary": "grok/grok-4.1-fast",          "fallbacks": []        }      }    ]  }}

验证清单

配置完成后，按以下清单验证：

1. Grok 提供商配置已添加到 models.providers.grok
2. baseUrl 包含完整路径（含 /v1）
3. 所有需要的 agent 已更新模型配置
4. Gateway 已重启并正常运行
5. 日志中显示正确的 provider 和 model
6. 在飞书中发送测试消息能正常收到回复

最佳实践

1. 备份配置文件：修改前先备份 ~/.openclaw/openclaw.json
2. 使用 jq 工具：避免手动编辑 JSON 文件，减少语法错误
3. 查看日志：遇到问题先查看 /tmp/openclaw/openclaw-*.log
4. 测试 API：配置前先用 curl 测试 API 端点是否可用
5. 逐步验证：每完成一步都验证配置是否正确

相关命令速查

# 查看配置openclaw config get models.providersopenclaw config get agents.list# 修改配置openclaw config set # Gateway 管理openclaw gateway statusopenclaw gateway restartopenclaw gateway stop# 查看日志tail -f /tmp/openclaw/openclaw-$(date +%Y-%m-%d).logtail -f ~/.openclaw/logs/gateway.log# 查看渠道状态openclaw channels statusopenclaw channels list

总结

通过本文的步骤，成功将 OpenClaw 飞书机器人从默认配置切换到自定义 Grok API。关键点包括：

1. 正确配置 models.providers 结构
2. 确保 API 端点包含完整路径
3. 更新所有 agent 的模型配置
4. 重启 gateway 使配置生效

配置完成后，机器人可以正常使用自定义的 Grok API 进行对话，实现了灵活的 AI 模型切换。

参考资源

1. OpenClaw 官方文档
2. 飞书 Bot 配置指南
3. OpenClaw GitHub 仓库

作者注：这篇内容以实际配置过程整理，如有问题欢迎反馈。