Magpie 是什么
Magpie(GitHub 仓库 yetone/magpie)是一个开源的本地 AI agent 模型网关:Go 编写、MIT 协议,在你自己的电脑上常驻一个监听 127.0.0.1:3425 的网关服务,把 Claude Code、Codex、Gemini CLI 这类编码代理的模型配置统一收进一个菜单栏应用。项目 2026-09-23 创建,三周 Star 到约 1.1 万(GitHub 2026-10-13 查询为 11,335),官网 usemagpie.ai,作者是开源社区知名开发者 yetone,Slogan 是”Every agent’s model. One place.”。使用场景一句话说清:在菜单栏点一下,让 Claude Code 跑 Kimi、Codex 跑 DeepSeek、Gemini CLI 跑 GLM、OpenCode 跑你已登录的 ChatGPT plan;某个配额用完时,它静默切到下一个账号或模型,代理本身看不到报错。
它收拾的是哪个烂摊子
Magpie 对准的是”模型配置碎片化”这个问题。官方 README 的 “Is magpie for you” 一节把原始痛点列得很直白:每个 agent 把模型配置存在自己的文件里、格式各异、各带各的 key 和 base URL;你付费的订阅只在一个 agent 里能用。
落到日常,是三种具体的疼法。
一,换模型等于翻文件改字段。 Claude Code 一份配置、Codex 一份配置,字段名互不相通。想让 Codex 从默认模型换到 DeepSeek,你得先找到它的配置文件、搞清楚字段格式、贴对 base URL 和 key——三个代理就是三遍。
二,订阅是孤岛。 你为 ChatGPT plan 付了费,这份额度只活在 Codex 里;Claude 订阅只活在 Claude Code 里。Codex 的窗口烧完时,你另一份订阅里可能还躺着大片没用掉的配额。官方 README 的原话是:A subscription you pay for works in one agent and nowhere else。
三,配额烧完就断工。 Claude 与 ChatGPT 订阅按 5 小时窗口计(官方 README 事实),窗口一关,会话当场报错。你只能手动换号、改配置、重开会话——长任务跑一半断在这里最疼。
三大核心机制
Magpie 对这三个痛点各给了一个机制,对应关系如下(事实出自官方 README,2026-10-13 抓取)。
| 痛点 | 机制 | 官方描述 | 日常效果 |
|---|---|---|---|
| 配置碎片 | 任意模型给任意代理 | 只原子改写 agent 自己配置里的那一个关键值,注释、顺序、格式保持不变 | 换模型变成点一下,配置其余内容不动 |
| 订阅孤岛 | 一个 provider 到处用 | API key、本地模型、或你已登录的 Claude/ChatGPT/Copilot/Gemini/Grok 订阅,统一暴露 | 一份 key、一个订阅,所有代理共用 |
| 配额断工 | 路由组自动接力 | routing group 切到下一个账号或模型,代理看不到错误 | 长任务不用人守着换号 |
第一点要单独讲:Magpie 没有接管你的配置文件。它只改那一个关键值,被替换的原值存进 ~/.config/magpie/stash.json,切回时原样还原(docs/reference.md 的 Files 一节)。你手动维护的注释、字段顺序、格式全部保留——这是它和”帮你重写一遍配置”的工具的本质区别。
订阅桥接:付过费的 plan 变成所有代理的仓库
订阅复用是 Magpie 最锋利的能力:你已登录的 agent 会被它当成一个”订阅 provider”,提供给其他所有代理。README 列出的桥接路径如下。
| 订阅 | 桥接方式(README 事实) |
|---|---|
| Claude | 驱动真实的本地 claude 二进制,经 MCP 桥接工具连接 |
| Codex / ChatGPT | 你的 ChatGPT plan 里的模型,给所有其他 agent 用 |
| GitHub Copilot、Gemini (Code Assist)、Antigravity、Grok (SuperGrok) | 同样作为订阅 provider 暴露 |
| 其他来源 | 任何 OpenCode auth 插件或 pi 包(npm) |
两个细节决定它好不好用。其一,多账号故障转移:每个订阅可以加多个账号,配额用完自动切下一个。其二,Daily warm-up:在你选的时间(或上一个窗口重置的瞬间)启动各 Claude 与 ChatGPT 账号的 5 小时窗口——早八开工时窗口已经在烧,不用等第一条消息才开始计时。
隐私边界也在这节说清:magpie 靠读取 agent 的登录态(Claude Code 与 Codex 的文件、macOS Keychain)发现你的订阅;不想让它读,有三个开关——Settings → Privacy 关掉 Subscription accounts、命令行 magpie accounts discovery off、或单次 MAGPIE_NO_ACCOUNTS=1(README 原文)。纯 API key 的 provider 不受影响。
支持 60+ 个代理,五种运行形态
Magpie 官方 README 的支持列表超过 60 个 agent:Claude Code、Claude Desktop、Codex、Gemini CLI、OpenCode、Goose、Cursor CLI、Zed、VS Code Chat、JetBrains Air、Copilot CLI、Cline、Qwen Code、Kimi Code、Droid、Devin、AstrBot、ZCode 等都在列(完整列表以官方 README 为准)。界面只显示你机器上实际装了的;没在列表里的工具,只要能配 base URL 就能直接接网关,环境变量三行的事(安装与接入细节见 Magpie 安装与配置教程)。
运行形态有五种,README 的口径是 menu bar app、window、TUI、web UI、CLI,另有 Docker 镜像与 Termux(Android)构建。
| 形态 | 入口 | 适合场景 |
|---|---|---|
| 菜单栏应用 | 常驻菜单栏图标 | 日常主力,随手切换 |
| 窗口 | magpie 主窗口 | 配 provider、看用量 |
| TUI | magpie tui | 终端党、SSH 远程机器 |
| Web UI | magpie web | WSL、无桌面服务器 |
| CLI | magpie claude … | 脚本化、单次操作 |
与 AgentDock 的定位差异
结论先给:两者不在同一层——Magpie 管本机代理”用哪个模型”,AgentDock 管”AI 怎么动手干活”,可以同时用。
按公开资料,AgentDock 是开源的 MCP 运行时(详见 AgentDock 是什么):跑在你自己的电脑、服务器或容器里,对 AI 客户端暴露统一 MCP 入口,提供文件、命令、Git、任务编排这类执行能力。Magpie 则是本机菜单栏应用,专注模型接入层:模型切换、订阅复用、配额路由。一个在工具执行层,一个在模型接入层;一个可以部署在服务端面向多设备,一个贴身管本机的所有代理。
三周 1.1 万 Star 的另一面:很新,很快
选型提醒要放在前面:这是一个三周大的项目。仓库 2026-09-23 创建(GitHub 元数据),2026-10-13 时 open issues 还有 600 多个(GitHub 查询为 612)。问题敞开着,但也意味着迭代极快,README 里今天的功能描述可能下周就变。另外 README 明确写了这个仓库不收 PR,反馈统一走 Discord。
对选型的实际含义:优势是需求响应快;风险是文档滞后于代码、行为随版本漂移。建议把关键工作流先小范围跑一两天再全量迁入,具体行为以官方文档为准。
适合谁用,不适合谁
官方 README 的边界写得直白:用不止一个 agent、不止一个 provider、或不止一个账号的人,需要它;只用一个 agent、用厂商自家 plan 且够用的人,不需要它。
适合的对号入座:
- 同时跑 Claude Code + Codex + Gemini CLI,想在一处统一管理模型;
- 手里多份订阅、多个账号(公司号、个人号、大小号),想让配额互相接力;
- 用 API 中转 key、本地 Ollama 模型与官方订阅混搭(key 怎么配看 Claude Code API key 配置);
- 想让一份 ChatGPT plan 覆盖到所有编码代理。
不适合的也直说:单 agent、单订阅、厂商 plan 够用的用户,直接用官方配置更省心,多一层网关反而多一层排查面。想在几个同类工具里挑,看 Magpie vs CC Switch vs LiteLLM vs AgentDock;想深挖配额策略,看 Magpie 路由组实战。
常见问题
claude code 怎么切换模型?
装 Magpie 后在 Agents 页点 Claude Code 的模型字段,从统一列表选任意 provider/model,新会话生效;命令行一条 magpie claude deepseek/deepseek-v4-pro 也行。Magpie 只原子改写 Claude Code 配置里的模型字段,其余内容不动;正在运行的会话保持旧模型,新开会话即切到新模型(reference 文档:agent 启动时读配置)。
Magpie 支持哪些 AI agent?
官方 README 的支持列表有 60+ 个,包括 Claude Code、Codex、Gemini CLI、OpenCode、Cline、Qwen Code、Kimi Code、Zed、AstrBot 等,界面只显示你本机实际装了的。不在列表里的工具,只要能配 base URL,就能通过 OPENAI_BASE_URL 等环境变量接到 127.0.0.1:3425 网关上用。
Magpie 安全吗?key 和订阅信息会上传吗?
Magpie 是 MIT 协议的开源软件,key 存本机 ~/.config/magpie/providers.json(权限 0600,reference 文档),请求由 127.0.0.1:3425 直连你选的厂商。订阅发现需要读 agent 登录态,可在 Privacy 设置关掉;每日仅一条匿名使用计数,DO_NOT_TRACK=1 可关(README Privacy 一节)。