🦞 让小龙虾跑起来：用 CopilotX 驱动 OpenClaw 的调试之旅

晚上 10 点，当 WebChat 窗口里终于显示出 AI 的回复时，我忍不住喊出了"终终终于跑通啦！" 这一刻，持续数小时的调试之旅终于画上了圆满的句号。

🎬 背景

OpenClaw 是一个开源的个人 AI 助手框架——想象一下，一个能同时连接 WhatsApp、Telegram、Discord、Slack、Signal、iMessage、微信、Teams 的 AI 管家，通过统一的 Gateway 控制平面，让你在任何消息渠道都能与 AI 对话。

它的名字很有意思，叫"小龙虾"（Claw = 爪子/钳子）。🦞

问题是：OpenClaw 需要 LLM 来驱动对话，官方默认支持 Anthropic 和 OpenAI。但这些 API 都要钱——而我手头有一个"无限 Claude API"的神器：CopilotX。

CopilotX 是我之前构建的一个项目，它通过 GitHub Copilot 的内部 API 提供 Anthropic 兼容的 /v1/messages 端点，部署在 https://api.polly.wang。理论上，只要配置正确，就能让 OpenClaw 白嫖无限的 Claude。

说干就干。

🔧 第一个坑：Gateway Token

安装 OpenClaw 很顺利：

cd X-Workspace/openclaw
pnpm install
pnpm openclaw gateway

Gateway 启动了，WebChat 也在 http://127.0.0.1:18789/__openclaw__/chat/ 打开了。但输入消息后，界面提示：

unauthorized: gateway token missing

翻了一下配置文档，发现 WebChat 需要认证。在 ~/.openclaw/openclaw.json 添加：

{
  "gateway": {
    "mode": "local",
    "auth": { "token": "polly-openclaw-local-dev" },
    "controlUi": { "allowInsecureAuth": true }
  }
}

重启后，在 WebChat 输入 token，认证通过。✅

🌐 第二个坑：配置自定义 Provider

现在要让 OpenClaw 使用 CopilotX 而不是 Anthropic。我最初的思路是设置环境变量：

export ANTHROPIC_BASE_URL=https://api.polly.wang/v1
export ANTHROPIC_API_KEY=polly-copilotx-xxx

然而，完全不生效。日志显示请求依然发往 https://api.anthropic.com。

深入研究代码后发现，OpenClaw 使用的 @mariozechner/pi-ai SDK 不从环境变量读取 baseUrl——它从配置文件的 model.baseUrl 字段读取。

正确的配置方式是创建自定义 Provider：

{
  "models": {
    "mode": "merge",
    "providers": {
      "copilotx": {
        "baseUrl": "https://api.polly.wang/v1",
        "api": "anthropic-messages",
        "apiKey": "polly-copilotx-xxx",
        "models": [
          {
            "id": "claude-opus-4-6",
            "name": "Claude Opus 4.6 (CopilotX)",
            "contextWindow": 200000,
            "maxTokens": 32000,
            "input": ["text", "image"],
            "reasoning": true
          }
        ]
      }
    }
  }
}

注意这里有个关键细节：必须包含 models 数组！我第一次漏掉了，导致配置校验失败：

models.providers.copilotx.models: Invalid input: expected array, received undefined

🎯 第三个坑：默认模型未设置

配置好 Provider 后，发送消息还是失败：

No API key found for provider "anthropic"

日志显示：

agent model: anthropic/claude-opus-4-6

虽然我配置了 copilotx Provider，但默认模型还是 anthropic！需要显式设置：

pnpm openclaw models set copilotx/claude-opus-4-6

现在日志变成了：

agent model: copilotx/claude-opus-4-6

进步了！但发消息依然没有回复，日志也没有错误。

🔍 第四个坑：404 Not Found

最折磨人的一个坑。表面上一切正常——请求发送了，1.5秒后完成，没有报错。但 WebChat 就是不显示 AI 回复。

我去翻 session 文件 ~/.openclaw/agents/main/sessions/*.jsonl，终于找到了真相：

{
  "role": "assistant",
  "content": [],
  "stopReason": "error",
  "errorMessage": "404 {\"detail\":\"Not Found\"}"
}

404！ 请求 URL 有问题。

灵光一闪，我测试了两个 URL：

# 这个有效（200）
curl https://api.polly.wang/v1/messages

# 这个 404
curl https://api.polly.wang/v1/v1/messages

问题找到了！Anthropic SDK 会自动追加 /v1，而我的 baseUrl 已经带了 /v1，导致最终变成 /v1/v1/messages。

修复很简单——把 baseUrl 从 https://api.polly.wang/v1 改成 https://api.polly.wang：

{
  "baseUrl": "https://api.polly.wang"
}

同时更新 agent 的 models.json：

cat ~/.openclaw/agents/main/agent/models.json | \
  jq '.providers.copilotx.baseUrl = "https://api.polly.wang"' > /tmp/tmp.json && \
  mv /tmp/tmp.json ~/.openclaw/agents/main/agent/models.json

重启 Gateway——

终于跑通了！ 🎉

📊 最终配置清单

经过这次调试，完整的配置如下：

~/.openclaw/openclaw.json

{
  "models": {
    "mode": "merge",
    "providers": {
      "copilotx": {
        "baseUrl": "https://api.polly.wang",
        "api": "anthropic-messages",
        "apiKey": "your-api-key",
        "models": [
          {
            "id": "claude-opus-4-6",
            "name": "Claude Opus 4.6 (CopilotX)",
            "contextWindow": 200000,
            "maxTokens": 32000,
            "input": ["text", "image"],
            "reasoning": true
          }
        ]
      }
    }
  },
  "gateway": {
    "mode": "local",
    "auth": { "token": "your-token" },
    "controlUi": { "allowInsecureAuth": true }
  }
}

设置默认模型

pnpm openclaw models set copilotx/claude-opus-4-6

启动

pnpm openclaw gateway
# 访问 http://127.0.0.1:18789/__openclaw__/chat/

💡 踩坑速查表

🤔 反思

这次调试让我体会到几点：

1. 日志是金矿：OpenClaw 的 trace 级别日志非常详细，/tmp/openclaw/*.log 里藏着所有真相

2. Session 文件会说话：API 返回的错误信息被保存在 .jsonl 文件里，而不是显示在界面上

3. SDK 会自动追加路径：这是个常见的坑，Anthropic SDK、OpenAI SDK 都会做类似的事情

4. 两层配置：OpenClaw 有全局配置（~/.openclaw/openclaw.json）和 agent 级配置（~/.openclaw/agents/main/agent/models.json），都要更新

现在，我拥有了一个用无限 Claude API 驱动的个人 AI 助手网关。可以通过 WhatsApp、Telegram、Discord 等任何渠道与 AI 对话，而成本是——零。

小龙虾，跑起来了！🦞

📱 后记：接入 Telegram（2月12日更新）

第二天，我决定让小龙虾走出 WebChat，接入 Telegram。

创建 Telegram Bot

1. 在 Telegram 搜索 @BotFather
2. 发送 /newbot，给 bot 起名（我取了"小龙虾助手"）
3. 设置 username：xiaolongxia_ai_bot
4. 复制 BotFather 返回的 token

配置 Telegram Channel

在 ~/.openclaw/openclaw.json 的 channels 部分添加：

{
  "channels": {
    "telegram": {
      "botToken": "your-telegram-bot-token",
      "dmPolicy": "allowlist",
      "allowFrom": [your-telegram-user-id],
      "proxy": "http://127.0.0.1:7890"
    }
  },
  "plugins": {
    "entries": {
      "telegram": { "enabled": true }
    }
  }
}

几个注意点：

• dmPolicy 只接受 "pairing" / "allowlist" / "open" / "disabled"，我之前写成 "allowFrom" 导致配置校验失败
• 获取你的 Telegram 用户 ID：在 Telegram 搜索 @userinfobot，发任意消息即可获取
• 网络问题：国内无法直连 Telegram API，需要配置 proxy（我用 ClashX，端口 7890）
• plugins.entries.telegram.enabled 必须设为 true，否则插件不会启动

Telegram 踩坑速查表

配置完成后重启 Gateway，去 Telegram 搜索 @xiaolongxia_ai_bot，发消息——收到 AI 回复了！

现在小龙虾真的跑起来了：WebChat + Telegram 双渠道，全部由 CopilotX 驱动！🦞

如果你也想尝试这个配置，OpenClaw 项目地址：https://github.com/openclaw/openclaw