手把手教程：一個 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 文檔中心