# OpenClaw 接入

> **最后核实**：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](https://github.com/openclaw/openclaw/blob/main/docs/concepts/model-providers/custom-providers.md) · [docs.openclaw.ai](https://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](https://github.com/openclaw/openclaw#readme)）。
- 一把 QCode.cc 的 `cr_` 密钥（[控制台](https://qcode.cc/dashboard) 创建）。**不需要**任何上游官方账号。
- 官方文档未要求 OpenClaw 有账号；模型全部由你配置的 provider 提供。

## 配置步骤

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

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

```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 文档](https://github.com/openclaw/openclaw/blob/main/docs/concepts/model-providers/custom-providers.md)）：

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

### 路径 B：onboard 向导的 Custom Provider

```bash
openclaw onboard --install-daemon
```

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

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

```bash
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 文档](https://github.com/openclaw/openclaw/blob/main/docs/cli/onboard.md)）。

## 验证是否接通

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

```bash
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 错误以外的码 = 路径通
```

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

## 已知限制

- **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 格式](/docs/getting-started/endpoints-and-api-paths)）。
- 非直连的 `anthropic-messages` 端点上，OpenClaw 会自动抑制 Anthropic beta 请求头（官方原文），对第三方兼容网关是好事；如果你在别的工具遇到 `anthropic-beta` 相关 400，那不是 OpenClaw 的问题。
- Gemini 腿（`google-generative-ai`）在官方枚举内，但本批未验证 QCode `/gemini` 端点的 baseUrl 形态，暂不提供配置示例。
- 官方文档以 GitHub `main` 分支为准，docs.openclaw.ai 线上渲染可能略滞后。

## 相关文档

- [接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths) —— 四条协议腿与 Base URL 填法
- [工具兼容总览](/docs/ide/tool-compatibility) —— 各工具协议支持一览
- [CC Switch 配置](/docs/ide/cc-switch) —— 图形化切换 Claude Code / Codex 供应商
- [国产模型接入](/docs/usage/cn-models) —— GLM / Kimi / DeepSeek / Qwen 的在售 id
- [故障排查指南](/docs/reference/troubleshooting)