# magpie 接入 QCode

> **最后核实**：2026-10-27 · 📄 依据官方文档（magpie v0.1.1680，2026-10-27 发布）· QCode 接入按 magpie 0.1.1677 实测（✅ Claude Code 2.1.311、Codex CLI 0.164.0）

## 接入速览

| 项目 | 说明 |
|---|---|
| 可用模型 | Claude ✅（走 `anthropic` 地址）· GPT ✅（走 `chat` / `responses`）· 国产模型 ✅（走 `anthropic` / `chat`）· Gemini ❌：QCode 暂不提供 Gemini 系列，请改用 Claude、GPT 或国产模型 |
| 三个地址 | `anthropic`：`https://api.qcode.cc/api` · `chat`：`https://api.qcode.cc/openai/v1` · `responses`：`https://api.qcode.cc/openai` |
| 配置入口 | 导入链接（桌面应用 / 网页可点链接）· `magpie provider add` 一条命令 · App 的 Providers → Add provider |
| 官方文档 | [usemagpie.ai](https://usemagpie.ai) · [Docs](https://usemagpie.ai/docs) · [Import links](https://usemagpie.ai/docs/import) |

## magpie 是什么、和 CC Switch 有什么不同

magpie 在本机运行一个网关（`127.0.0.1:3425`），支持 OpenAI、Anthropic 与 Gemini 三种 API，并在它们之间转换，流式输出与工具调用都包括在内；你在 magpie 里给某个 agent 选定模型后，magpie 把模型写进该 agent 自己的配置文件。因此 Claude Code、Codex 连的是本机网关，QCode 的 key 保存在 magpie 里，由网关把请求送到 QCode。

和 CC Switch 的结构性区别只有一句：[CC Switch](/docs/ide/cc-switch) 把端点和 Key 写进各客户端自己的配置，客户端直接连服务商；magpie 让客户端连本机网关，由网关转发。

## 用哪条协议

| magpie 字段 | magpie 里的含义 | 填 QCode |
|---|---|---|
| `anthropic` | Anthropic Messages base URL，根路径，不带 `/v1` | `https://api.qcode.cc/api` |
| `chat`（CLI 里叫 `url`） | OpenAI Chat Completions base URL，以 `/v1` 结尾 | `https://api.qcode.cc/openai/v1` |
| `responses` | OpenAI Responses base URL | `https://api.qcode.cc/openai` |

**Claude 只走 `/api`，OpenAI 兼容地址不提供 Claude。** 把 `claude-*` 填进 chat 或 responses，QCode 会返回 `model_not_available_on_endpoint`，这个校验发生在鉴权之前。GPT 走 OpenAI 的 chat 与 responses 两条；国产模型 chat 与 anthropic 都能走。

亚洲 / 北美接入点把域名换成 `asia.qcode.cc` / `us.qcode.cc`，路径不变；三个域名业务能力完全一致，差异只在网络路由。

magpie 官方示例把 `responses` 写成以 `/v1` 结尾的 base URL；接 QCode 时填 `https://api.qcode.cc/openai`（与 QCode 的 Codex 配置里 base_url 相同），2026-10-27 按 magpie 0.1.1677 实测可用。

## 安装

官方安装命令：

```bash
curl -fsSL https://usemagpie.ai/install.sh | sh
```

安装脚本把 `magpie` 命令放进 `~/.local/bin`，应用按平台放好（macOS 在 `/Applications`，Linux 在应用菜单）。Windows 上 `magpie.exe` 接受同样的命令；只要终端版时，取最新 release 里的 `magpie-cli-windows-amd64.exe`。magpie 提供 macOS、Windows、Linux 的菜单栏应用、窗口、TUI、Web UI 与 CLI。

## 添加 QCode

**方式 A：导入链接（桌面应用与网页）**

magpie 要求每个参数值做 URL 编码。下面是填好 QCode 的导入链接，不含 key：

```
magpie://import?name=QCode&anthropic=https%3A%2F%2Fapi.qcode.cc%2Fapi&chat=https%3A%2F%2Fapi.qcode.cc%2Fopenai%2Fv1&responses=https%3A%2F%2Fapi.qcode.cc%2Fopenai&models=claude-opus-5-5%2Cclaude-sonnet-5-5%2Cclaude-haiku-5-5%2Cgpt-6.1-sol%2Cgpt-5.6-sol&website=https%3A%2F%2Fqcode.cc&keys=https%3A%2F%2Fqcode.cc%2Fdashboard
```

网页里改用可点形式，参数放在 `#` 后面（浏览器不会把 `#` 后的内容发给服务器；没装 magpie 时这个链接会提供下载）：

```
https://usemagpie.ai/import#name=QCode&anthropic=https%3A%2F%2Fapi.qcode.cc%2Fapi&chat=https%3A%2F%2Fapi.qcode.cc%2Fopenai%2Fv1&responses=https%3A%2F%2Fapi.qcode.cc%2Fopenai&models=claude-opus-5-5%2Cclaude-sonnet-5-5%2Cclaude-haiku-5-5%2Cgpt-6.1-sol%2Cgpt-5.6-sol&website=https%3A%2F%2Fqcode.cc&keys=https%3A%2F%2Fqcode.cc%2Fdashboard
```

导入链接里不带 key 时，按官方说明由用户在 magpie 的对话框里粘贴 key；按 Add 之前不会保存。终端里执行不带 key 的 `magpie import` 只会显示将要添加的内容、不会保存（2026-10-27 实测），终端用户请直接用方式 B。已保存的 provider 要换 key 时，用 `magpie provider key qcode cr_xxx`。

**方式 B：终端里一条命令（实测通过）**

```bash
magpie provider add QCode anthropic=https://api.qcode.cc/api url=https://api.qcode.cc/openai/v1 responses=https://api.qcode.cc/openai key=cr_xxx
```

**方式 C：App 界面**

打开 Providers 标签，点 ＋ Add provider，选 Custom（官方文案 `Custom · any compatible URL`），填名称、OpenAI compatible base URL（以 `/v1` 结尾）和 / 或 Anthropic compatible base（根路径），再填 key 并保存。

## 选模型

```bash
magpie claude qcode/claude-sonnet-5-5        # 主模型
magpie claude opus qcode/claude-opus-5-5     # Claude Code 的 opus 槽
magpie codex qcode/gpt-6.1-sol               # Codex
magpie claude default                        # 恢复 Claude Code 原来的配置
magpie codex default                         # 恢复 Codex 原来的配置
```

magpie 写进 `~/.claude/settings.json` 的是本机网关地址（`ANTHROPIC_BASE_URL` 为 `http://127.0.0.1:3425`）和 token `magpie`；QCode 的 key 保存在 magpie 里，不写进 Claude Code 的配置。只设主模型时，opus 槽也会跟着设成同一个模型；想让 opus 槽用 Opus，要另外执行 `magpie claude opus qcode/claude-opus-5-5`。haiku 槽由 magpie 自动设为 `qcode/claude-haiku-5-5`。

添加 provider 时没有指定 `models=`，magpie 默认只放出模型列表的前 24 个（实测输出 `24 of 29 models`）。用 `magpie provider models qcode <id> <id> …` 选要放出的模型，例如：

```bash
magpie provider models qcode claude-opus-5-5 claude-sonnet-5-5 claude-haiku-5-5 gpt-6.1-sol gpt-5.6-sol
```

推荐的 ID 有 `claude-opus-5-5`、`claude-sonnet-5-5`、`claude-haiku-5-5`、`gpt-6.1-sol`、`gpt-5.6-sol`。在售模型以 https://qcode.cc/models 为准。按 token 计费，各模型单价见 https://qcode.cc/models。

## 验证

```bash
magpie healthcheck
magpie provider test qcode
```

`magpie healthcheck` 在网关能应答时退出码为 0。`magpie provider test qcode` 对 chat、responses、anthropic 各发一个极小请求并显示延迟。

当 `models` 的第一个是 Claude 模型时，chat 与 responses 两行会显示 `✗ 400 · Model 'claude-opus-5-5' is not available on this endpoint.`——这是 QCode 的正常行为：Claude 只走 Anthropic Messages 端点，只要 anthropic 一行是 ✓ 就说明 Claude 通了；GPT 是否通，在 `magpie codex qcode/gpt-6.1-sol` 之后实际跑一次最直接。

然后在 Claude Code 里发一句「ping」，在 Codex 里让它读一个文件。截至 2026-10-27 实测，经 magpie 的 Claude 请求与直连 QCode 基本一致，提示缓存照常生效；Codex 走 Responses 接口。

## 常见问题

### 网关没开，Claude Code 连不上

先跑 `magpie healthcheck`，退出码为 0 说明网关在应答。网关随应用运行，关掉窗口后它留在菜单栏或托盘；也可以 `magpie serve` 只跑网关，或用 `magpie daemon install` 装成服务（Linux 用 systemd，macOS 用 launchd）。

### chat 与 responses 两行 400，是不是配错了

不是，前提是 anthropic 一行是 ✓。QCode 的 Claude 模型只走 Anthropic Messages 端点，测试命令拿同一个 Claude 模型去请求 chat 与 responses，QCode 会按设计返回 400。GPT 是否可用，按 `magpie codex qcode/gpt-6.1-sol` 后实际跑一次判断。

### 为什么只看到一部分模型

没有指定 `models=` 时 magpie 只放出前 24 个。用 `magpie provider models qcode …` 把要用的 ID 选出来；在售清单以 https://qcode.cc/models 为准。

### 怎么恢复原来的 Claude Code 配置

运行 `magpie claude default`，或在模型选择器里选回 agent 自己的模型。magpie 会移除它写入的内容，并还原它替换掉的原值。

### Codex 的推理档怎么调

用 `magpie codex effort <档位>`，例如 `magpie codex effort high`；`magpie codex effort` 可以查看当前值。也可以直接写档位，例如 `magpie codex xhigh`。

### 隐私遮罩是什么，默认开吗

隐私遮罩默认关闭，在 Settings → Privacy 里打开。打开后，API key、私钥、token、邮箱，以及校验和正确的卡号与证件号，会在请求离开本机前换成占位符（例如 `{{API_KEY_k3v9x2mq}}`），回复里再换回原值；这些值只保存在内存里。

### 匿名统计怎么关

在 Settings → Privacy 关掉 Count me as a user，或设置 `DO_NOT_TRACK=1` / `MAGPIE_NO_STATS=1`。magpie 每天会发一次匿名使用计数，内容只有随机 id、版本、系统，以及用到的 agent、provider 与模型的内置 id。

## 相关文档

- [CC Switch 配置](/docs/ide/cc-switch)：把端点和 Key 写进各客户端配置的桌面工具
- [Codex 完整教程](/docs/ide/codex)：`~/.codex/config.toml` 的 Responses 写法
- [接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths)：三条协议与三个接入域
- [环境变量配置](/docs/getting-started/environment)：`ANTHROPIC_BASE_URL` 等变量的用法