---
title: "自建 Magpie AI 网关：让 Claude Code、Codex 等智能体随时切换模型"
description: "用 Zenavo 把 Magpie 部署到自己的服务器上，统一管理 DeepSeek、Kimi、Anthropic、OpenAI 等模型服务商，为每台电脑发放网关密钥，再让 Claude Code 和 Codex CLI 通过它调用模型。"
date: 2026-11-12
language: zh-CN
url: https://zenavo.app/zh-CN/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-CN/blog/self-host-new-api)：New API 侧重统一管理团队的 API 密钥，Magpie 侧重让每个智能体自由选择模型。

服务器、Zenavo 平台和上游模型 API 分别计费；Magpie 只负责转发和统计，不会让模型调用变便宜。

## 部署 Magpie

先在 Zenavo 中[连接一台 Linux 服务器](https://docs.zenavo.app/zh-CN/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`，网页界面和智能体调用的接口都走这个端口 |
| 持久化目录 | `/config`，服务商、网关密钥、登录信息和用量记录都在这里 |
| `MAGPIE_WEB_KEY` | 项目创建时自动生成，是网页界面的登录密钥 |
| 内存 | 建议预留 512 MB |

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

## 绑定域名并登录

在 magpie 服务的 **网络** 页为 `3430` 端口绑定域名，例如 `magpie.example.com`，在 DNS 添加指向服务器的 A 记录，等待 HTTPS 生效。步骤见[域名文档](https://docs.zenavo.app/zh-CN/networking/domains)。

然后在 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 文档](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-CN/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-CN/blog/self-host-open-webui) 或 [LobeHub](https://zenavo.app/zh-CN/blog/self-host-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 模板](https://zenavo.app/deploy?template=magpie)开始：先绑定域名、保管好登录密钥，再添加服务商、发放网关密钥，最后把 Claude Code 和 Codex 指向它。