# 用 magpie 一键配置

[magpie](https://usemagpie.ai) 是一个开源的桌面工具（MIT 许可）。它在你电脑上跑一个本地网关，把 Claude Code、Codex、Gemini CLI、OpenCode 等几十种工具接到你选的服务商。在 magpie 里添加一次 2api，之后换工具、换模型都是点几下的事。

## 一键配置（推荐）

用 Claude 点第一个按钮，Key 要是「CC-Max」分组的；用 GPT 点第二个，Key 要是 GPT 的分组（见[分组](https://docs.2api.dev/start/endpoints/#分组)）。

<MagpieButtons />

点完按钮，magpie 会弹出下面这个确认框。点「获取密钥」打开 2api 的密钥页面，复制 Key 粘贴回来，再点「添加」（之前加过的话，按钮会显示「替换」）。GPT 和 Claude 都要用，就两个按钮各点一次。

![magpie 的导入确认框](../../assets/magpie/import.png)

添加好以后，到 magpie 的「Agent」页把工具接上 2api，见下面的[让工具用上 2api](#让工具用上-2api)。

## 安装 magpie

到 [usemagpie.ai](https://usemagpie.ai) 下载 macOS 版，拖进「应用程序」。也可以用命令安装：

  ```bash
  curl -fsSL https://usemagpie.ai/install.sh | sh
  ```
  到 [usemagpie.ai](https://usemagpie.ai) 下载 Windows 版安装包。安装包没有签名，第一次运行如果弹出 SmartScreen，点「更多信息」→「仍要运行」。
  ```bash
  curl -fsSL https://usemagpie.ai/install.sh | sh
  ```
  图形界面需要 GTK3 和 WebKitGTK 4.1，没有的话只能用命令行和 `magpie tui`。
  国内下载慢，可以让安装脚本走 GitHub 下载镜像或本地代理：

```bash
curl -fsSL https://usemagpie.ai/install.sh | sh -s -- --mirror https://gh-proxy.com/
curl -fsSL https://usemagpie.ai/install.sh | sh -s -- --proxy http://127.0.0.1:7890
```

## 让工具用上 2api

1. 打开「Agent」页，找到 Claude Code（或 Codex），打开右边的「接入」开关。

2. 点开右边的模型下拉框，选带 2api 图标的模型：Claude Code 选 2api Claude 下的模型，Codex 选 2api GPT 下的模型。不要选 `auto/...`，它会把请求分给别的供应商。

3. 新开一个会话再用。Codex 要完全退出再重新打开才生效。

![magpie 的 Agent 页](../../assets/magpie/agents.png)

## 确认能用

- 在「供应商」里点开 2api 那一行 →「端点」→「测试」。它会发一个很小的真实请求，会扣一点点额度。
- 或者直接在 Claude Code 里发一句话，magpie 的「路由」页能看到这次请求经过了哪个供应商。

## 手动添加

一键添加的按钮打不开 magpie 时，可以手动添加：

1. 打开 magpie，进入「供应商」→「＋ 添加供应商」→「自定义供应商」。

2. 名称填 `2api Claude` 或 `2api GPT`。

3. 按 Key 的分组填 API 地址和协议：

   | Key 的分组 | 协议 | API 地址 |
   | --- | --- | --- |
   | CC-Max | Anthropic 兼容 | `https://2api.dev` |
   | GPT 的分组 | OpenAI Responses | `https://2api.dev/v1` |

4. 粘贴 API 密钥，点「获取模型」，再点「添加」。

:::caution[两个分组分成两个供应商]
2api 的每个 Key 只属于一个分组。GPT 和 Claude 的 Key 要分别添加成两个供应商，不要把它们加进同一个供应商的多个密钥里。
:::

## 注意事项

- **magpie 要一直开着。** 工具连的是本机的 magpie 网关，退出 magpie 后会连不上。想开机自动运行：`magpie daemon install`。
- **不用了怎么恢复：** 运行 `magpie uninstall`，各工具的配置会还原。不要直接删掉 magpie，否则工具会一直指向一个不存在的本地地址。
- **开着代理软件：** Clash、Surge 等开了 TUN 或系统代理时，给 `127.0.0.0/8` 和 `::1` 加直连规则，否则会出现 502。
- **检测或测试返回 503：** 如果 Claude 分组只允许 Claude Code 客户端，magpie 的「检测协议」「测试」会被拒绝，这是正常的，Claude Code 里实际使用不受影响。
- **Codex 扣费偏多：** 有用户反馈 Codex 经过 magpie 转发时缓存命中率偏低。如果发现 Codex 扣费明显比直连多，可以改用 [Codex 手动配置](https://docs.2api.dev/clients/codex/)。

## 用命令行添加

```bash
magpie provider add "2api Claude" id=2api-claude anthropic=https://2api.dev key=sk-你的CC-Max分组Key
magpie provider add "2api GPT" id=2api-gpt url=https://2api.dev/v1 responses=https://2api.dev/v1 key=sk-你的GPT分组Key
magpie claude 2api-claude/模型名
magpie codex 2api-gpt/模型名
```

---

本页步骤参考 magpie 官方文档整理。magpie 更新很频繁，界面文字可能略有出入。