yetone/magpie：一个本地网关，让所有 Agent 随便挑模型

yetone/magpie：一个本地网关，让所有 Agent 随便挑模型

配置文件我替你改了，坑我也替你看了。

结论先放这：如果你机器上装了两个以上的 coding agent，或者手里有两个以上的模型渠道（API key、订阅、本地模型都算），magpie 值得装。它是 avante.nvim 作者 yetone 的新项目，Go 写的 MIT 程序，9 月 23 日开源，一个月 24k stars。

它干的事一句话：在本机起一个网关，所有 Agent 的配置统一指向它，然后你在菜单栏里点一下，就能让 Claude Code 跑 Kimi、Codex 跑 DeepSeek、Gemini CLI 跑 GLM，额度用完了还会自动切下一个账号。

本文提纲

  1. 它解决的那个破问题
  2. 十分钟上手：安装、加 provider、给 Agent 换模型
  3. 核心机制：一个本地网关怎么接住四种 API
  4. 高级功能逐个点评：路由组、订阅复用、隐私脱敏、插件
  5. 和 LiteLLM、new-api、CC Switch 的坐标对比
  6. 边界、风险与隐私
  7. 谁该装，谁不用装

它解决的那个破问题

每个 coding agent 出厂时都带着自己的「门户之见」：Claude Code 说 Anthropic Messages API，配置在 ~/.claude/settings.json；Codex 说 OpenAI 协议，配置在 ~/.codex/config.toml；Gemini CLI 又有自己的文件和环境变量。想让 Codex 跑 DeepSeek？手动改 TOML、在脑子里翻译 API 方言、再祈祷别的工具别把文件覆盖回去。

这还只是第一层。第二层是订阅不通用：你花钱买的 Claude 订阅只能在 Claude Code 里用，ChatGPT 订阅只能在 Codex 里用，Copilot 席位锁在 VS Code 里。第三层是额度算术：多账号、多 key 时谁的额度什么时候重置、429 了该歇多久，全靠人肉记。

magpie 把这三层一起拆了。

十分钟上手

安装三选一。macOS 有签名公证的 App，也可以脚本装：

curl -fsSL https://usemagpie.ai/install.sh | sh
# 或者有 Go 环境
go install github.com/yetone/magpie@latest

装完起服务，加一个 provider，给 Agent 指定模型，三步：

magpie serve &                                    # 起本地网关，默认 127.0.0.1:3425
magpie provider add deepseek sk-xxxxxxxx          # preset 只要贴 key
magpie claude deepseek/deepseek-v4-pro            # Claude Code 立刻切到 DeepSeek

第三条命令实际做的事，是用外科手术式的编辑器改 ~/.claude/settings.json，把 ANTHROPIC_BASE_URL 指向本地网关。新开一个 Claude Code 会话，请求链路就变成：Claude Code 发 Anthropic 格式请求到 127.0.0.1:3425，网关翻译成 OpenAI Chat Completions 格式，转发给 DeepSeek，再把流式响应翻译回 Anthropic 的 SSE 事件。全程本地，Agent 毫无察觉。

不想敲命令也行：菜单栏面板里列出本机检测到的所有 Agent（README 表格里有 60 多个集成，从 Claude Code、Codex、Gemini CLI、OpenCode 到 Cline、Zed、Crush，国内的 Kimi Code、Qwen Code、CodeBuddy 也在），点当前模型那一行，弹出搜索列表，选一个，完事。切换对新建会话生效。

一个实用细节：任何支持自定义 base URL 的工具，不做专门集成也能用，设三个环境变量即可：

export OPENAI_BASE_URL=http://127.0.0.1:3425/v1
export ANTHROPIC_BASE_URL=http://127.0.0.1:3425
export GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:3425
# API key 随便填，网关只监听 loopback，官方就用 "magpie" 这个字符串

核心机制：一个本地网关怎么接住四种 API

菜单栏只是面子，里子在 internal/gateway。这套代码值得说，因为它解决的问题确实硬。

网关在一个端口上同时提供四套端点：/v1/chat/completions（OpenAI Chat）、/v1/responses（OpenAI Responses）、/v1/messages（Anthropic）、/v1beta/models/{model}:generateContent（Gemini 形态）。任意 Agent 用自己最熟的方言进来，网关解析成一套协议无关的中间表示（IR，ir.go），消息部分带类型：文本、图片、文件、tool call、tool result、thinking、联网搜索结果，然后按目标厂商的方言重新编码出去。

MERMAID_BLOCK_0

跨协议翻译最容易翻车的流式输出、tool call、reasoning content、图片、token 计数，因为 IR 里都显式建模了，不会在转换中被拍平。一个刻意的不对称：Gemini 协议只对客户端提供，上游从不主动说 Gemini 方言，统一翻译成另外三种厂商真正实现的协议。

配置改写这一层是我觉得工程上最讲究的地方。internal/edit 里有 JSON/JSONC、TOML、YAML、dotenv 四个专用编辑器，只动你改的那一个键，注释、顺序、格式全部保留，原子写入；被替换的旧值存进 stash，切回去时原样恢复。它还会记住自己上次给每个 Agent 写过什么，如果别的程序把配置改坏了，面板上报 Drift 警告而不是默默覆盖。共享配置文件这种「三方抢着写」的地方，这套处理方式比整个文件重写靠谱太多。

高级功能逐个点评

路由组：多账号多模型的真正用法

把多个模型打包成一个 group/xxx，Agent 选这个组，网关在成员之间调度。五种模式语义有真实区别：

模式 行为 我的判断
smart 有额度的订阅里，先用额度最早重置的那个 订阅用户的默认选择，重置前不清掉的额度等于浪费，这个调度逻辑是懂省钱的
order 第一个不行了才用下一个 想钉死主力模型、挂了才降级时用
rotate 每轮轮流 适合多账号平摊，对话体验会因为模型换了而飘
usage 用得最少的优先，token 计数带一小时半衰期 按 key 计费、想均衡用量时用
pace 按每周剩余额度除以剩余小时数调度 多订阅想撑满整周的玩法，粒度最细 
magpie group add "Opus anywhere" \
  models=claude/claude-opus-5-5,copilot/claude-opus-5.5 routing=order
magpie claude group/opus-anywhere

组还能嵌套；两个 provider 恰好提供同名模型时会自动派生一个组。对话粘性（affinity）单独有讲究：一个会话一旦由某个账号应答，后续轮次尽量留在那个账号上，因为厂商的 prompt cache 是真金白银，auto / session / turn / off 四档对应不同的缓存价值判断。

Intent routing 是最有噱头但我建议谨慎开的功能：让一个小模型先读每轮请求判断意图（或者判断推理难度），简单问题路由给便宜模型，难题给强模型。思路对，但每轮多一次分类调用，分类错了的代价比省下的钱大。适合请求量真的大、且能在 Routing 视图里持续盯决策的用户；个人一天几百个请求，开着属于给自己加调试面。

订阅复用：整个项目最野的设计

这是 magpie 和其他网关拉开差距的功能：你在 Claude Code 里 OAuth 登录的 Claude 订阅、~/.codex/auth.json 里的 ChatGPT 登录、Copilot、Gemini Code Assist、Grok 订阅，都会被识别成一个 provider，反过来供给其他所有 Agent 用。

Claude 这条路的实现方式值得讲：Anthropic 把别的 Agent 的 system prompt 判定为第三方流量，直接伪造 Claude Code 的 API 调用会被封号处理。magpie 没有伪造，而是真的驱动本机的 claude binary 发起每一次生成，调用方的工具通过 MCP 桥接进那一轮对话，工具结果再续进同一个进程。ChatGPT 方向反过来，官方后端只支持流式且拒收部分参数，magpie 就把非流式请求转成流式、丢掉会被拒的字段。

我的判断：能力上无可替代，这是白嫖已购订阅的唯一正规姿势，但它天然是在厂商规则的边缘走，更新风险自担。多账号可以都挂上，一个被限流自动换下一个；daily warm-up 还能在你指定的时间点提前开启 Claude/ChatGPT 的 5 小时额度窗口。介意 ToS 风险的团队环境就别开这一类。

隐私脱敏：默认关，开了之后有真代价

Settings → Privacy 里打开 masking 后，请求离开本机前，API key、私钥、token、邮箱、银行卡/身份证号（校验和通过才认）会被替换成 {{API_KEY_xxxx}} 占位符，回复里再换回来，流式文本和 tool call 参数都换，所以 Agent 执行命令时拿到的还是真 key。同一个值永远是同一个占位符，prompt cache 不会被打碎。规则拿不准的（姓名、地址、密码）可以再下一个 1.6GB 的本地模型在 CPU 上跑识别。

两个设计细节能看出作者是真被坑过：脱敏值只存内存，磁盘上的记录只留类型、长度和首字符；脱敏模块跑不起来时请求直接 503 拦下，绝不裸奔发出。

代价也要说清：模型看到的是占位符，凡是「关于这个 secret 本身」的任务（比如排查为什么 token 被拒）就做不了，得把该值放进 Never mask。脱敏误伤在 Insights 页面能逐条核对。我建议处理 .env、生产日志这类高敏输入的常驻 Agent 开；纯写业务代码的场景收益不大，还多一层不确定性。

插件与中间件：New API 党会找到熟悉的东西

插件跑在 Bun 上（首次用时自动下载），来源是 npm 包和 pi 包，主要两类：一类是登录型 provider 插件（把某个订阅接进来），另一类是网关中间件。中间件的 onRequest / onEvent / onResponse 能看所有 Agent 的请求和流式响应，社区现成的几个基本对标 New API 的渠道能力：param-override（条件改写请求字段）、model-map（模型名映射）、system-prompt（强制注入系统提示词）、word-guard（敏感词拦截/打码）、think-tags（reasoning 内容处理）。

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

抛异常或超时的中间件不影响原请求，这个默认行为是对的。我的保留意见：中间件能读全部流量，装第三方插件前把它当浏览器扩展级别来审计，只认 magpie-community 官方仓库的。

其余值得知道的

  • Profiles：magpie save work 快照所有 Agent 的当前配置，magpie use work 一键整套切回，支持加密备份和 WebDAV/S3 跨机同步。「省钱档/专注档」两套日常切换很好用。
  • 用量面板：每个账号、每个 key 的 token、缓存读写、美元/人民币成本都有，价格可自定义，支持 OTLP 导出。magpie quota 命令行直接看所有订阅还剩多少。
  • 联网搜索 MCP：给本身不能搜索的模型挂搜索能力，Tavily、Brave、Exa、Firecrawl、SearXNG 等按拖拽顺序尝试，多 key 轮换，还能作为 MCP server 给任意 Agent 挂 web_search / web_fetch 工具。
  • 局域网共享与远程：开 Share 后能给每台客户端发独立 gateway key 并设日/周/月限额；笔记本可以远程使用桌面机上的 provider 和组；服务器/NAS 有 distroless Docker 镜像 ghcr.io/yetone/magpie，Web UI 管理。SSH 主机上用 magpie web 比 TUI 方便。
  • Library 功能：instructions、MCP server、skills、subagents 写一次，magpie 按各 Agent 的格式分发进对应文件，卸载时只删自己写过的部分。多 Agent 用户会懂这省了多少重复劳动。

和 LiteLLM、new-api、CC Switch 的坐标

LiteLLM 是服务端网关的标杆，强项是给生产应用统一 100+ 模型 API、做预算管控和审计，现在还是 Rust core + Python SDK，定位是团队基础设施。new-api 是国内自部署圈子的热门，渠道管理、分发、计费面板是它的主场。CC Switch 这类切换器解决的是单点问题：在多个 Claude Code 供应商之间切配置。

magpie 占的位置很刁：它是「个人桌面端」这一格。不上生产、不做计费出租、不管团队，只管你这台机器上一堆 Agent 和一堆渠道之间的接线。协议翻译做到四向、Agent 集成做到 60 多个、配置编辑做到无损加漂移检测，再加上「订阅反哺 Agent」这个别家没有的桥。如果你要给公司的应用做模型网关，还是 LiteLLM/new-api；如果你是每天切 Agent 的开发者，这是为你做的。

边界、风险与隐私

几个必须知道的事实：

第一，主仓库 yetone/magpie 不接受外部 PR，只有维护者能提，需求走 Discord。代码可审计（MIT），但贡献模型是 BDFL 式的，节奏完全绑在 yetone 一个人身上，他同时还维护着 18k stars 的 avante.nvim。发布构建在独立的 magpie-releases 仓库。

第二，发布版每天有一次上报：随机 id、版本、系统、用了哪些 Agent/provider/模型（自定义 provider 只报 custom），不含名称、URL、key、prompt 和用量，可在设置里关或 DO_NOT_TRACK=1；源码自己编译则没有这段。考虑到刚发生的 LiteLLM 1.107.0 投毒事件，介意的人可以直接 make cli 构建终端版，7MB，无 cgo 依赖。

第三，key 的存放是本地 ~/.config/magpie/providers.json，权限 0600，不从环境变量反向读取（避免顺手继承你 shell 里的秘密）；网关默认只听 loopback，显式开启才会共享到局域网。

第四，订阅复用那条路前面说过，跟着厂商 ToS 和风控走，别在重要工作账号上赌。

第五，开源才一个多月，issue 数已经 2000+，迭代极快（v0.1.x 一天几个版本），好处是模型上午发布下午进列表（模型清单实时从厂商拉取，元数据走 models.dev，没有编译进二进制），代价是你要容忍偶尔的行为变化，生产化使用建议钉版本。

谁该装，谁不用装

该装：Claude Code、Codex、Gemini CLI、OpenCode 里同时用两个以上的；有多个 API key 或多个订阅账号想自动轮换的；想让国产模型（DeepSeek、Kimi、GLM、Qwen）进任意 Agent 的；在 Ollama/LM Studio 跑本地模型想全机统一入口的。

不用装：只用一个 Agent 配它自家订阅、对模型没有二心的，README 自己也承认你不需要它；要给线上应用做统一网关的，那是 LiteLLM 的活；对「驱动真实 claude 进程复用订阅」这种灰色玩法零容忍的合规环境。

我自己用下来最值钱的不是菜单栏点一下，而是路由组加额度感知那套调度：多个订阅的 5 小时窗口、周额度、rate limit 各有各的重置节奏，以前全靠感觉换号，现在它按失败类型精确冷却（欠费歇 30 分钟、额度用尽歇 15 分钟、厂商自带 retry-after 就信厂商的，最长信一小时），人彻底不用管这件事了。

参考文档与链接

装完来聊聊：你把哪个 Agent 配到了哪个模型上？踩坑或者发现骚玩法，评论区见。觉得有用点个赞，让更多在改 TOML 的人看到。

作者: itech001
来源: 公众号：AI人工智能时代(the-ai-era)
网站: https://www.theaiera.top/
关注每日最新AI新闻和技术博客，主页有更多的文章的AI 技术参考：https://www.theaiera.top

本文首发于 AI人工智能时代，转载请注明出处。

posted @ 2026-10-28 09:21  iTech  阅读(112)  评论(0)    收藏  举报