OpenClaw集成自定义Grok API完整教程与配置攻略

时间：2026-08-21 | 作者：实验室老王 | 阅读：0

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

如果 OpenClaw 飞书机器人一直只返回“Connection error”，问题很可能不在 gateway，也不在飞书渠道，而是缺少 AI 提供商配置。

前段时间在折腾 OpenClaw 飞书机器人时，我就遇到了这个问题：虽然配置了多个 agent，但机器人始终无法正常回复消息。排查后发现，根本原因在于缺少 AI 提供商的配置。

本文将完整记录把 OpenClaw 从默认 AI 模型切换到自定义 Grok API 的全过程，包括踩过的坑和相应的解决方案，供有类似需求的开发者参考。

运行环境

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

问题表现

初始状态下，OpenClaw 飞书机器人配置了不少 agent，但唯独缺了 AI 提供商这一环。

结果就是，不管怎么发消息，机器人都只回复一个冷冰冰的“Connection error”。检查后发现，gateway 运行正常，飞书渠道也配置好了，但就是没有 AI 提供商配置。

解决思路

核心处理步骤只有四件事：确认问题、补齐 providers 配置、更新 agent 模型、重启 gateway。

第一步：先确认问题位置

可以先用下面几条命令排查基础状态：

# 检查 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 提供商。

这里需要添加完整的提供商配置，包括 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

这部分有几个关键点：

baseUrl：API 端点地址，必须包含 /v1 路径，不少问题就出在这里
apiKey：换成你自己的 API 密钥
api：设置为 openai-completions，表示使用 OpenAI 兼容的 API 格式
models：定义可用的模型列表，这里的参数可以根据实际情况调整

配置完成后，可以先验证一下：

openclaw config get models.providers.grok

第三步：更新 Agent 模型配置

OpenClaw 支持多个 agent，每个 agent 都可以配置不同的模型。

如果你要统一切换到 Grok，就需要把相关 agent 都更新为新添加的模型。先查看现有 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"
}

然后批量更新所有 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

重启后，再确认一下状态：

openclaw gateway status

第五步：验证配置是否生效

最后一步是查日志，确认新模型和新 provider 已被正确加载：

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”，但机器人就是不说话。

原因：十有八九是 API 端点配置不对，最常见的就是 baseUrl 漏掉了 /v1 路径。

解决方案：

# 修正 baseUrl
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"
# 强制停止
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": []
        }
      }
    ]
  }
}

配置完成后检查这几项

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

建议养成的习惯

备份配置文件：修改前先备份 ~/.openclaw/openclaw.json，给自己留条后路
多用 jq 工具：尽量别手动编辑 JSON 文件，语法错误真的让人头大
善用日志：遇到问题先翻 /tmp/openclaw/openclaw-*.log
先测试 API：配置前用 curl 确认 API 端点是否可用
逐步验证：每完成一步都确认一下配置是否正确

常用命令速查

# 查看配置
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