AI > openclaw >

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

2026-03-02 11:12:06 秒懂AI+

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

前言

本文记录了将 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

第二步：添加 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 可以配置不同的模型。需要将所有 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-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 <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
  }'

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

症状： 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
在飞书中发送测试消息能正常收到回复

最佳实践

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

总结

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

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

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

参考资源

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

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