自建 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，网页界面和智能体调用的接口都走这个端口
持久化目录	/config，服务商、网关密钥、登录信息和用量记录都在这里
MAGPIE_WEB_KEY	项目创建时自动生成，是网页界面的登录密钥
内存	建议预留 512 MB

latest 会随上游更新。准备长期使用时，在服务 设置 的 来源 中把镜像标签改成你验证过的固定版本，或者改成 Magpie 每周更新一次的 stable 渠道。

绑定域名并登录

在 magpie 服务的 网络 页为 3430 端口绑定域名，例如 magpie.example.com，在 DNS 添加指向服务器的 A 记录，等待 HTTPS 生效。步骤见域名文档。

然后在 magpie 服务的 变量 标签页找到 MAGPIE_WEB_KEY 的值，打开 https://magpie.example.com，在页面要求的位置粘贴这把密钥登录。浏览器会记住登录状态。

这把密钥等同于 Magpie 的管理员密码。 拿到它的人可以修改所有设置，也能看到你配置的服务商密钥。所以：

• 不要把它发给只需要调用模型的人。他们需要的是下文的网关密钥。
• 不要把它放进截图、聊天记录或代码仓库。
• 怀疑泄露时，在 变量 中把它换成新的随机值（至少 16 个字符，可用字母、数字和 - . _ ~），保存后重启服务。

Magpie 官方建议把网页界面放在本机或 VPN 里。通过域名公开访问时，网页界面只靠这把密钥保护，请按上面的要求保管好它。

设置对外地址

在 变量 中添加 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 服务的 备份与恢复 中备份数据卷，完成后启动项目，并下载一份自行保存。升级前先读 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 每天会发送一次匿名统计（不含提示词、密钥和用量），可在同一页面关闭，或在 变量 中设置 DO_NOT_TRACK=1。

一台小服务器够用吗？ Magpie 本身很轻，模板建议预留 512 MB 内存。主要压力来自并发的流式请求，多人同时长时间使用时，留意服务器的内存和带宽。

从 Magpie 模板开始：先绑定域名、保管好登录密钥，再添加服务商、发放网关密钥，最后把 Claude Code 和 Codex 指向它。