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/completionsOpenAI Chat
/v1/responsesOpenAI Responses(HTTP / SSE,Codex 用的 WebSocket 也支持)
/v1/messages、/v1/messages/count_tokensAnthropic Messages 和计 token
/v1beta/models/{model}:generateContentGemini(另有 :streamGenerateContent、:countTokens)
/v1/models模型目录
/v1/codex/modelsCodex 能读的模型目录格式(给另一台电脑上的 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 容器访问:

  1. 打开 Settings → Network and sharing → Share on local network(中文界面叫「局域网共享」)。
  2. 再去 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 的日志里遇到过一条把会话直接卡死的失败链:

  1. Codex 长会话快满时,会先发一个「压缩」请求;
  2. 主线路限流,Magpie 按规则把请求转到备用线路;
  3. 备用线路声称支持 Responses 接口,但不支持引用已存储的响应,返回 400 unsupported_input_item;
  4. 当时的 Magpie 把这个 400 当成上游故障,包成 502 返回给 Codex;
  5. 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 最小上手顺序:怎么确认真的配好了

  1. magpie provider test <id>:每个供应商、每种协议都返回成功,记下延迟。
  2. magpie models 里能看到你要用的 供应商/模型。
  3. 建一个 routing=order 的路由组,放进两条你测过的线路,magpie models 里能看到 group/<id>。
  4. 开着 Clash / mihomo 的话,先把回环 DIRECT 规则加上。
  5. 用上面的 curl 发一次请求,响应头 X-Magpie-Provider / X-Magpie-Model 是你期望的那个;控制台的 Routing 视图能实时看到这次请求。看不到的话,先排查代理软件有没有截走请求。
  6. 要给容器或其他机器用:建一个网关 Key,设一条周限额。从另一台机器或容器带 Key 请求一次返回 200,不带 Key 返回 401,说明鉴权真的生效了;再拿 Key 打开 /me,限额和可用模型都符合预期。
  7. 跑一段时间后,在 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 之前模型多了会被截断。

只有一个账号,额度用完还是报错? 这是正常现象。只有一个账号、没有路由组时,没有可以切换的对象。

必须讲的真话

  1. Magpie 不会让 token 变便宜。 它省的是配置时间和缓存浪费,单价由供应商决定。
  2. 故障转移会放大兼容性问题。 备用线路功能不全时,自动切过去反而会出错。路由组里放什么线路,要你自己负责测。
  3. 把订阅账号通过网关 Key 分给别人用,可能违反供应商的服务条款。 能不能共享、能共享给谁,以各家条款为准,这一点网关帮不了你。
  4. 暴露方式选错,网关 Key 就形同虚设。 只转 TCP 的隧道指向 127.0.0.1,Magpie 会把外部请求当成本机请求。对外一律走 VPN 或会加转发头的 HTTP 反代。
  5. 它更新得非常快。 一天发好几个版本,本文里的界面位置和参数可能很快就变了。生产环境用 stable 通道或 :stable / :daily 镜像标签,升级前看一下更新日志。
  6. 本文按 v0.1.3248 源码与官方文档核对(截至 2026-11-07 最新版为 v0.1.3249),命令没有逐条实跑。 CLI 的具体输出、Docker 日志格式、中文界面的菜单名,都以你实际看到的为准。

姊妹篇:《Clash Verge Rev AI 分流指南》,负责网络层,让海外 AI 走固定的稳定出口。

合集目录:《AI 漫剧全栈指南》。Magpie 在那套流水线里负责模型网关这一层:在网络层之上、各个工作台之下。