文档大纲

yetone/magpie：把Claude Code、Codex等69个AI Agent的模型收进一个本地网关

你同时用 Claude Code 写代码、用 Codex 跑测试、用 Cursor 改前端，却发现这三家模型各自锁在自己的配置文件里，谁的额度快用完了你都不知道——因为它们不互相通气。

一个常驻在你电脑上的小工具专门解决这件事。它把各家模型订阅收拢成一个本地入口，额度见底自动换下一个账号，请求出网前还能把文件里的密钥先打码。这个项目叫 yetone/magpie。下面把它拆开讲清楚：它到底解决什么问题、架构怎么搭、隐私怎么处理。

它是什么：一个本地模型网关

magpie 自我定位的一句话是 "Every agent's model. One place."（每个 Agent 的模型，都在一处）。更直白一点的官方描述是：Codex 跑在 DeepSeek 上，Claude Code 跑在 Kimi 上，从 macOS 菜单栏就能切换。

形态上它是一个桌面应用：macOS 是菜单栏应用，Windows 和 Linux 提供窗口版、终端版、Web 界面和命令行，同时也提供 Docker 镜像和 Termux（安卓）版本。作者是 yetone，Go 语言写的，MIT 协议，2026 年 9 月 23 日建的仓库。

谁会需要它，谁用不着

官方给的判断标准非常干脆：如果你用了不止一个 Agent、不止一个供应商、或者不止一个账号，你需要它；如果你只用一个 Agent、只用它自己家的套餐而且额度够用，你不需要它。

这是个诚实的自我限定，值得先放在前面。magpie 解决的不是"模型不够强"，而是"模型调度权不在你手里"这件事。

支持哪些 Agent

官方清单里点了 69 个名字，Claude Code、Claude Desktop、Claude Science、Codex、Gemini CLI、OpenCode、Cursor CLI、Zed、VS Code Chat、JetBrains Air、Copilot CLI、Crush、DeepSeek Harness、Devin、Kimi Code、Qwen Code、MiniMax Code、Cline、Qoder、Qoder CN、WorkBuddy、CodeBuddy、Pencil、OpenPencil、Raycast、AionUi、Cindy、OpenClaw 都在内。

名单里同时出现了 Claude Code 和 Codex，也在最后出现了 OpenClaw。除此之外，任何能接受自定义 base URL 的工具都能接进它的网关。

三层架构：网关、路由组、插件

magpie 的结构可以拆成三层，理解这三层，后面所有功能都能挂上去。

第一层 · 网关：一个端口讲四种协议

网关固定监听 127.0.0.1:3425，同时讲 OpenAI Chat、OpenAI Responses、Anthropic Messages 和 Gemini 四种协议，并且互相翻译——不只是转发，还包括流式输出、工具调用（tool call）和推理内容（reasoning）在协议之间的转换。

这一层的意义是：任何只认其中一种协议的客户端都能接进来，不需要改自己的源码。

接入方式轻到有点夸张，三个环境变量加一个假的 API Key：

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

API Key 填字面量 magpie 就能通过校验——因为请求根本不出本机，校验只是给客户端一个"我配好了"的信号。

第二层 · 路由组：把一组模型当成一个模型

路由组（routing group）是这个项目最有意思的概念：若干个模型打包成一个模型对外暴露，Agent 眼里它就是 group/daily-coding 这样一个东西，网关负责把请求摊到组内所有成员的 Key 和账号上。

创建方式是一条命令：

magpie group add "Opus anywhere" models=claude/claude-opus-5-5,copilot/claude-opus-5.5 routing=smart

五种路由模式，各管一件事

组的路由策略有五种，选哪种直接决定你的额度怎么花：

模式行为
smart在还有额度的订阅里，挑额度最早刷新的那个用，避免白白浪费到重置时刻
order第一个成员一直用到它答不了，再退到下一个
rotate每轮换下一个成员
usage优先用得最少的那个
pace用"本周剩余额度除以剩余小时"最大的账号，把周额度摊匀

这五种不是强弱之分，而是策略之分。日常写代码适合 order，团队共享额度适合 pace，跑批量任务适合 usage，账号多且额度情况复杂时 smart 最省心。

组可以嵌套组

路由组可以包含路由组。这一条听起来平淡，但它意味着路由策略可以分层组合——先按"用哪一族模型"分一层，再在族内按"用哪个账号"分一层，而不是把所有候选摊成一张平表。

会话黏性：上下文连续性和缓存命中率的平衡

一个对话会一直待在刚刚应答它的那个账号上，只要供应商的 prompt cache 还值得保留。

这条设计把两件事绑在了一起：换账号会丢缓存，不换账号会浪费额度。magpie 的判断是——当缓存更值钱的时候，就不换。这个取舍对经常跑长对话的人是实打实的影响，因为换账号意味着重新建立上下文。

第三层 · 插件：两种身份的插件

插件跑在 Bun 运行时上，首次需要时才下载安装。插件有两种身份：

一种是供应商插件——自己登录、自己列模型、自己发请求，Agent 像用别的供应商一样用它。比如从 npm 装一个 OpenCode 的鉴权插件。

另一种是网关中间件——JavaScript 代码，能看到每一个 Agent 发出和收到的全部内容，三个钩子：

// alias.middleware.js — magpie plugin add ./alias.middleware.js
export function onRequest(body, ctx) {
  if (body.model === "fast") return { ...body, model: "deepseek/deepseek-chat" };
}

onRequest 可以改写请求或者直接拦掉，onEvent 能看到每一个流式事件，onResponse 能看到完整回复。

这里有个容易被忽略的细节：中间件抛异常或者超时，请求会保持原样发出。它不吞请求，也不把错误结果当成功放行。这是一种 fail-open 语义（失败即放行），下文讲设计取舍时会再回到这一点。

五个随附的中间件包

官方随带五个中间件包，形态上明显对标 New API 的渠道能力，用的是同一套 JSON 约定。

param-override：改字段，也能直接拒

对应 New API 的 param_override：在满足条件的前提下，对请求字段做设置、删除、移动或改写，也可以直接把请求挡回去。

model-map：换个名字发给上游

对应 model_mapping：以另一个模型名发送请求，但回复里仍保留用户请求时用的那个名字。

magpie plugin add @magpie-community/middleware-model-map
magpie plugin options model-map '{"mapping": {"fast": "deepseek/deepseek-chat"}}'

system-prompt：统一注入系统提示词

可以给所有请求挂上你的系统提示词，也可以只对特定 Agent 或特定模型生效。

word-guard：敏感词过滤与打码

对应 New API 的敏感词过滤：既能在用户输入里拦下或打码某些词，也能在回复里处理。

think-tags：处理思考标签

把回复里的 <think>…</think> 取出来，或者把 reasoning_content 字段塞进去——不同供应商对"思考过程"的表达方式不一样，这个包负责对齐。

fail-open 不是"随便失败"

前面提过中间件失败时请求照发原样。官方给的理由是：中间件属于观察和改写层，它挂掉不应该拖垮用户的主流程。

但这里有个必须自己拿捏的边界：如果某个中间件承担的是"门禁"职责（比如合规校验、敏感词强制拦截），那它的失败就不该放行。官方包把这两类混在一起提供，是把判断权交还给了使用者。做企业内网部署的时候，这一条要自己定规矩。

订阅即供应商

这是 magpie 最"省钱"的一层设计。

一个你已经登录的 Agent，本身就是一份订阅。 magpie 把它开放给其他所有 Agent 用。加多个账号，就在账号之间做故障转移。

具体到各家：

  • Claude：驱动真实的本地 claude 二进制，并通过 MCP 把你的 Agent 的工具桥接过去——也就是说 Claude Code 原本能调的工具，换成别的 Agent 也能用
  • Codex / ChatGPT：你 ChatGPT 套餐里的模型，开放给其他所有 Agent
  • GitHub Copilot、Gemini（Code Assist）、Antigravity、Grok（SuperGrok）等也支持
  • 任何 OpenCode 鉴权插件或 npm 上的 pi 包

每日预热

可以设定时间，或者"在最后一个窗口刚重置的那一刻"，提前启动 Claude 和 ChatGPT 账号的 5 小时窗口。

这个功能针对的是一个很具体的痛点：订阅制套餐的额度按时间窗口重置，窗口一开就被抢光的用户往往后知后觉。预热等于让你在窗口开启的第一秒就拿到额度。

账号发现是可控的

magpie 会读取 Agent 的登录态文件（Claude Code 和 Codex 的配置文件、macOS 钥匙串）来识别你有哪些订阅。

这是可关的：Settings → Privacy 里关掉，或者命令行 magpie accounts discovery off，或者单次运行用 MAGPIE_NO_ACCOUNTS=1 临时关闭而不改变保存的设置。用 API Key 形式的供应商不受影响。

顺带一提，官方隐私说明里提到：发布版每天会向服务器上报一次使用情况，内容是一个随机 ID、版本、系统信息，以及用了哪些 Agent、供应商和模型（用的是 magpie 自己的 ID，你自己添加的供应商只记为 custom）。这部分可以用 Settings → Privacy 关掉一部分或全部，也可以用 DO_NOT_TRACK=1 关掉。

意图路由：让强模型和便宜模型各干各的

除了"轮询着用"，magpie 还有一层按意图分流的能力：用你自己指定的一个小模型读每一轮新消息，把测试类的问题甩给强模型、简单问题甩给便宜模型。

意图路由的路由决策在 Routing 视图里实时可见——每一次"这轮为什么走了这个模型"都能查。

这个思路的价值在于它做的是分工而不是切换：你不需要为了省钱把整个会话降级，也不需要为了质量把每个小问题都送进最贵的模型。

隐私掩码：请求出网前先把敏感值换掉

这一节可能是整个项目最实用的部分。

Agent 会把读到的东西塞进 prompt 里：.env 文件、配置文件、带 token 的日志。开启掩码后，magpie 在请求离开本机之前把这些值替换成占位符，在回复里再换回来。你的 Agent 端和文件里始终是真实值，供应商永远看不到。

掩码的边界写在明处

  • 只存在内存里：值只在内存中持有，磁盘上不落盘。记录里保留每个值的类型、长度和开头几个字符
  • 掩码开不了就挡住请求：如果掩码开着但没法执行，请求会被扣住返回 503，绝不按原文发出
  • 可以核对：Insights → Masking 页面列出它改过的每一个请求，左边是原文、右边是供应商实际收到的内容；Settings 里的 Try it 可以先预览一段文本会被改成什么样
  • 有代价：模型看到的是 {{API_KEY_…}} 而不是真实值，所以"这个 token 为什么被拒"这类任务在掩码下做不了，这类值应该放进 Never mask
  • 规则偶尔会错：规则判错的入口就是 Masking 页面
  • 默认关闭：需要在 Settings → Privacy 里主动打开

举一个具体场景：你的 Agent 要读一个含数据库密码和邮箱的 .env 去排查连接问题，开启掩码后，密码和邮箱在出网前就被替换成占位符，供应商拿到的只是一串 {{API_KEY_…}}。如果哪天你需要临时排查"这个密钥是不是过期了"，把对应值加进 Never mask 就行。

掩码是纯本地完成的

整个替换过程在你自己的机器上发生，不依赖上游模型的配合。这点和很多"让模型自己别乱说"的做法有本质区别——后者是请求道德，后者是请求结构。

可诊断性：额度、成本、决策都能查

命令行看额度

magpie quota                                    # what's left on every plan

Usage 页：把成本拆开

Usage 页面给出每个 Key、每份套餐、每个账号的余额和额度窗口，还有 token 用量、缓存命中率、推理量、调用次数，以及按列表价折算出来的成本。

它还会在额度窗口即将刷新、而其中大量额度还没用掉时提醒你——这个提醒的价值在于，它让你在"额度白白清零"之前动一下。

故障排查

magpie 有 doctor 风格的排障入口，Usage 和 Routing 页面各自保留了每个请求的路由记录。

把这些放在一起看，这个项目的取向就很清楚了：它的设计里没有"静默降级"这个概念。每一次切换用了哪个模型、为什么切、额度剩多少，都是能被查到的状态，而不是埋在日志里的一句话。

上手路径

三步。

一 · 装。 从 usemagpie.ai 下载，或一行命令：

curl -fsSL https://usemagpie.ai/install.sh | sh

macOS 版本有签名和公证，每个构建都会自动更新；在防火墙后面用 --proxy 或 --mirror。也可以 go install github.com/yetone/magpie@latest，或者用 Docker 镜像。

二 · 加供应商。 打开 magpie 进 Providers → Add provider，选一个预设粘贴 Key，或者直接用订阅账号登录。预设列表包括 Anthropic、OpenAI、Google Gemini、Vertex AI、Bedrock、DeepSeek、Kimi、GLM、MiniMax、StepFun、Qwen、通义之外还有 Groq、OpenRouter、Together、Fireworks、SiliconFlow、NVIDIA NIM、ModelScope、Ollama、LM Studio，以及任何 OpenAI 或 Anthropic 兼容的 URL。

Import 功能能把 CC Switch、Claude Code、Codex 和 Alma 里的供应商直接搬过来。

三 · 给每个 Agent 选模型。 在 Agents 页面选好，起一个新会话就生效了。模型列表来自供应商本身，名称和推理档位从 models.dev 补齐——今天早上刚发布的模型，刷新一次就能出现在选择器里。

如果要在命令行里配，格式是这样的：

magpie claude deepseek/deepseek-v4-pro          # Claude Code on DeepSeek
magpie codex moonshot/kimi-k2.5                 # Codex on Kimi

数据时点与需要留意的地方

本文的数据快照取自 2026 年 10 月 29 日 12:52（Asia/Shanghai），通过 GitHub REST API 实时拉取，与当天早些时候的分析稿相比，星标从 24,770 更新到 24,773，fork 保持 2,012，未关闭 issue 从 2,190 变为 2,192。文中所有数字都对应这个时点。

三件需要留意的事：

issue 数量偏高。 2,176 个未关闭 issue 对于一个建仓才一个多月的项目是极高的数字。速成型项目的典型代价是：功能铺得极快，边界情况和文档跟不上。

默认会读登录态文件。 包括 Claude Code 和 Codex 的配置文件和 macOS 钥匙串。虽然可关，但在团队环境里部署前应该明确知道这件事。

版本号一天能跳几十个。 v0.1.1992 到 v0.1.1993 只隔了 28 分钟。追最新版能拿到最新模型支持和修复，但也意味着你几乎没有稳定的接口契约可以依赖。生产环境更适合锁一个具体版本。

还有一点值得直说：magpie 读你的登录态来驱动真实的 Claude 二进制，本质上是在复用各家 Agent 的官方登录流程。这条路径依赖上游的登录态格式，一旦上游改了格式，magpie 就得跟着改。绑定越深，升级越需要盯紧。

阅读量： 154

网站备案号：沪ICP备2025137870号