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

目录

• OpenClaw 集成自定义 Grok API 完整指南
• 前言
• 环境信息
• 问题背景
• 解决方案
• 第一步：诊断问题
• 第二步：添加 Grok API 配置
• 第三步：更新 Agent 模型配置
• 第四步：重启 Gateway
• 第五步：验证配置
• 常见问题排查
• 问题 1：机器人不回复消息
• 问题 2：API 调用返回空内容
• 问题 3：Gateway 无法启动（端口占用）
• 配置文件结构参考
• 验证清单
• 最佳实践
• 相关命令速查
• 总结
• 参考资源

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

• OpenClaw 版本：2026.2.9
• 操作系统：macOS
• 消息平台：飞书（Feishu）
• 目标 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

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

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 进程
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

症状： 飞书显示 “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

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

诊断方法：

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

解决方案： 检查 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
  }'

症状： Port 18789 is already in use

解决方案：

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

完整的 ~/.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
• 在飞书中发送测试消息能正常收到回复

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

# 查看配置
openclaw config get models.providers
openclaw config get agents.list
# 修改配置
openclaw config set <path> <value>
# 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。关键点包括：

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

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

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

作者注：本文基于实际配置过程整理，如有问题欢迎反馈。

到此这篇关于OpenClaw 集成自定义 Grok API 完整攻略(最新整理)的文章就介绍到这了,更多相关OpenClaw 集成Grok API内容请搜索风君子博客以前的文章或继续浏览下面的相关文章，希望大家以后多多支持风君子博客！