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

2026-06-03阅读 0热度 0

OpenClaw

OpenClaw 集成自定义 Grok API 完整配置手册

前阵子在配置 OpenClaw 飞书机器人时遇上一个棘手问题：明明部署了多个 agent，机器人却始终静默，仅返回“Connection error”。排查后才意识到，根源在于缺少 AI 提供商配置。这篇文档完整记录了将 OpenClaw 从默认模型切换到自定义 Grok API 的全流程，涵盖踩坑记录与对应处理方案，供有类似需求的开发者直接参考。

环境说明

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

初始故障：机器人无响应

初始状态下，OpenClaw 飞书机器人已配置多种 agent，唯独缺少 AI 提供商这一要素。结果无论发送什么消息，机器人只返回一个冰冷的“Connection error”。逐个检查后发现 gateway 进程正常、飞书渠道配置无误，唯独 AI 提供商配置完全不存在。

分步解决：从排查到上线

第一步：定位缺失环节

通过以下命令摸清当前状态：

# 检查 gateway 运行状态
openclaw gateway status
# 查看飞书渠道连接情况
openclaw channels status

结果 gateway 与飞书渠道均正常，但查询 AI 提供商时暴露出问题：

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

根源锁定——缺少 providers 配置项。

第二步：注入 Grok API 提供商

OpenClaw 通过 models.providers 结构管理 AI 提供商。需要完整写入提供商配置，包括端点、密钥与模型定义。推荐使用 jq 操作，避免手动编辑 JSON 出错：

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

关键配置注意事项：

baseUrl：API 端点必须包含 /v1 路径，多数失败案例均源于此遗漏
apiKey：替换为你的真实密钥
api：固定为 openai-completions，表示采用 OpenAI 兼容接口
models：定义可用模型，参数可根据实际需求调整

写入后验证配置是否生效：

openclaw config get models.providers.grok

第三步：批量更新 Agent 模型指向

OpenClaw 支持多 agent 各自绑定不同模型。需要将所有 agent 的 model.primary 指向新添加的 Grok 模型。先查看现有 agent 列表：

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

输出示例：

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

接着用 jq 批量替换：

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-fast
provider=grok model=grok-4.1-fast thinking=off messageChannel=feishu

常见踩坑与解决实录

问题 1：机器人沉默不回复

表现： 飞书会话显示“New session started · model: grok/grok-4.1-fast”，但机器人始终无响应。

根因： 大概率是 baseUrl 遗漏了 /v1 路径，导致 API 路由错误。

处理方式：

# 修正 baseUrl，补上 /v1
cat ~/.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
# 重启 gateway
killall -9 openclaw-gateway

问题 2：API 返回空内容

表现： 日志中显示 "content":[]，且 usage 全部为 0。

诊断步骤：

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

处理方式： 先用 curl 直连测试 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"
# 强制终止所有 gateway 进程
killall -9 openclaw-gateway
# 或指定 PID 终止
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": []
        }
      }
    ]
  }
}

配置生效后，按此清单逐项验证

Grok 提供商已成功写入 models.providers.grok
baseUrl 包含完全路径（含 /v1）
所有用到的 agent 均已更新模型指向
Gateway 已重启并处于运行状态
日志中正确显示 provider 与 model 字段
在飞书发送测试消息，可正常收到 AI 回复

常用命令速查表

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

核心要点总结

按上述步骤操作后，OpenClaw 飞书机器人已从默认配置平滑切换至自定义 Grok API。整个流程中需重点关注：

正确构建 models.providers 层级结构
API 端点路径务必携带 /v1
逐一更新所有 agent 的模型字段
每次配置变更后必须重启 gateway

配置完毕后，机器人即可稳定使用自定义 Grok API 完成对话任务。细粒度验证每一步，多数事故都能提前规避。

参考资源

OpenClaw 官方文档
飞书 Bot 配置指南
OpenClaw GitHub 仓库