Magpie 是一个开源(MIT)的本地统一模型网关。装好之后,Claude Code、Codex、各种 OpenAI 兼容客户端和工作台都只填一个地址 http://127.0.0.1:3425。它同时支持 OpenAI、Anthropic、Gemini 三家协议,会在协议之间互相翻译。一个账号额度用完,可以自动切到下一个账号或下一个模型。这篇按从零上手的顺序讲:安装、Docker、加供应商、下游怎么接、路由组、网关 Key、局域网共享,也讲我真实踩过的坑。
本文是《AI 漫剧全栈指南》第 01 章工具篇的模型网关层一篇,可以单独看。不做漫剧、只想把 AI 工作流的模型入口收到一处,也照样适用。网络层见姊妹篇《Clash Verge Rev AI 分流指南》。
文中所有地址和 Key 都用
<YOUR_...>占位符,端口用的是官方默认值。Magpie 一天会发好几个版本。本文按 v0.1.3248 源码与官方文档核对(截至 2026-11-07 最新发布为 v0.1.3249),命令没有逐条实跑,功能细节以官方文档为准。
Magpie 是什么:一个应用加一个本地网关
问题很简单:每个 Agent、每个工作台都把模型地址和 Key 存在自己的配置文件里,格式还各不一样。供应商一多,换一次模型就要改十个地方。
Magpie(作者 yetone,MIT 协议)把这些收到一个应用加一个本地网关里:
- 它会改各个 Agent 自己的配置文件,让 Agent 指向你选的模型,不用你手动改。
- 它在本机起一个网关,所有请求都从这里过,由它决定发给哪家供应商、哪个账号。
- 额度用完了自动接着跑:同一家供应商的下一个账号顶上,或者路由组切到另一个模型或另一家供应商。
支持 macOS、Windows、Linux,有菜单栏应用、窗口、TUI、网页控制台和 CLI 几种形态,也能跑在 Docker 和 Termux 里。
注意它和 Apache 基金会的同名项目 Apache Magpie 没有关系。
官方 README 自己写了一句很实在的话:如果你只用一个 Agent,用的是厂商自家的套餐,而且够用,那你不需要它。 只有一个账号又没建路由组,额度用完也没东西可切,报错照样会传到 Agent 那里。
Magpie 默认端口:网关 3425,网页控制台 3430
| 端口 | 是什么 | 说明 |
|---|---|---|
127.0.0.1:3425 | 网关 | 跟着应用一起启动;magpie serve 只跑网关;MAGPIE_ADDR 改监听地址 |
127.0.0.1:3430 | 网页控制台(magpie web) | 参数有 --addr、--lan、--no-open、--gateway、--tls-cert/--tls-key |
3430 也会把网关的 /v1 路由转给网关,所以放在反向代理后面时只要代理这一个端口。但走 3430 的请求一律按远程请求处理,就算是从本机发的也一样:必须打开共享,还要带网关 Key。
如果放在反代或容器后面,设置 MAGPIE_PUBLIC_URL=<YOUR_PUBLIC_URL>,让控制台和 CLI 里显示的地址是别的机器真正能访问到的那个。
Magpie 怎么安装:桌面版和一行脚本
开着 Clash / mihomo 的 TUN 模式或系统代理的,先看下文「开着 Clash / mihomo 的 TUN 模式,Magpie 报 502 或连不上」那一节,把回环地址的 DIRECT 规则加上,否则第一次测试就会 502。
桌面版去 usemagpie.ai 下载,或者用官方安装脚本:
curl -fsSL https://usemagpie.ai/install.sh | sh
常用参数:
# Linux 上指定装桌面版还是终端版(--tui 也可用 MAGPIE_CLI=1)
curl -fsSL https://usemagpie.ai/install.sh | sh -s -- --gui
curl -fsSL https://usemagpie.ai/install.sh | sh -s -- --tui
# 网络不通时走本机代理或镜像(官方示例写 7890;Clash Verge Rev 默认混合端口是 7897,按你的实际端口改)
curl -fsSL https://usemagpie.ai/install.sh | sh -s -- --proxy http://127.0.0.1:7897
curl -fsSL https://usemagpie.ai/install.sh | sh -s -- --mirror <YOUR_MIRROR_PREFIX>
# 卸载;加 --purge 会连 ~/.config/magpie 一起删
curl -fsSL https://usemagpie.ai/install.sh | sh -s -- --uninstall
也可以 go install github.com/yetone/magpie@latest。
关于安全,有三点要知道:
- 用了镜像也不影响校验:每个下载文件的 SHA-256 始终从 usemagpie.ai 获取,不从镜像取。
- Mac 版签了名,也做了公证。Windows 和 Linux 版目前还没签名,Windows 第一次运行时 SmartScreen 可能会弹提示。
- 所有安装包都发布在 yetone/magpie-releases。
更新:用 magpie update 或界面里的 Restart to Update。嫌更新太频繁,可以切到稳定通道,一周一个版本:
magpie update channel stable
无界面的服务器:magpie daemon install 会把 magpie serve 装成后台服务(Linux 上是 systemd 用户服务,macOS 上是 launchd),加 --web 会同时跑网页控制台。Linux 上想不登录也开机自启,要执行一次:
sudo loginctl enable-linger $USER
Magpie Docker 部署:官方预构建镜像
服务器或 NAS 上用 Docker。官方有预构建镜像 ghcr.io/yetone/magpie,支持 amd64 和 arm64,不需要自己从源码构建。
官方的启动命令(带网页控制台):
docker run -d --name magpie --restart unless-stopped \
-p 127.0.0.1:3425:3425 -p 127.0.0.1:3430:3430 \
-e MAGPIE_WEB_KEY=$(openssl rand -hex 16) \
-v magpie-config:/config \
ghcr.io/yetone/magpie:latest web --addr 0.0.0.0:3430 --no-open
docker logs magpie # 日志里有带 ?k=... 的控制台登录链接
几个要点:
- 镜像名后面的
web是子命令。 镜像入口是/magpie,默认子命令是serve,只跑网关不带控制台。换成web才有网页控制台。 MAGPIE_WEB_KEY一定要设(至少 16 位)。设了之后控制台的 key 重启也不变,浏览器保持登录 400 天。不设的话每次启动都会生成新 key,之前的链接就失效了。- 镜像标签:
latest每次发版都更新(一天好几次);daily一天最多更新一次;stable一周一次,和桌面版的稳定通道一致;也可以钉死在某个0.1.N。生产环境建议用daily或stable。 - 容器里用非 root 用户(uid 65532)运行。用 bind mount 时,挂载目录必须让 65532 能写。
- 数据卷结构:
/config/magpie放设置、供应商、网关 Key、路由组;/config/home放各 Agent 和订阅的登录态;/config/cache放模型目录、Bun 以及它下载的 Claude Code;/config/data、/config/state放其余数据。备份就备份整个/config卷。 - 上面的命令只把端口发布在宿主机的 127.0.0.1 上,别的机器连不到。要给局域网用,改成
-p 3425:3425,并且一定配好网关 Key。
容器里的 Magpie,只要请求来自容器外面(宿主机自己也算),就必须带已启用的网关 Key,否则返回 401。容器里不需要打开「局域网共享」。生成 Key:
docker exec magpie magpie gateway-key add "<名字,如 nas-docker>"
千万别把 3430 暴露到公网。 拿到控制台链接的人可以改你的 Magpie,还能看到你的 Key。要远程管理,用 SSH 隧道或 VPN。
想自己构建也可以:在仓库目录里执行 docker build -t magpie .,得到的是同一套 Dockerfile 构建的镜像,但版本号会显示为 dev(可用 --build-arg VERSION=… 指定)。
添加模型供应商:预设、订阅登录和自定义兼容地址
图形界面:Providers → Add provider,选一个预设,粘贴 Key,或者用订阅账号登录。Import 可以从 CC Switch、Claude Code、Codex、Alma 导入已有的供应商。
预设覆盖了常见的几十家:Anthropic、OpenAI、Google Gemini、Vertex AI、Bedrock、DeepSeek、Kimi、智谱 GLM、MiniMax、阶跃、通义、百度千帆、腾讯云、华为云 MaaS、火山方舟、Mistral、Groq、xAI、OpenRouter、硅基流动、ModelScope、Ollama、LM Studio 等。另外,任何 OpenAI 或 Anthropic 兼容的地址都能加。
命令行:
magpie presets # 列出所有预设
magpie provider add deepseek <YOUR_DEEPSEEK_API_KEY> # 预设只要一个 Key
# 自定义中转:url= 填 OpenAI 兼容地址,anthropic= 填 Anthropic 兼容地址,两个可以都填
magpie provider add "My Relay" url=<YOUR_RELAY_BASE_URL>/v1 key=<YOUR_RELAY_KEY> models=<模型A>,<模型B>
magpie provider test deepseek # 每种协议发一个很小的请求,报告延迟
magpie models # 下游 Agent 能看到的全部模型
magpie providers # 每个供应商的地址、Key、暴露了哪些模型
自定义供应商还支持这些字段:responses=(厂商单独提供的 Responses 端点)、id=、name=、catalog=(借用 models.dev 的模型列表)、header.X=(自定义请求头)。
单个供应商挂了或额度用完时,可以给它指定备用模型:
magpie provider fallback <id> <供应商/模型> <供应商/模型>
还有一点要知道:Magpie 不会从 shell 环境变量里读供应商 Key。 你 .zshrc 里 export 的 OPENAI_API_KEY 它不会用,Key 一律在 Magpie 里添加。
下游工具怎么接 Magpie:OpenAI 地址带 /v1,Anthropic 和 Gemini 不带
最重要的一条规则,官方示例原样照抄:
export OPENAI_BASE_URL=http://127.0.0.1:3425/v1 OPENAI_API_KEY=magpie
export ANTHROPIC_BASE_URL=http://127.0.0.1:3425 ANTHROPIC_API_KEY=magpie
export GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:3425 GEMINI_API_KEY=magpie
OpenAI 协议的地址带 /v1,Anthropic 和 Gemini 不带。 Anthropic 客户端会自己拼上 /v1/messages,你多填一段 /v1,就变成了 /v1/v1/messages,结果是 404。
模型名格式是 供应商/模型,比如 deepseek/deepseek-chat。路由组写成 group/<id>,或者直接写组名。只写模型名(不带供应商)也能用,会落到自动生成的组或第一个提供它的供应商上。想看有哪些模型 id,请求 GET /v1/models。
在别的机器上,把 127.0.0.1 换成 <YOUR_MAGPIE_HOST>,把 magpie 换成网关 Key <YOUR_GATEWAY_KEY>(见下文「网关 Key」一节)。
用 curl 测一次,确认实际是谁在回答
curl -i http://127.0.0.1:3425/v1/chat/completions \
-H "Authorization: Bearer magpie" \
-H "Content-Type: application/json" \
-d '{"model":"<供应商/模型>","messages":[{"role":"user","content":"只回复 OK"}]}'
每个响应都带 X-Magpie-Provider 和 X-Magpie-Model 两个响应头,告诉你这次实际落到了哪家供应商的哪个模型。排查时非常有用。
如果这里返回 502,而控制台的 Routing 视图里什么都没有,直接看下一节。
开着 Clash / mihomo 的 TUN 模式,Magpie 报 502 或连不上
这是官方排障文档里专门写了的一条:Clash、mihomo、Surge 这类代理软件开了系统代理、TUN 或增强模式后,可能会把发往 http://127.0.0.1:3425 的请求截走转发到别处。表现是 502 或者连不上,而 Magpie 的 Routing 视图里什么都没有。
修法:把本地地址设成直连,放在其他规则前面。
Surge 的写法(每行一条):
IP-CIDR,127.0.0.0/8,DIRECT,no-resolve
IP-CIDR6,::1/128,DIRECT,no-resolve
Clash / mihomo 的写法(放在 rules: 下面,每行以 - 开头):
rules:
- IP-CIDR,127.0.0.0/8,DIRECT,no-resolve
- IP-CIDR6,::1/128,DIRECT,no-resolve
# …你原有的规则放在后面
只设置「绕过列表」不一定够,因为有些 Agent(Codex 就是)发本地请求时照样走代理。用 Clash Verge Rev 扩展脚本的写法,见《Clash Verge Rev AI 分流指南》。如果从局域网访问 Magpie,对应的内网网段也要加 DIRECT。改完之后,让 Agent 重新发一次请求。
常用客户端怎么接:Claude Code、Codex、OpenAI 兼容客户端
Claude Code(同一台电脑)
magpie claude <供应商/模型> # 例如 magpie claude deepseek/deepseek-chat
magpie claude group/<组 id> # 或者用一个路由组
magpie claude haiku <供应商/模型> # 单独给 haiku 档指定模型
Magpie 会把 ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN 和模型相关变量写进 ~/.claude/settings.json 的 env 块。要注意:ANTHROPIC_AUTH_TOKEN 里放了 Key 之后,Claude Code 通过 Magpie 运行期间会退出 claude.ai 登录,除非你在 Magpie 里选了保留 claude.ai 登录的选项。
Codex
同一台电脑:
magpie codex <供应商/模型>
magpie codex effort high
另一台电脑上的 Codex 连共享出来的 Magpie,用官方给的 config.toml:
model_provider = "magpie"
model = "<供应商/模型>"
[model_providers.magpie]
name = "magpie"
base_url = "http://<YOUR_MAGPIE_HOST>:3425/v1"
model_catalog_url = "http://<YOUR_MAGPIE_HOST>:3425/v1/codex/models"
env_key = "MAGPIE_API_KEY" # 环境变量里放网关 Key
wire_api = "responses"
supports_websockets = false
注意 model_catalog_url 要指向 /v1/codex/models,不是 /v1/models。后者是 OpenAI 格式的列表,Codex 读不了。
Codex 版本也有讲究:
- Codex 0.161 起默认读取这个目录;0.160 需要在
config.toml里加[features] api_key_model_discovery = true。 - 0.166 之前的 Codex 最多读 1 MiB 的目录,模型超过约 48 个就会被截断(响应头
X-Magpie-Left-Out会告诉你漏了几个)。解决办法是升级 Codex,或者少暴露一些模型给它。
Cherry Studio 这类 OpenAI 兼容客户端
通用填法只有三项:
- API 地址:
http://<YOUR_MAGPIE_HOST>:3425/v1 - Key:网关 Key(本机访问时 Magpie 不校验,填
magpie即可) - 模型名:
供应商/模型
Magpie 官方文档里没有专门写 Cherry Studio,各个客户端是否会自动补 /v1、字段叫什么名字,我没有逐个验证。填完先点客户端自带的「检查 / 测试」按钮。
Docker 容器里的工具怎么连 Magpie:magpie、172.17.0.1 和 host.docker.internal
容器里的 127.0.0.1 指的是容器自己,不是宿主机。按你的部署方式选地址:
| 部署方式 | 容器里填的 Magpie 地址 |
|---|---|
| Magpie 也跑在 Docker 里,两个容器在同一个自定义网络(如同一个 compose) | http://magpie:3425(最省心) |
| Magpie 跑在 Docker 里,另一个容器在默认网桥上 | http://172.17.0.1:3425,前提是 3425 发布在网桥能到的地址上(-p 3425:3425 或 -p 172.17.0.1:3425:3425);按上文只发布到 127.0.0.1 时大概率连不到,改用同一个自定义网络 |
| Docker Desktop(macOS / Windows) | http://host.docker.internal:3425 |
Linux 上想用 host.docker.internal | 必须给容器加 extra_hosts: ["host.docker.internal:host-gateway"] |
如果 Magpie 是宿主机上的桌面版,记得先打开「局域网共享」。不管哪种方式,从容器里访问都必须带网关 Key。
Magpie 接口参考:支持哪些协议和端点
网关同时支持四种协议:OpenAI Chat、OpenAI Responses、Anthropic Messages、Gemini,并且能在它们之间互相翻译,流式输出、工具调用、推理过程都会一起翻译。供应商本来就支持 Agent 用的协议时,请求直接透传;协议不一样时才翻译。
| 端点 | 用途 |
|---|---|
/v1/chat/completions | OpenAI Chat |
/v1/responses | OpenAI Responses(HTTP / SSE,Codex 用的 WebSocket 也支持) |
/v1/messages、/v1/messages/count_tokens | Anthropic Messages 和计 token |
/v1beta/models/{model}:generateContent | Gemini(另有 :streamGenerateContent、:countTokens) |
/v1/models | 模型目录 |
/v1/codex/models | Codex 能读的模型目录格式(给另一台电脑上的 Codex 用) |
/v1/embeddings、/v1/rerank | 向量和重排 |
/v1/audio/speech | 文字转语音(OpenAI 的 JSON 格式) |
/v1/audio/transcriptions、/v1/audio/translations | 语音转文字(multipart,透传) |
/v1/images/generations、/v1/images/edits | 同步生图、改图 |
/v1/videos、/v1/videos/{id}、/v1/videos/{id}/content | 视频:提交、轮询、取文件 |
/v1/magpie/native/{provider}/{path} | 原样透传到某个供应商自己的 API |
除 count_tokens、/v1/codex/models 和 /v1/magpie/native/... 外,这些端点去掉 /v1 前缀也能用。
两个用法细节:
- 视频接口用的是 OpenAI videos 的请求格式:读
model、prompt、seconds、size、input_reference这些字段,JSON 和 multipart 都行。不认识的字段会原样转给供应商自己的视频 API。 - 语音合成接受 OpenAI 的 TTS 请求体,
model填 Magpie 里的模型 id,官方示例是openai/gpt-4o-mini-tts、groq/playai-tts。
Magpie 路由组怎么配:12 种 routing 模式各适合什么
路由组就是把几个模型(可以来自一家供应商,也可以来自好几家)打包成一个名字。下游只选这个组:group/<id>。
magpie group add "Opus anywhere" models=<供应商A/模型>,<供应商B/模型> routing=order stays=session
magpie groups # 你建的组,以及 Magpie 自动发现的组
magpie group opus-anywhere # 查看一个组
magpie group set opus-anywhere models+=<供应商C/模型>
magpie group set opus-anywhere routing=weight weight=<供应商A/模型>=3,<供应商B/模型>=1
magpie group rm opus-anywhere
magpie claude group/opus-anywhere # 让 Claude Code 用这个组
组的 id 由名字生成,官方示例里 "Opus anywhere" 变成了 opus-anywhere。具体规则文档里没写,以 magpie groups 的输出为准。
另外两点:
- 你的两个供应商提供了同名模型时,Magpie 会自动建一个组(
auto-<模型名>),不用手动建。 - 组可以嵌套,最多 8 层。
routing= 不写的话默认是 smart。全部 12 种模式:
| 模式 | 怎么选 | 适合 |
|---|---|---|
smart(默认) | 在还有额度的订阅里,先用最快重置的那个 | 手上有好几个按周期重置的订阅 |
order | 一直用第一个,答不了才用下一个 | 一个主力加几个备胎 |
rotate | 每一轮换下一个 | 几个同价的 Key 平摊用量 |
usage | 用得最少的先用 | 让各账号用量差不多 |
pace | 按周额度的节奏,每小时剩余最多的先用 | 周额度订阅,避免周中就用光 |
weight | 按权重(1–1000)分配 | 想按 3:1 这种比例分流 |
free | 免费模型优先 | 有免费额度、能接受质量波动 |
fast | 最近首字延迟和输出速度最快的优先 | 交互对话,对速度敏感 |
cheap | 请求时价格最低的优先(只能用于路由组) | 批量跑量,不要求最强 |
drain | 一个用完再换下一个,换了不回头 | 想把某个余额一次用干净 |
expiring | 最快过期的免费额度先用,然后才用付费的(只能用于路由组) | 手里有会过期的赠送额度 |
manual | 只用你选中的那个,不做故障转移 | 排查问题、对比测试 |
拿不准就先用 order:行为最好预测,出了问题也最好查。
stays 参数:让会话粘在同一个账号上,用满提示词缓存
光有路由模式还不够,还要决定一段对话要不要一直留在同一个账号上。这由 stays= 控制:
| 取值 | 含义 |
|---|---|
auto(默认) | 只在供应商的提示词缓存还值得保留时留在原账号 |
session | 整个会话都留在原账号 |
turn | 只在一轮之内留在原账号 |
off | 不刻意保持 |
strict | 永远不换,账号休息中或到了上限也不换,报错直接给 Agent |
auto 的具体规则是:同一轮之内一定留在原账号;跨轮时,要满足两个条件才继续留:上一个请求读写缓存合计至少 1,024 token,并且是在 5 分钟之内回答的。
另外,粘住账号不会把一个正在休息的账号拉回来用,某个时间窗口里已经用到 98% 的账号也不会。
为什么这一点重要:Agent 工作流会反复带着同样的设定、规则和上下文跑,文本成本里大头是缓存。我自己的 Agent 工作流里,缓存读取能占到九成以上。会话在不同账号之间乱跳,缓存就白白丢掉了。
Magpie 网关 Key:本机不校验,远程必须带 Key
本机访问 127.0.0.1:3425 时,Magpie 不校验 Key,不带也行。 但很多客户端要求这一栏非空,官方示例就填 magpie。有一个例外:如果填的是一个真实、已启用的网关 Key,就算从本机发请求,也照样按这个 Key 计量和限额。
其他机器、其他容器访问时,必须带一个已启用的网关 Key。Key 可以放在 Authorization: Bearer、x-api-key、x-goog-api-key 里,或者用 ?key= 参数传。没带 Key 返回 401。
magpie gateway-key add "<名字,如 laptop>" # 新 Key 只打印这一次,马上记下来
magpie gateway-key list # 列出 id、名字、启用状态和打码后的 Key
magpie gateway-key rotate <id> # 换一个新 Key,身份不变
magpie gateway-key remove <id> # 吊销
# 限额:可以按 token、按估算美元,周期可以是天、周、月,或每 N 天 / 每 N 小时
magpie gateway-key limit <id> week --tokens 2m --cost 5
magpie gateway-key limit <id> 5h --tokens 200k
magpie gateway-key limit <id> add month --cost 20 --model openai/* # 只计 OpenAI 的模型
# 限定这个 Key 能用哪些模型、账号、MCP 工具
magpie gateway-key models <id> openai/gpt-5 anthropic/*
magpie gateway-key accounts <id> <供应商/账号>
magpie gateway-key mcp <id> none
规则要点:
- 一个 Key 最多挂 5 条限额,全部满足才放行。
- Key 用完额度后,请求在发给任何供应商之前就被拒绝,返回 429 和
Retry-After。 - 请求了不在允许范围内的模型或账号,返回 403。
- Key 存在
~/.config/magpie/caller-keys.json,权限是 0600。
拿到 Key 的人可以在浏览器打开网关地址的 /me 页面,输入自己的 Key,就能看到自己的限额、今天、7 天、30 天的用量,能用哪些模型,还有 Claude Code、Codex 和 OpenAI 兼容客户端可以直接复制的配置。把 Key 发给别人时附上这个地址,能省掉很多沟通。
局域网共享和远程访问:别把网关直接暴露到公网
桌面版默认只允许本机访问。要让局域网里的其他电脑或 Docker 容器访问:
- 打开 Settings → Network and sharing → Share on local network(中文界面叫「局域网共享」)。
- 再去 Gateway → Gateway keys → Add gateway key 创建 Key。这一块只有在打开共享之后才会显示。
怎么判断一个请求算远程:只要对端地址不是回环地址就算远程,Docker 端口映射进来的、WSL 的 NAT 进来的都算。共享没开、MAGPIE_ADDR 也不在网络地址上时,远程请求一律返回 403。
两台电脑共用一个 Magpie:在第二台电脑上,把共享出来的那台 Magpie 当成一个供应商添加:
magpie provider add remote-magpie <YOUR_GATEWAY_KEY> url=http://<YOUR_MAGPIE_HOST>:3425 id=office
这样第二台电脑上的 Magpie 仍然负责配置自己的 Agent,但供应商、路由组(office/group/...)和用量统计都用共享那台的。
要从公网访问,官方更推荐用 VPN(Tailscale、WireGuard)。确实要暴露的话:
- 直接开 HTTPS:
magpie serve --tls-cert <YOUR_CERT_PATH> --tls-key <YOUR_TLS_KEY_PATH>,或者前面放一个 Caddy 这类反代。 - 本机的 HTTP 反代或隧道(cloudflared、ngrok、Tailscale serve、Caddy、nginx)会加转发头,Magpie 据此把请求当作远程:没开共享直接拒绝,开了共享必须带网关 Key。
- 但只转 TCP 的隧道(frp 的
tcp、ssh -R、socat)不加转发头,Magpie 分不出它和本机 Agent,会当成本机请求、不校验 Key。绝不要把这类隧道指向127.0.0.1:3425;要用就打开共享,指向本机的局域网地址。 MAGPIE_TRUST_PROXY=1会让本机代理转来的请求重新按本机处理,只适合那个代理自己做了登录鉴权的情况,不确定就别设。MAGPIE_ALLOW_IPS可以限制允许的来源 IP。
Magpie 插件:跑在 Bun 上,可以当网关中间件
插件运行在 Bun 上。第一次用到插件时,Magpie 会自动下载 Bun。
magpie plugin add <npm 包名 | 社区插件名 | 本地路径>
magpie plugin login <供应商>
插件有两种用途:
- 接入新的登录方式或供应商;
- 当网关中间件,挂在
onRequest、onEvent、onResponse这几个环节。现成的中间件有 param-override、model-map、system-prompt、word-guard、think-tags 等。
插件目录在 magpie-community/plugins。
举一个例子:muse2api 是把 muse.ai 网页封装成 OpenAI 兼容接口的开源项目(非官方的网页自动化)。社区的 magpie-muse2api-plugin(v0.7.1,MIT)可以把它接进 Magpie。这个插件的源码读模型列表时,用正则 /image|video/ 把图片和视频模型过滤掉了,所以网关里只能看到文本模型 muse-spark。生图生视频要直连 muse2api 的异步任务接口,详见《Muse / Magpie / muse2api》。这个插件最后一次更新是 2026-10-12,在当前版本的 Magpie 上能不能正常用,我没有测过。
Codex 压缩失败、返回 502:故障转移踩过的坑(v0.1.3139 起代码已修)
路由组能在额度用完时自动换线路,但我在 2026-11-03 到 11-04 的日志里遇到过一条把会话直接卡死的失败链:
- Codex 长会话快满时,会先发一个「压缩」请求;
- 主线路限流,Magpie 按规则把请求转到备用线路;
- 备用线路声称支持 Responses 接口,但不支持引用已存储的响应,返回
400 unsupported_input_item; - 当时的 Magpie 把这个 400 当成上游故障,包成
502返回给 Codex; - Codex 重试三次都失败,报
Failed to run pre-sampling compact。回一句「继续」,它会带着更大的上下文再失败一次。
完整排查过程见《Codex compact 失败与网关故障转移》。
从 v0.1.3139(2026-11-06)开始,代码里改了两点:
- 压缩请求如果因为
unsupported_input_item或unknown item type被拒(状态码 400、422、502),Magpie 会先改成纯文本重新问一次,不行再在本地压缩,不再一路 502 到底。 - 401、403、429 这类错误照旧原样返回。
另外,Magpie 早就有一条保护(#2274),不是这次新加的:同一会话在同一模型上连续 3 次压缩失败(每次间隔不到 5 分钟),之后到最后一次失败满 5 分钟之前,压缩请求直接回 400,不再发给模型;401/403 不计数。
但要说清楚:修复提交里自己写了,没有在真实的 Command Code 账号上测过。所以「已修」的意思是代码和单元测试里修了,还不能算在生产环境里证明过。
还有一个容易忽略的点:Codex 的压缩默认由 Magpie 自己调模型来写摘要(供应商设置里的 compaction=magpie),而且走的是正常路由。也就是说,你放进路由组的每条线路,都可能接到压缩请求。改成 compaction=native 的话,会让供应商用 Codex 原生的压缩功能。
教训没变:「兼容 OpenAI 接口」不等于「兼容你用到的全部功能」。
- 给编码 Agent 用的路由组,只放你实际测过能跑压缩、能跑工具调用的线路。
- 便宜但功能不全的线路单独建一个组,只给批量文本这类不需要高级功能的活用。
- 每加一条线路,先跑
magpie provider test,再到控制台的 Routing 视图里看请求实际落到了哪里。
Magpie 会上报什么数据:隐私遮罩和使用统计
- 隐私遮罩默认关闭,要在 Settings → Privacy 里打开。
- 使用统计:官方发布的版本每天会上报一次,内容是一个随机 id、版本号、操作系统和架构,以及你用了哪些 Agent、供应商、模型(是 Magpie 内部的 id)、各有多少个、路由组个数,还有添加面板里赞助商的展示、打开、添加次数。不包含名字、地址、账号、Key、提示词和用量。
- 只关 Settings → Privacy → Share the agents, providers and models I use 这一项,就只剩 id、版本和系统。
- 全部关闭:Settings → Privacy 里关掉 Count me as a user,或者设置环境变量
DO_NOT_TRACK=1或MAGPIE_NO_STATS=1。自己从源码构建的版本不会上报。 - 另外,添加面板里赞助商的
usemagpie.ai/go/...跳转链接,不管上面怎么设置,点击都会被网站计数,就像任何网站统计访问一样。
Magpie 最小上手顺序:怎么确认真的配好了
magpie provider test <id>:每个供应商、每种协议都返回成功,记下延迟。magpie models里能看到你要用的供应商/模型。- 建一个
routing=order的路由组,放进两条你测过的线路,magpie models里能看到group/<id>。 - 开着 Clash / mihomo 的话,先把回环 DIRECT 规则加上。
- 用上面的 curl 发一次请求,响应头
X-Magpie-Provider/X-Magpie-Model是你期望的那个;控制台的 Routing 视图能实时看到这次请求。看不到的话,先排查代理软件有没有截走请求。 - 要给容器或其他机器用:建一个网关 Key,设一条周限额。从另一台机器或容器带 Key 请求一次返回 200,不带 Key 返回 401,说明鉴权真的生效了;再拿 Key 打开
/me,限额和可用模型都符合预期。 - 跑一段时间后,在 Usage 页面看 token 数、缓存读写、费用。缓存读取占比很低的话,检查
stays=设置。
Magpie 常见问题
从容器访问,报 401「not an enabled magpie gateway key」?
从容器或其他机器访问必须带已启用的网关 Key。随便填的 magpie 只在本机回环地址上有效。
从其他机器访问直接 403?
没打开「局域网共享」,MAGPIE_ADDR 也不在网络地址上。
Anthropic 协议的客户端报 404?
地址多带了 /v1,拼成了 /v1/v1/messages。Anthropic 和 Gemini 客户端只填根地址。
502,Routing 视图里却什么都没有? 基本可以确定是代理软件把发往 127.0.0.1 的请求截走了,按上文加回环 DIRECT 规则。
容器里填 127.0.0.1:3425 连不上?
容器的 127.0.0.1 是容器自己,按 Docker 那一节的表换地址。
另一个容器填 172.17.0.1:3425 连不上?
多半是 Magpie 的 3425 只发布在宿主机 127.0.0.1 上。改发布地址,或者把两个容器放进同一个自定义网络,用 http://magpie:3425。
Docker 版每次重启后,控制台链接就失效了?
没设 MAGPIE_WEB_KEY,每次启动都会生成新 key。
某个 Key 突然全部 429?
它的限额用完了,看响应里的 Retry-After,或者执行 magpie gateway-key limit <id> list 查看。
另一台电脑的 Codex 模型列表是空的或不全?
检查 model_catalog_url 是否指向 /v1/codex/models,再看 Codex 版本:0.160 要手动开 api_key_model_discovery,0.166 之前模型多了会被截断。
只有一个账号,额度用完还是报错? 这是正常现象。只有一个账号、没有路由组时,没有可以切换的对象。
必须讲的真话
- Magpie 不会让 token 变便宜。 它省的是配置时间和缓存浪费,单价由供应商决定。
- 故障转移会放大兼容性问题。 备用线路功能不全时,自动切过去反而会出错。路由组里放什么线路,要你自己负责测。
- 把订阅账号通过网关 Key 分给别人用,可能违反供应商的服务条款。 能不能共享、能共享给谁,以各家条款为准,这一点网关帮不了你。
- 暴露方式选错,网关 Key 就形同虚设。 只转 TCP 的隧道指向 127.0.0.1,Magpie 会把外部请求当成本机请求。对外一律走 VPN 或会加转发头的 HTTP 反代。
- 它更新得非常快。 一天发好几个版本,本文里的界面位置和参数可能很快就变了。生产环境用
stable通道或:stable/:daily镜像标签,升级前看一下更新日志。 - 本文按 v0.1.3248 源码与官方文档核对(截至 2026-11-07 最新版为 v0.1.3249),命令没有逐条实跑。 CLI 的具体输出、Docker 日志格式、中文界面的菜单名,都以你实际看到的为准。
姊妹篇:《Clash Verge Rev AI 分流指南》,负责网络层,让海外 AI 走固定的稳定出口。
合集目录:《AI 漫剧全栈指南》。Magpie 在那套流水线里负责模型网关这一层:在网络层之上、各个工作台之下。
COMMENTS
读者评论