自架 Magpie AI 閘道：讓 Claude Code、Codex 等智慧代理隨時切換模型

Claude Code 預設呼叫 Anthropic 的模型，Codex 預設呼叫 OpenAI 的模型。想讓 Claude Code 試試 DeepSeek，或是在某家服務商額度用完時自動換到另一家，就得在各個工具的設定檔裡來回修改位址和金鑰。

Magpie 是一個開源（MIT 授權）的 AI 閘道，正是為此而生。你把各家服務商接到 Magpie 上，智慧代理只要認得 Magpie 一個位址。它同時支援 OpenAI Chat、OpenAI Responses、Anthropic Messages 和 Gemini 格式，並在這幾種格式之間轉換，所以 Claude Code 也能使用非 Anthropic 的模型。它還提供：

• 故障切換和路由群組：某個模型出錯或額度用完時，自動換到備用模型或另一個帳號，智慧代理那端看不到錯誤。
• 用量和費用統計：依模型和用戶端統計 token、快取命中率和估算費用。
• 閘道金鑰：為每個用戶端單獨發一把金鑰，可以限制額度和可用模型。

Magpie 通常裝在自己的電腦上使用。本文用 Zenavo 的 Magpie 範本把它部署到伺服器上，讓你的筆電、桌機和同事的電腦共用同一套設定。如果你需要的是依人為整個團隊發放 API 金鑰和額度，也可以看看 New API：New API 著重統一管理團隊的 API 金鑰，Magpie 著重讓每個智慧代理自由選擇模型。

伺服器、Zenavo 平台和上游模型 API 分別計費；Magpie 只負責轉發和統計，不會讓模型呼叫變便宜。

部署 Magpie

先在 Zenavo 中連接一台 Linux 伺服器，再開啟 Magpie 範本，選擇伺服器並部署。

目前範本的設定如下：

設定	值或用途
映像檔	ghcr.io/yetone/magpie:latest
啟動指令	web --addr 0.0.0.0:3430 --no-open，執行網頁管理介面
HTTP 連接埠	3430，網頁介面和智慧代理呼叫的 API 都走這個連接埠
持久化目錄	/config，服務商、閘道金鑰、登入資訊和用量紀錄都存在這裡
MAGPIE_WEB_KEY	建立專案時自動產生，是網頁介面的登入金鑰
記憶體	建議預留 512 MB

latest 會跟著上游更新。打算長期使用時，在服務 Settings 的 Source 中把映像檔標籤改成你測試過的固定版本，或改成 Magpie 每週更新一次的 stable 頻道。

綁定網域並登入

在 magpie 服務的 Networking 頁為 3430 連接埠綁定網域，例如 magpie.example.com，在 DNS 新增指向伺服器的 A 記錄，等待 HTTPS 生效。步驟見網域文件。

接著在 magpie 服務的 Variable 分頁找到 MAGPIE_WEB_KEY 的值，開啟 https://magpie.example.com，在頁面要求的位置貼上這把金鑰登入。瀏覽器會記住登入狀態。

這把金鑰等同於 Magpie 的管理員密碼。 拿到它的人可以修改所有設定，也能看到你設定的服務商金鑰。所以：

• 不要把它交給只需要呼叫模型的人。他們需要的是下文的閘道金鑰。
• 不要讓它出現在截圖、聊天紀錄或程式碼儲存庫中。
• 懷疑外洩時，在 Variable 中把它換成新的隨機值（至少 16 個字元，可用英文字母、數字和 - . _ ~），儲存後重新啟動服務。

Magpie 官方建議把網頁介面放在本機或 VPN 裡。透過網域公開存取時，網頁介面只靠這把金鑰保護，請依上面的要求妥善保管。

設定對外位址

在 Variable 中新增 MAGPIE_PUBLIC_URL，值為 https://magpie.example.com，儲存後重新啟動。Magpie 執行在容器裡，只看得到容器自己的內部位址；設定這個變數後，網頁上顯示的連線位址和設定範例才會是你的網域。

新增服務商

在網頁介面的 Providers 頁新增服務商。Magpie 內建 Anthropic、OpenAI、Google Gemini、DeepSeek、Kimi、智譜 GLM、通義千問、Mistral、xAI、OpenRouter 等預設，也可以填寫任何相容 OpenAI 或 Anthropic 格式的位址。填入該服務商的 API Key，儲存後在模型清單裡確認能看到可用的模型。

在 Magpie 中，模型名稱的格式是 服務商/模型，例如 deepseek/deepseek-v4-pro。你也可以建立路由群組，把幾個模型組成一組，依順序、輪流或依用量分配請求，前一個出錯時自動用下一個。智慧代理呼叫時填路由群組的名稱即可。

Magpie 也能把 Claude、ChatGPT 等訂閱帳號接成服務商。在伺服器上登入這些帳號需要額外步驟，詳見 Magpie 的 Docker 文件。請先讀清楚各服務商的使用條款：個人訂閱通常只限本人使用，不要透過閘道分享給別人。

發放閘道金鑰

伺服器上的 Magpie 只接受帶有有效閘道金鑰的請求，沒有金鑰會回傳 401。在網頁介面開啟 Gateway → Gateway keys，為每台電腦或每個人建立一把金鑰並複製下來。完整的金鑰只在建立時顯示一次。

每把金鑰都可以單獨設定：

• 額度：依天、週、月或總量限制 token 數和估算費用；
• 可用模型：例如只允許 deepseek/*；
• 啟用或停用：金鑰外洩時停用或輪替它，不影響其他用戶端，也不必去上游服務商更換主金鑰。

拿到閘道金鑰的人可以開啟 https://magpie.example.com/me，輸入自己的金鑰，查看自己的額度、用量、可用模型，以及 Claude Code 和 Codex 的設定範例。他們看不到其他金鑰和服務商。

串接 Claude Code

在你的電腦上設定：

export ANTHROPIC_BASE_URL="https://magpie.example.com"
export ANTHROPIC_AUTH_TOKEN="你在 Magpie 建立的閘道金鑰"
export ANTHROPIC_MODEL="deepseek/deepseek-v4-pro"
claude

ANTHROPIC_BASE_URL 只寫網域，不要加 /v1，Claude Code 會自己接上 /v1/messages。ANTHROPIC_MODEL 換成你在 Magpie 中看得到的模型名稱或路由群組名稱，也可以進入 Claude Code 後用 /model 切換。如果想直接在 Claude Code 裡透過 MCP 與 Skills 部署、查看日誌和回滾 Zenavo 服務，可以接著看用 Claude Code 部署和除錯 Zenavo 專案。

串接 Codex CLI

Codex CLI 在 ~/.codex/config.toml 中定義自訂服務商：

model = "deepseek/deepseek-v4-pro"
model_provider = "magpie"

[model_providers.magpie]
name = "magpie"
base_url = "https://magpie.example.com/v1"
model_catalog_url = "https://magpie.example.com/v1/codex/models"
env_key = "MAGPIE_API_KEY"
wire_api = "responses"
supports_websockets = false

接著在終端機設定 export MAGPIE_API_KEY="你的閘道金鑰" 再執行 codex。這裡的 base_url 要帶 /v1，與 Claude Code 不同。model_catalog_url 讓 Codex 從 Magpie 讀取這把金鑰能用的模型清單。

其他相容 OpenAI 的網頁介面或用戶端（例如自架的 Open WebUI 或 LobeHub），Base URL 填 https://magpie.example.com/v1，API Key 填閘道金鑰即可。

備份與升級

服務商的 API Key、訂閱帳號的登入資訊和閘道金鑰都存在 /config 磁碟區裡，備份檔要和金鑰本身一樣嚴格保管。

在維護時段停止專案，在 magpie 服務的 Backup & Restore 中備份磁碟區，完成後啟動專案，並下載一份自行保存。升級前先讀 Magpie 的發行說明，先備份再更換映像檔版本。

常見問題

智慧代理回報 401？ 請求沒有帶閘道金鑰，或金鑰已停用。伺服器上的 Magpie 不接受本機版那種隨便填的 magpie 金鑰。也請確認填的是閘道金鑰，而不是 MAGPIE_WEB_KEY。

Claude Code 回報 404 或連線失敗？ 先檢查 ANTHROPIC_BASE_URL 是否多寫了 /v1。

提示模型不存在或被拒絕（403）？ 模型名稱要用 服務商/模型 格式，且在這把閘道金鑰的可用模型範圍內。用這把金鑰請求 https://magpie.example.com/v1/models，可以看到它能用的所有模型。

Magpie 會把我的程式碼送給誰？ 請求內容會送給你選擇的上游服務商，閘道部署在自己的伺服器上，不代表資料只留在本機。Magpie 有選用的隱私遮罩功能，能在請求送出前把金鑰、密碼、電子郵件換成預留位置，在 Settings → Privacy 中開啟。Magpie 每天會送出一次匿名統計（不含提示詞、金鑰和用量），可在同一頁關閉，或在 Variable 中設定 DO_NOT_TRACK=1。

一台小伺服器夠用嗎？ Magpie 本身很輕，範本建議預留 512 MB 記憶體。主要壓力來自並行的串流請求，多人同時長時間使用時，請留意伺服器的記憶體和頻寬。

從 Magpie 範本開始：先綁定網域、保管好登入金鑰，再新增服務商、發放閘道金鑰，最後把 Claude Code 和 Codex 指向它。