OpenClaw 接入

把 QCode.cc 配成 OpenClaw 的模型供应商：openclaw.json 的 models.providers 写法、onboard 向导 Custom Provider 路径与验证方法

更新于 2026-09-18

本页目录

接入速览
前提条件
配置步骤
- 路径 A：直接编辑配置文件（推荐）
- 路径 B：onboard 向导的 Custom Provider
验证是否接通
已知限制
相关文档

最后核实：2026-09-18 · 📄 依据官方文档（OpenClaw v2026.9.4，2026-09-11 发布）

接入速览 ¶

项目	说明
可用模型	Claude ✅（Anthropic 协议）· GPT ✅ · 国产 ✅ · Gemini ⚠️（官方有 `google-generative-ai` 适配器，本批未验证）
协议与 Base URL	Anthropic：`https://api.qcode.cc/api` · OpenAI：`https://api.qcode.cc/openai/v1`
配置位置	`~/.openclaw/openclaw.json`（JSON5，网关热重载）或 `openclaw onboard` 向导
官方文档	Custom Providers · docs.openclaw.ai

OpenClaw 是运行在你自己设备上的开源 AI 助手：一个自托管 Gateway 进程接入 Discord、Telegram、Slack、iMessage 等聊天渠道，也有 macOS / Windows / Linux 客户端。它不是代码编辑器——放在这里是因为它在中文社区常被拿来当「多模型网关 + 个人助手」用，而且官方支持任意 OpenAI / Anthropic 兼容端点。

前提条件 ¶

已安装 OpenClaw（官方安装脚本 curl -fsSL https://openclaw.ai/install.sh | bash，npm 直装需 Node 24.16+，官方推荐 26+，见 README）。
一把 QCode.cc 的 cr_ 密钥（控制台创建）。不需要任何上游官方账号。
官方文档未要求 OpenClaw 有账号；模型全部由你配置的 provider 提供。

配置步骤 ¶

路径 A：直接编辑配置文件（推荐）¶

写入 ~/.openclaw/openclaw.json 的 models.providers 段。文件是 JSON5（允许注释与尾逗号），网关监视该文件自动热重载，不用重启：

{
  models: {
    mode: "merge", // keep built-in providers, append QCode
    providers: {
      qcode: {
        baseUrl: "https://api.qcode.cc/api",
        apiKey: "${QCODE_API_KEY}",
        api: "anthropic-messages",
        models: [
          { id: "claude-sonnet-5", name: "Claude Sonnet 5", input: ["text", "image"] },
        ],
      },
      qcode_openai: {
        baseUrl: "https://api.qcode.cc/openai/v1",
        apiKey: "${QCODE_API_KEY}",
        api: "openai-completions",
        models: [
          { id: "gpt-5.6", name: "GPT-5.6" },
          { id: "glm-5.3", name: "GLM-5.3" },
        ],
      },
    },
  },
}

三点说明（均出自官方 custom-providers 文档）：

apiKey 支持 ${ENV_VAR} 环境变量替换，官方建议优先用引用而不是明文 Key。
api 是请求适配器，枚举里 Anthropic 腿写作 anthropic-messages、OpenAI 腿写作 openai-completions；只填 baseUrl 不填 api 时默认按 openai-completions 处理。
模型要收图片（视觉）必须显式写 input: ["text", "image"]，否则图片只按文本引用传入。

路径 B：onboard 向导的 Custom Provider ¶

openclaw onboard --install-daemon

在 provider 列表选 Custom Provider（不在前列时在 More… 下），依次填 base URL、API Key、compatibility 与模型 ID。向导在保存前会做一次真实补全验证（官方原文：verifies a real reply before saving），能立刻暴露填错的路径。

非交互（脚本化）等价命令，以 Claude 模型为例：

openclaw onboard --non-interactive --accept-risk \
  --auth-choice custom-api-key \
  --custom-base-url "https://api.qcode.cc/api" \
  --custom-model-id "claude-sonnet-5" \
  --custom-api-key "$QCODE_API_KEY" \
  --custom-compatibility anthropic

🔴 注意两处拼写不同：onboard 旗标 --custom-compatibility 的取值是 anthropic，而配置文件里 api 的取值是 anthropic-messages（官方 onboard 文档）。

验证是否接通 ¶

走路径 B 时向导已经替你验证过（保存前有一次真实请求）。
走路径 A 时，先在任意渠道让 agent 跑一句 ping；失败先查 ~/.openclaw/openclaw.json 的 JSON5 语法（注释逗号都可能炸）。
只验路径与密钥是否送达：

curl -s -o /dev/null -w '%{http_code}\n' -X POST https://api.qcode.cc/api/v1/messages \
  -H "x-api-key: $QCODE_API_KEY"
# → 401 = 密钥无效；返回 JSON 错误以外的码 = 路径通

每一次请求（包括 OpenClaw 发出的）都会上报到 probe.qcode.cc，输入密钥即可看到实际请求的模型与返回码。仍不通按故障排查的顺序查。

已知限制 ¶

Base URL 形态的盲区：官方两个 anthropic-messages 示例（Synthetic、MiniMax）的 baseUrl 都不带 /v1（如 https://api.minimax.io/anthropic），所以本页写 https://api.qcode.cc/api；但 OpenClaw 自动拼接的确切路径官方文档未逐字说明，未经实测。如果请求返回 404，把 baseUrl 改成完整路径 https://api.qcode.cc/api/v1/messages 再试。
openai-responses 适配器官方说明「仅在后端支持 /v1/responses 时使用」；QCode 的 Responses 腿只跑 GPT 系，国产模型请走 openai-completions（协议对照见接入点与 API 格式）。
非直连的 anthropic-messages 端点上，OpenClaw 会自动抑制 Anthropic beta 请求头（官方原文），对第三方兼容网关是好事；如果你在别的工具遇到 anthropic-beta 相关 400，那不是 OpenClaw 的问题。
Gemini 腿（google-generative-ai）在官方枚举内，但本批未验证 QCode /gemini 端点的 baseUrl 形态，暂不提供配置示例。
官方文档以 GitHub main 分支为准，docs.openclaw.ai 线上渲染可能略滞后。

OpenClaw 接入

相关文档