手把手教程：一个 Key 接上所有 Agent，用开源 magpie 统一接入 API 网关（以 Claude Code、Codex、Pi、Hermes 为例）

作者注：这是一篇可以照着做完的教程。读完并跟着做一遍，你会得到一套“一个 Key、一个网关地址、装了几个 Agent 就管几个”的配置；以后换模型、轮换 Key，只需要改一个地方。

开始之前，先看清楚你要做什么

• 目标：你机器上所有的编程 Agent 共用同一个 API Key 和同一个上游地址（本文以 Claude Code、Codex、Pi、Hermes 这四个为例，装了几个就接几个）
• 耗时：约 30 分钟（不含注册和网络下载时间）
• 前置条件：一个 API易 令牌（也可以是任何 OpenAI / Anthropic 兼容的中转或官方 Key）、一台能跑命令行的电脑、至少装好一个 Agent
• 难度：★★☆☆☆，会用鼠标点几下、会复制粘贴即可，全程不用敲命令

教程路线图

三分钟看懂：magpie 到底在中间做了什么

如果你只是想要“照做就行”，可以跳过这一节；但花三分钟看完，后面排错会快很多。

不同 Agent 对上游模型的要求差异很大，手动配一遍，装几个就要维护几套配置。下面以四个最常见的为例：

magpie（仓库 github.com/yetone/magpie，口号 “Every agent’s model. One place.”）解决的就是这件事：它把“哪个 Agent 用哪个模型、读哪个 Key”集中到一个窗口里管理，再由它去改写各工具自己的原生配置。

一句话分工：

• magpie 管分发：决定 Claude Code 用哪个模型、Codex 用哪个模型
• 网关管协议：把 Anthropic / OpenAI / Gemini 三种格式的请求，转发到真正的模型厂商

所以你的上游网关，最好支持多协议

理想组合是“magpie 管分发，网关管协议”。如果网关只支持 OpenAI 兼容格式，Claude Code 就得额外套一层协议转换，链路变长，也更容易出现工具调用格式不一致的问题。

API易 的做法是一个令牌兼容三种主流协议：OpenAI 兼容、Anthropic 原生、Gemini 格式都能用同一个 Key 调用（具体支持范围以控制台说明为准）。这样 magpie 后面只挂一个上游，所有 Agent 都能直接接入，不用分别维护厂商账号和账单。

三种做法怎么选

手动配置最直接，但工具一多，Key 分散在一堆文件里，轮换和排错成本明显上升。环境变量脚本零依赖、几十行就能搞定，但没法给不同 Agent 分配不同模型。“Claude Code 用 Claude、Codex 用 GPT、Hermes 用便宜模型”这种需求，只有 magpie 这类集中管理方案做起来顺手。

第 1 步：领一个 Key，复制就行

1.1 在 API易 控制台创建令牌

到 API易 控制台（apiyi.com）创建令牌，复制出来。

这一步不用敲任何命令。 后面整个流程里，这个 Key 只出现一次：粘进 magpie 的「供应商」面板（第 3 步）。粘完它自己会把各个 Agent 的配置文件写好，你不需要 export 环境变量，也不需要改 config.toml、settings.json 这些东西。

🚀 还没有令牌？ 可以先去 API易 apiyi.com 注册并领取测试额度，用一个令牌把常驻的几个工具都跑通，再决定长期用哪些模型。

1.2 两个地址记在手边

第 3 步填供应商时要选填哪一个：

✅ 本步验收：令牌已经在剪贴板里，知道第 3 步该填哪个地址。

第 2 步：装好 magpie，先认出这两个页面

magpie 的源码、安装方式和配置格式以官方仓库 README 为准（github.com/yetone/magpie）。项目迭代比较快，安装命令和字段名可能随版本变化，下面的界面截图和操作顺序才是长期有效的那部分。

装好启动后，你会看到一个左侧带导航的窗口。整篇教程只需要用到其中两个页面：Agent（谁用哪个模型）和供应商（Key 挂在哪里）。

① 左侧导航里的 Agent，就是你所有 Agent 的“总开关面板”：

图 1 · Agent 页：每个工具一行，右侧开关控制是否接入 magpie，开关右边是模型下拉框

在这个页面上你需要认出三样东西：

② 左侧导航里的 供应商，是挂上游 Key 的地方（下一节细讲）。

如果你想先理解 magpie 的配置文件长什么样，可以瞄一眼官方 README 的 providers / agents 结构，大意是“给上游起个名字、写 base_url 和 Key，再给每个 Agent 指一个模型”。但日常操作全部在窗口里点就行：magpie 会替你把各工具的原生配置写好，比手改 YAML 稳得多。

✅ 本步验收：窗口能打开，左侧能看到 Agent 和 供应商 两项。

第 3 步：在「供应商」里挂上你的 Key

3.1 进入供应商页

点左侧的 供应商（图 2 里红框 ①），进页后点右上角的 + 添加供应商（红框 ②）：

图 2 · 供应商页：左侧导航进「供应商」，右上角「+ 添加供应商」是唯一入口

已经挂上的供应商会以卡片形式列在这里，卡片第二行是它的地址和可用模型数（例如 api.apiyi.com · 11 个模型）。想确认“到底能不能用”，先看这一行有没有数字。

3.2 选哪一类供应商

点开「+ 添加供应商」后，会看到一个分成好几组的选择面板（图 3）：

图 3 · 添加供应商面板：订阅、供应商、中转、本机、另一台电脑上的 magpie 五类来源

面板里的分组，对应五种不同的 Key 形态：

用 API易 的话：它的 OpenAI 兼容端点就是标准的中转形态，选 中转 组里对应的条目；如果你手上就是一把自定义的 OpenAI / Anthropic 兼容 Key，直接点最下面的 + 自定义供应商（图 3 红框），把地址和 Key 填进去即可，地址填 https://api.apiyi.com/v1（Anthropic 原生请求则填 https://api.apiyi.com）。

这就是一个供应商点开后的完整面板，跟你有关的只有四行：

图 4 · APIYI 供应商的配置页：Base URL 先选协议再填地址，Accounts 放 Key，Models 勾选要开放给 Agent 的模型

这张图正好把前面那句“一个令牌多种协议”落地了：地址都是 https://api.apiyi.com，选 Anthropic 兼容 就是 Claude Code 要的原生端点，选 OpenAI 兼容 就是 Codex / Pi / Hermes 用的 /v1 端点，选 Gemini 兼容 同理。不用维护三家供应商、三把 Key。

填完保存，回到供应商列表确认两件事：卡片第二行有模型数、开关是打开的。看到 · N 个模型 就说明 Key 和地址是通的——这一步本身就是自检，不用另外跑命令。

✅ 本步验收：供应商列表里出现你的卡片，显示类似 · N 个模型，不是「未设置」。

第 4 步：把装好的 Agent 逐个接进来

回到 Agent 页，对每个你装过的工具做同样三件事。这一页会列出 magpie 能接的全部 Agent（还在不断增加，没装的那几个显示「未找到 CLI」），装了几个就接几个，下面的表格只是拿最常见的四个举例：

1. 打开右侧开关（从灰变亮）
2. 在开关右边选模型（不选就用默认；这里选的模型会写进该工具自己的配置）
3. 按提示重开这个工具（Codex、Claude Code、Pi、Hermes 多数需要重开一次进程才会读到新配置）

图 5 · 点开模型下拉：第一项「默认」让这个 Agent 用它自带的模型、不经 magpie；下面每一条都标着「经 magpie」，选中哪条，它就走上游供应商的那一个模型

几个常见状态，看到这些就说明方向是对的：

• 已接入：配置已经写好，重开工具后生效
• 未接入 · 用 XXX 自己的设置：开关没打开，或者还没选模型
• 只能用 XXX 自己的模型，magpie 无法接入：这个工具（例如 Cursor）只允许用自己的模型，属于设计限制，不是配置错了
• 未找到 CLI：这个工具没装或不在 PATH 里，装好或补 PATH 再来

💡 想给不同 Agent 配不同模型（Claude Code 用 Claude、Codex 用 GPT、Hermes 用便宜的），就在这一步分别选。这也是 magpie 相对“环境变量脚本”的主要优势。

✅ 本步验收：已装工具的开关都打开，状态行不再是「未接入」。

第 5 步：每个 Agent 各跑一句话验证

配置写完不算完成，跑通才算。每个工具里发一句最简单的任务：

想确认请求真的走了网关，最省事的办法是去 API易 控制台看这个令牌的用量/日志：有新的调用记录，就说明所有 Agent 的请求确实都汇到了同一个 Key 上。

✅ 本步验收：每个 Agent 都能正常返回，控制台里能看到对应的调用记录。

附：模型怎么选（不确定时的默认答案）

💡 建议同一个任务分别在不同 Agent 和模型上各跑一遍：有统一令牌，切换只需要改模型名，对比成本很低。

第 6 步（可选）：magpie 到底替你写了哪些配置

这一节不影响你跑通，也不是必须做的步骤。日常使用完全不用碰这些文件：第 4 步打开开关的那一刻，magpie 已经把下面这些内容写好了。放在这里只为两件事——出问题时知道该查哪一层，以及你哪天不想用 magpie 时可以直接照抄。

Claude Code：ANTHROPIC_BASE_URL + ANTHROPIC_AUTH_TOKEN

export ANTHROPIC_BASE_URL="https://api.apiyi.com"   # Anthropic 原生端点
export ANTHROPIC_AUTH_TOKEN="$APIYI_API_KEY"
# 可选：指定默认模型（以控制台模型列表为准）
# export ANTHROPIC_MODEL="<Claude 模型名>"
claude

也可以写进 ~/.claude/settings.json 的 env 字段，这样不依赖终端会话。

Codex：~/.codex/config.toml 里的 provider 段

# ~/.codex/config.toml
model = "<GPT 系列模型名>"
model_provider = "apiyi"

[model_providers.apiyi]
name = "APIYI"
base_url = "https://api.apiyi.com/v1"   # OpenAI 兼容端点
env_key = "APIYI_API_KEY"
wire_api = "responses"                   # 若所选模型不支持 Responses，改为 "chat"

wire_api 是最容易踩的坑：Codex 新版默认走 Responses 协议，如果网关侧这个模型只开放了 Chat Completions，就必须改成 chat。

Pi 与 Hermes：声明一个自定义 OpenAI 兼容 provider

思路一致：base_url 填 https://api.apiyi.com/v1，Key 引用 APIYI_API_KEY。不同版本结构有差异，以各自官方文档为准：

// Pi：在自定义模型配置里声明 provider（结构以 Pi 官方文档为准）
{
  "providers": {
    "apiyi": {
      "baseUrl": "https://api.apiyi.com/v1",
      "api": "openai-completions",
      "apiKey": "APIYI_API_KEY",
      "models": [{ "id": "<模型名>" }]
    }
  }
}

# Hermes：运行 hermes model，选择自定义 OpenAI 兼容端点，
# 按提示填入以下信息（或写入 Hermes 配置目录的 .env / config）
#   Base URL : https://api.apiyi.com/v1
#   API Key  : $APIYI_API_KEY
#   Model    : <模型名>

#!/usr/bin/env bash
# agents-env.sh —— 不依赖 magpie 的备用方案：一个 Key 驱动所有 Agent
# 用法：source agents-env.sh
: "${APIYI_API_KEY:?请先 export APIYI_API_KEY}"

# Claude Code（Anthropic 协议）
export ANTHROPIC_BASE_URL="https://api.apiyi.com"
export ANTHROPIC_AUTH_TOKEN="$APIYI_API_KEY"

# Codex / Pi / Hermes 等 OpenAI 兼容工具的通用变量
export OPENAI_BASE_URL="https://api.apiyi.com/v1"
export OPENAI_API_KEY="$APIYI_API_KEY"

# 连通性自检
curl -s "$OPENAI_BASE_URL/models" \
  -H "Authorization: Bearer $APIYI_API_KEY" | head -c 300 && echo
echo "✅ 所有 Agent 已指向同一网关"

curl -s "https://api.apiyi.com/v1/models" \
  -H "Authorization: Bearer sk-你的令牌" | head -c 300

出问题先看这里：四个高频报错

排查顺序永远是自下而上：先确认网关和令牌正常（供应商卡片上有没有 · N 个模型），再看单个 Agent 的原生配置，最后才看 magpie 的映射层。这样三步就能判断问题出在上游、工具本身，还是统一配置这一层。

常见问题 FAQ

五分钟速查

• 分工：magpie 管模型映射，网关管协议转发，各自只做一件事
• 一个令牌：选支持多协议的上游，所有 Agent 共用一个 Key 和一份账单
• 上手顺序：控制台建令牌 → 粘进「供应商」→ 打开 Agent 开关 → 逐个跑通（全程在窗口里点，不用命令）
• 排错顺序：网关 → Agent 原生配置 → magpie 映射层，自下而上
• Claude Code 要点：用 ANTHROPIC_AUTH_TOKEN，base_url 不加 /v1
• Codex 要点：wire_api 必须与模型支持的协议一致
• 备用方案：一个环境变量脚本（agents-env.sh）也能让所有 Agent 共用一个 Key

如果你同时使用三个以上 Agent，值得花半小时把这套配置搭好：以后换模型、轮换 Key，都只需要改一处。推荐通过 API易 apiyi.com 领取测试额度，先把常驻的几个工具跑通，再按任务细化每个 Agent 的模型分配。

延伸阅读 Related Articles

• 📘 Workbuddy 支持 Claude 原生格式调用吗？3 大原因与 6 类 content 报错排查实测：想搞清楚 Anthropic 原生格式和 OpenAI 兼容格式差在哪，看这篇；本文第 2 步「Claude Code 必须走原生端点」的原因也在里面
• 📊 claude-sonnet-5-5 对比 claude-opus-5-5：Opus 更快、Sonnet 只剩便宜？6 组数据讲清企业长上下文 Agent 的最佳搭配：第 4 步给不同 Agent 分模型之前先看这篇，决定谁用 Opus、谁用便宜模型
• ⚠️ gemini-4-argon AI Studio 并发是多少？429 频现的 5 类原因与 6 步解决方案：几个 Agent 同时打同一个 Key 撞上限流，就按这里的 6 步排查
• 🧭 OpenAI 报错 model not found？GPT-5.5 已于 10 月 14 日从 ChatGPT 下线，5 步排查与替代方案：第 5 步验证时报「模型不存在」，先确认这个模型名还有效

📚 参考资料

1. GitHub – magpie：项目官方仓库
2. 链接： github.com/yetone/magpie
3. 说明：安装方式、配置格式、版本更新均以 README 为准
4. Claude Code 官方文档：环境变量与 settings 配置
5. 链接： docs.anthropic.com/en/docs/claude-code
6. 说明：ANTHROPIC_BASE_URL 等变量的官方说明
7. OpenAI Codex CLI 仓库：config.toml 与 model_providers 配置
8. 链接： github.com/openai/codex
9. 说明：自定义 provider 与 wire_api 参数说明
10. API易 文档中心：多协议端点与模型列表
11. 链接： docs.apiyi.com
12. 说明：OpenAI / Anthropic 等协议端点的接入说明

作者：APIYI 技术团队
技术交流：欢迎在评论区分享你的 magpie 配置经验，更多接入资料可以访问 API易 docs.apiyi.com 文档中心