---
title: "自架 Magpie AI 閘道：讓 Claude Code、Codex 等智慧代理隨時切換模型"
description: "用 Zenavo 把 Magpie 部署到自己的伺服器上，統一管理 DeepSeek、Kimi、Anthropic、OpenAI 等模型服務商，為每台電腦發放閘道金鑰，再讓 Claude Code 和 Codex CLI 透過它呼叫模型。"
date: 2026-11-12
language: zh-TW
url: https://zenavo.app/zh-TW/blog/self-host-magpie
---

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

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

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

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

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

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

## 部署 Magpie

先在 Zenavo 中[連接一台 Linux 伺服器](https://docs.zenavo.app/zh-TW/servers/add-a-server)，再開啟 [Magpie 範本](https://zenavo.app/deploy?template=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 生效。步驟見[網域文件](https://docs.zenavo.app/zh-TW/networking/domains)。

接著在 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 文件](https://usemagpie.ai/docs/docker)。請先讀清楚各服務商的使用條款：個人訂閱通常只限本人使用，不要透過閘道分享給別人。

## 發放閘道金鑰

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

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

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

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

## 串接 Claude Code

在你的電腦上設定：

```bash
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 專案](https://zenavo.app/zh-TW/blog/claude-code-deploy-debug)。

## 串接 Codex CLI

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

```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](https://zenavo.app/zh-TW/blog/self-host-open-webui) 或 [LobeHub](https://zenavo.app/zh-TW/blog/self-host-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 範本](https://zenavo.app/deploy?template=magpie)開始：先綁定網域、保管好登入金鑰，再新增服務商、發放閘道金鑰，最後把 Claude Code 和 Codex 指向它。