
如今已经逼近 34K Stars的 Magpie 是开源项目 yetone/magpie,官网是 usemagpie.ai。它解决的是一件很具体的事:电脑上同时装着几个 AI 编程工具,每家又有自己的模型、密钥和订阅,换来换去时不必再逐个改配置文件。
网上常有人说「大家已经不用 CC Switch、都转投 Magpie 了」,也常把 Jev、DeepSeek 和各家免费体验模型说成可以一股脑收进同一个工具。下面是按 2026 年 11 月 10 日能核对到的官方文档和公开使用记录来写的小白向教程,以及前面的论点哪些成立,哪些只在更窄的意义上成立。
一、这个工具是做什么的
先把三个词说清楚。
Agent 指本机上会调用大模型的编程工具,比如 Claude Code、Codex、Gemini CLI、OpenCode,以及 Cursor CLI、VS Code Chat 等。Magpie 只显示你已经安装或配置过的那些。
供应商(provider)指模型从哪里来:可以是 DeepSeek、Kimi 这类需要 API 密钥(厂商发给你、用来证明「这是你的账号」的一串密钥)的厂商,也可以是已登录的 Claude、ChatGPT、GitHub Copilot、Gemini、Antigravity 订阅,还可以是本机的 Ollama、LM Studio,或任何兼容 OpenAI、Anthropic 的接口。
网关(gateway)是 Magpie 在本机开的入口,默认地址是 127.0.0.1:3425。你给某个 Agent 选好模型后,请求先发到这个地址,再由 Magpie 转给真正提供模型的那一家。网关能在 OpenAI、Anthropic、Gemini 这几套接口之间转换,所以 Codex 可以用 DeepSeek,Claude Code 也可以用 Kimi。

它主要做四件事:
-
在一张表里给每个 Agent 选模型(写作
供应商/模型,例如deepseek/deepseek-v4-pro); -
一个供应商添加一次,就能给所有已接入的 Agent 用;
-
额度用完时,可按你预先设好的多个账号或「路由组」自动换下一个;
-
还可以选开隐私脱敏,在请求离开电脑前把密钥、密码、邮箱等换成占位符。
如果你只用一个 Agent、只用它自家官方订阅,而且已经够用,就不需要 Magpie。它适合「不止一个 Agent、不止一个供应商,或不止一个账号」的人。
还有一件会改变使用习惯的事:只要 Agent 是通过 Magpie 选的模型,Magpie 就必须一直开着(窗口可以关,菜单栏或托盘图标还在)。因为它的主产品是这道本地网关,不是改完配置就功成身退。这一点和后文的 CC Switch 很不一样。
二、安装与第一次打开
官方支持 macOS、Windows、Linux,也提供 Docker 和 Termux。最省事的是到官网下载对应系统的应用,发布文件也可在 Releases 里看到。本文写作时的最新标签是 v0.1.3587。已安装的 Magpie 一般会自己检查更新。
macOS 用已签名的安装包:Apple Silicon 选 magpie-darwin-arm64.dmg,Intel 选 magpie-darwin-amd64.dmg。也可以在终端运行官方脚本:
curl -fsSL https://usemagpie.ai/install.sh | sh
脚本会把 magpie 命令放进 ~/.local/bin,并把应用放到 /Applications。网络受限时,可加 --proxy ``http://127.0.0.1:7890 或 --mirror 指定 GitHub 镜像。校验和始终以 usemagpie.ai 为准,镜像改过的文件会被拒绝安装。
Windows 下载 magpie-windows-amd64.exe(ARM 用 magpie-windows-arm64.exe),另有只有终端的 magpie-cli-windows-amd64.exe。官方说明:Windows 上的 magpie.exe 接受和 macOS、Linux 相同的命令。若希望程序和数据放在另一块磁盘,把 magpie.exe 放进一个文件夹,旁边建名为 data 的空文件夹即可进入便携模式;各 Agent 自己的配置仍在原来的位置。常规安装下,配置目录是 C:\Users\<你>\.config\magpie。卸载请到「设置 → 卸载 magpie」。
Linux 同样可用上面的安装脚本。已装 GTK 3 和 WebKitGTK 4.1 时会装桌面版;缺库时脚本会先说明再用 sudo 安装;没有桌面或没有 sudo 时先装终端版。想自己指定,可加 --gui 或 --tui。也可以 go install ``github.com/yetone/magpie@latest,或看官方 Docker 文档。
打开之后,最短路径就三步。

到「供应商」页添加一个预设并粘贴密钥,或登录一个订阅;到「Agents」页给每个工具选一个 供应商/模型;然后开一个新会话。正在运行的会话会沿用启动时的模型。Codex 还要重启应用,因为它的模型列表也是启动时生成的。
全程也可以在终端完成(密钥请换成你自己的,不要把真密钥写进教程或截图):
magpie provider add deepseek sk-你的DeepSeek密钥
magpie claude deepseek/deepseek-v4-pro
magpie codex moonshot/kimi-k2.5
magpie save work && magpie use work
magpie quota
magpie tui
magpie ls 可查看本机找到了哪些 Agent,以及它们当前的模型。用脚本安装的,卸载可以运行:
curl -fsSL https://usemagpie.ai/install.sh | sh -s -- --uninstall
这会先断开每个 Agent 并恢复原来的配置,再拿掉程序。~/.config/magpie 默认保留,加上 --purge 才会一起删除。
三、把各家模型收到一起
DeepSeek 是官方预设,加密钥就能给任意已接入的 Agent 用。
Jev 也是正式支持的,但它不是用来写代码、聊天的普通对话模型。它是 TypeSafe 的 System One 结构化判断模型,在 Magpie 里主要担当路由组的「意图判断模型」:读你刚发的那一条消息,判断这轮该交给组里的哪个模型、用多重的推理强度。把它当成 Claude 或 DeepSeek 的替代品,会走不通。

免费或试用模型可以加进来,也可以和付费模型放进同一个路由组,但这不是 Magpie 自带的「免费模型市场」,更不是「装了就能一直白用」。能用哪些、额度还剩多少,都由上游当时的目录决定。
1、添加 DeepSeek
窗口里:打开「供应商」页,点「添加供应商」,选 DeepSeek,粘贴密钥后保存。「获取密钥」会打开厂商自己的密钥页面。保存后,Magpie 会向 DeepSeek 询问当前模型并列出来,可勾选要暴露给 Agent 的模型,也可以点「测试」。
终端里的官方示例是:
magpie provider add deepseek sk-你的DeepSeek密钥
magpie provider test deepseek
magpie claude deepseek/deepseek-v4-pro
最后一行的意思是:让 Claude Code 使用 DeepSeek 的 deepseek-v4-pro。具体模型名以 magpie models 或界面列表为准。密钥只保存在 Magpie 自己的配置里(~/.config/magpie/providers.json,权限仅你可读),它不会去读 shell 环境变量里的密钥。同一套做法也适用于 Kimi、智谱 GLM、OpenRouter、硅基流动等官方预设。自定义接口需要填写名称、兼容 OpenAI 的地址(通常以 /v1 结尾)或兼容 Anthropic 的根地址,再填密钥。
2、添加 Jev:它是判断器,不是聊天模型
TypeSafe 把自己的旗舰模型叫做 Jev,之前我们有写过相关文章:
《Jev这35个场景我整理成了一本实战手册》
《Jev这8个场景,对上你现在的Agent》
《Jev爆火先别急着往Agent里硬接》
走的是 POST https://api.typesafe.ai/v1/systemone 这一套决策接口,不是普通的聊天补全。常用别名是 jev-latest(写作本稿时指向 jev-1.14.0)。在 TypeSafe 控制台申请密钥的地址,Magpie 预设里写的是 console.typesafe.ai/keys。
Magpie 源码里的官方预设名称是 TypeSafe Jev,供应商 id 为 typesafe。添加方式和别的「只需要密钥的预设」相同:
magpie provider add typesafe sk-你的TypeSafe密钥
窗口里到「供应商 → 添加供应商」,找到「TypeSafe Jev」,粘贴密钥保存即可。加上之后,模型会以 typesafe/jev-latest 这种形式出现。也可以把 TypeSafe 的 Jev 和阿里云百炼的决策模型组成一个专门的判断组:
magpie group add Jevs models=typesafe/jev-latest,bailian-token-plan/decision-model-preview routing=order
这类组不会出现在 Agent 的普通模型列表里,而是给路由组当分类器使用。发给 Jev 的对话请求会被拒绝。
暂时没有 TypeSafe 密钥时,还有几条旁路,效果同样是「当判断器,不当聊天模型」:已添加 OpenRouter 时,它的决策模型列表里包含 typesafe/jev-latest 等;官方也有「Jev · Vercel AI Gateway」和「Cloudflare Workers AI · Jev, Clef」等预设;部分免费通道(例如 OpenCode Zen,以及社区免费模型插件)会提供名为 jev-*-free 的决策模型,列表是否出现要以当时的上游目录为准。
使用方法见官方「意图路由」:先有一个至少包含两个模型的路由组,再为这个组添加带「意图」的规则,例如「写测试或修测试」交给较强的模型、「简单提问」交给更快更便宜的模型。有 TypeSafe 供应商时,意图判断模型会默认选 Jev;否则可以选一个小而快、不带推理的模型。保存后从下一轮起生效,可在「路由」页看到判断结果。命令行示例:
magpie group rule add coder use=deepseek/deepseek-v4-flash intent="a quick question" classifier=groq/llama-3.1-8b-instant
magpie group rule add coder use=deepseek/deepseek-v4-pro intent="writing or fixing tests"
magpie group rule classifier coder typesafe/jev-latest
有两点在真实使用里反复被提到:判断模型默认只看你最新这一条消息,只回「继续」「同意」时很容易判轻;意图规则只能在当前这个路由组的成员里挑选模型,组外的模型切不过去。
3、把免费或试用模型加进来
Magpie 能做的,是把你有权使用的那些免费额度、试用模型和付费订阅,放进同一个本机网关和选择列表,必要时再放进同一个路由组。它不会把付费模型变成无限免费,也不会保证某条免费通道明天还在。
常见来源包括:
-
OpenRouter:按官方方式添加并粘贴密钥。社区在 2026 年 11 月 2 日的一份盘点里列出过一批名称带
:free的模型,那只是当时的快照,请以刷新后的列表为准。 -
OpenCode Zen:官方预设注明「免费模型可以不填密钥」。它的聊天接口和决策接口是分开的,Zen 上的 Jev 仍然只走 System One,不能当聊天模型。
-
Kilo Gateway:官方预设注明「免费模型无需密钥」。
-
NVIDIA NIM、魔搭等:官方有预设;其中哪些当时标价为零,以厂商列表和 Magpie 刷新结果为准。
-
WorkBuddy / WorkBuddy AI:可在用量卡片上点签到,或运行
magpie accounts checkin。社区教程把插件安装写成magpie plugin add @magpie-community/opencode-workbuddy-auth,然后在「供应商」里选择 WorkBuddy(国内版)或 WorkBuddy AI(国际版),优先用浏览器登录。这不是「装完就永久免费」的承诺;桌面客户端 5.6 及以后对登录信息做了加密,桌面导入可能失败,应改用浏览器登录。
把免费模型和主力模型放在一起时,建议给免费模型明确的用途,而不是让它们垫在长队列最末尾「额度满了就顶上」。更稳妥的做法是:用路由组规则把「压缩上下文、子代理、简单提问」交给免费或低价模型,不要让差模型接到高难度任务。
登录订阅(Claude、ChatGPT、Copilot、Gemini Code Assist、Antigravity 等)的方法是:在「添加供应商」里点对应卡片,Magpie 会打开厂商自己的登录页。官方特别提醒:Google 可能封禁在 Antigravity 之外使用的 Antigravity 账号,请用丢了也不心疼的账号。Claude 订阅的请求会通过本机安装的 Claude Code 运行,所以请保留 Claude Code。
四、日常怎么用
刚上手只需先会三件事:给单个 Agent 换模型、用「方案」一次切换整套配置、在有多个账号或模型时建一个简单的路由组。
在「Agents」页找到那一行,点当前模型,从列表里选。列表会分组显示:Agent 自带的模型、你的路由组、再是你添加的每个供应商。选好后开新会话。若要恢复某个 Agent 原来的默认值,在选择器里选回它自带的模型,或运行 magpie default;只恢复 Codex 则用 magpie codex default。如果你希望平常的 claude 命令继续走自己的 Claude 账号,只在需要时才经过 Magpie,可以用 claude-magpie(或 magpie claude run):这一次会话会叠上 Magpie 的网关和模型,但不会改写 ~/.claude/settings.json。
「方案」就是把所有 Agent 当前的模型选择存成一个名字。在 Agents 页底部点「保存当前」,以后点这个方案就能一键切回去。终端里是 magpie save work 和 magpie use work。正在使用的方案会带标记;你事后又手动改过某个 Agent,标记会消失。
路由组是把几个模型或账号合成一个名字,Agent 把它当作一个模型来选,例如 group/daily-coding。适合同一个订阅有多个账号,或同一个模型既有官方接口、又有 OpenRouter、还有免费通道。官方入门示例:
magpie group add "Opus anywhere" models=claude/claude-opus-5-5,copilot/claude-opus-5-5 routing=smart
magpie claude group/opus-anywhere
smart 是默认策略:在还有额度的订阅里,优先用最快重置的那个。此外还有按顺序(order)、轮流(rotate)、剩余额度多的优先(usage)、按重置前的消耗节奏(pace)等。想先跑通时,用 smart 即可。两个供应商提供了同名模型时,Magpie 还会自动组成 auto/模型id 这样的组,不想要的可以用 magpie group rm 隐藏。查看额度用 magpie quota 或窗口里的用量页;经过网关的调用才会被统计。
更进阶的规则(按意图、按文件夹、按时段、把 /compact 交给便宜模型)见官方文档。建议先观察几天「路由」页的记录,再改规则措辞。
五、从 CC Switch 迁过来的人要先注意什么
先纠正一个常见说法:并不是「现在都不用 CC Switch 了」。
官方对比页把 Magpie、CC Switch 与 Claude Code Router 写成各有所长,而且写明「也可以同时使用」——不过同时用时必须非常小心。CC Switch 更适合主要靠手动给每个工具切换服务商、或想在一个应用里集中管理 MCP、Skills 和提示词的人;Magpie 更适合同时用多个工具、希望它们共用一个会转换协议的本机网关、并且需要多账号自动转移的人。两边都还在活跃更新。
根本差别是请求怎么走。CC Switch 默认是配置管理器:改好配置后,工具可以自己直连厂商,应用在直连模式下甚至可以退出。Magpie 则是本地网关:选了它提供的模型后,请求一定经过 127.0.0.1:3425,网关关掉,这些 Agent 就会连不上。

官方支持导入。打开「供应商」页时,Magpie 会在后台检查 CC Switch、Claude Code、Codex 和 Alma 里的本地配置;没有供应商时会提示发现了多少,否则在「添加供应商」旁边出现「导入本地配置」。点进去后先勾选、再确认,不会在你点确定之前写入。
迁移时建议按这个顺序:
-
如有需要,先在 CC Switch 里把 Agent 恢复成官方配置,避免两边稍后互相覆盖同一份配置文件。
-
在 Magpie 里用「导入」勾选要带来的供应商。导入的是一份拷贝,之后两边不再同步。
-
订阅登录、OAuth 这类凭据通常需要在 Magpie 里重新登录。
-
到 Agents 页,重新给每个工具选择
供应商/模型或路由组。 -
用
magpie ls和magpie provider test <供应商>逐个验证,并开新会话试一条最短对话。 -
验证通过后,停用或卸载 CC Switch,或至少不要再在 CC Switch 里切换供应商。两个工具都会改同一批配置文件,后写的会盖掉先写的。
有人迁过来,是因为原先要同时挂着 CC Switch 和另一套反代,才能把 Antigravity 的模型分给其他 Agent;换到 Magpie 后,Antigravity 是原生接入,少开一个软件。这是特定场景,不是所有人都必须换。如果你主要用 Claude Code 和 Codex、更看重 MCP / Skills / 会话阅读,官方对比页仍然把 CC Switch 列为合适的选择。
六、真实使用案例
下面几篇都是 2026 年 10 月到 11 月可以打开的公开记录。每篇只取能核对到的做法和教训,列表和版本都可能已经过时。
1️⃣Ward Lu:为什么从 CC-Switch 换到 Magpie :https://wardlu.com/blog/magpie-gateway-part-1 (2026-10-18)记录了一次完整迁移:同时接入 Codex、Claude Code、OpenCode Go、多个 Google AI Pro(Antigravity)订阅和 WorkBuddy,并从 CC Switch 导入原有供应商。他看重的是 Antigravity 不必再另开反代,以及社区插件支持 WorkBuddy 每日签到。文中的免费模型 id 是当时的实测结果。
2️⃣Ward:用 Jev 重构多模型路由 :https://juejin.cn/post/7698552541927817231 (2026-10-20)是同一系列里对意图路由的复盘。他先按「五个路由组」来配,后来发现:主对话只会进入当前槽位绑定的那一个组,Jev 不能把请求跳到另一个组。把十八个模型按 order 排成一条长队后,主力限流时有八百多次请求滑到了免费 Flash 上。他把审查规则改写清楚,并把对应模型加进主组之后,日志里才看到 Jev 用大约一秒判中审查意图。文中也写到:Jev 只看当前这一轮,「继续」容易被判成低强度。
3️⃣白嫖社区:把 WorkBuddy 接进 Codex、Claude Code 和 OpenCode :https://baipiao.org/docs/magpie-tutorial/ (2026-10-22)面向新手的插件操作说明,步骤和官方「先加供应商、再给 Agent 选模型、再开新会话」一致。它额外整理了一批 WorkBuddy 相关报错和 3425 连不上时的检查项,并强调不要把生产稳定性押在单一免费额度上。
4️⃣闻心阁:当时可以用 Magpie 接到的免费模型厂商 :https://yqc.im/magpie-free-model-providers.html (更新于 2026-11-02)把 OpenRouter、OpenCode Zen、NVIDIA NIM、Groq 等来源里当时看到的免费或零价模型列成清单。适合用来建立印象,不适合当作今天的菜单照抄。
5️⃣liurb:magpie 会成为下一个 CC Switch 吗 :https://blog.liurb.org/posts/2026/10/11/magpie-intro/ (2026-10-11)写于 Magpie 发布约两周时,作者在 Windows 上双击打开,并确认可以从 CC Switch、Claude Code、Codex、Alma 导入供应商。关于「一个管配置、一个管流量」,以及把 3425 映射到所有网卡前要先配好局域网密钥的提醒,仍然和官方安全说明一致。
6️⃣youngs.zone:CC Switch 与 magpie 的逐项对比 :https://youngs.zone.id/post/68.html (资料基准约 2026-11-02 / 11-03)把迁移步骤、两者同时使用时的覆盖风险,以及「只想换 Key 选 CC Switch、想要统一网关和策略选 Magpie」写得很细。两款软件迭代都很快,文中的版本号只是当时的基准。
七、常见问题与坑
1、关掉窗口之后,Agent 是不是还能用? 通过 Magpie 选用的模型,需要网关还在运行。关掉窗口后,它通常仍留在菜单栏或托盘里。magpie tray 可以只启动图标,magpie serve 只运行网关,magpie daemon install 会把它装成服务。Agent 若用的是自己的模型和登录,则不经过 Magpie。
2、换了模型,对话还是旧的? 已在运行的会话保持启动时的模型。请开一个新会话;如果是 Codex,同时重启 Codex 应用。
3、Agent 报 502,或连不上,路由页里却什么都没有? 常见原因是系统代理(Surge、Clash、mihomo 等)把发往 127.0.0.1:3425 的请求接走了。只把 127.0.0.1 写进跳过列表不一定够,有些 Agent(包括 Codex)仍会走代理。需要在代理规则最前面加上本地地址直连,例如:
IP-CIDR,127.0.0.0/8,DIRECT,no-resolve
IP-CIDR6,::1/128,DIRECT,no-resolve
4、需要自己导出 OPENAI_BASE_URL 吗? 对 Magpie 列表里的 Agent,不需要。它会把网关地址和令牌写进 Agent 自己的配置。这些环境变量只用于 Magpie 没有纳入管理、但支持填写 base URL 的其他工具。本机默认可以使用 magpie 作为网关密钥:
export OPENAI_BASE_URL=http://127.0.0.1:3425/v1
export OPENAI_API_KEY=magpie
把网关分享到局域网或公网之前,请先打开「设置 → 网络与共享 → 局域网共享」,并为每个客户端创建独立的网关密钥。不要把 3425 裸暴露在所有网卡上却不设密钥。
5、Jev 选不中,或一直不切模型? 先看「路由」页。常见原因包括:判断模型超时或回答「都不是」;上面还有一条不带意图的规则先命中了;目标模型不在当前这个组里;规则指定的模型正在冷却;或者这只是同一轮里的工具往返,不会重新判断。判断失败时这一轮照常有回答,只是带意图的规则不生效,不会把对话卡死。
6、免费模型今天还有、明天没有了? 这是上游目录和账号策略的问题。刷新供应商的模型列表,并以当前账号实际能看到的为准。重要任务请保留可替换的付费或官方通道。
7、手动改了 Agent 的配置,会不会被覆盖? Magpie 每次重新读取文件,只动它负责的那几个键,你的其他设置和注释会保留。导入带来的供应商是拷贝,之后在原工具里的修改不会自动同步回 Magpie。真正要小心的是另一个也在改同一份配置的管理器,例如同时开着的 CC Switch。
8、它会把我的对话发给 Magpie 的服务器吗? 官方说明:提示词、回复、密钥和账号只发给你使用的供应商。正式版每天会发送一次匿名使用计数(随机 id、版本、系统,以及用了哪些 agent / 供应商 / 模型的内部 id),不含名称、URL、账号、密钥、提示词和用量。可在「设置 → 隐私」关闭,或设置 DO_NOT_TRACK=1。细节见官方隐私页。
9、日志在哪里? macOS 上是 ~/Library/Logs/magpie/app.log,Windows 上是 %LOCALAPPDATA%\magpie\logs\app.log,Linux 上是 ~/.local/state/magpie/app.log。magpie log 会打印路径,magpie log -f 可以跟随输出。日志里不应出现你的密钥和提示词原文。
10、版本号为什么一直在涨? Magpie 于 2026 年 9 月开源,版本号是 v0.1.x,发布非常频繁。本文核对时的最新标签是 v0.1.3587。遇到菜单和文档不一致,以当前应用内说明和官方文档为准。仓库不接受外部 Pull Request,问题和想法请到 Discord 反馈。
参考链接
GitHub 仓库 yetone/magpie :https://github.com/yetone/magpie 中文 README :https://github.com/yetone/magpie/blob/main/README.zh-CN.md 官网与下载 :https://usemagpie.ai/zh/ 完整参考(英文) :https://github.com/yetone/magpie/blob/main/docs/reference.md 意图路由 :https://usemagpie.ai/docs/zh/intent 与 CC Switch、Claude Code Router 的官方对比 :https://usemagpie.ai/docs/zh/alternatives 插件说明 :https://usemagpie.ai/docs/zh/plugins 社区插件仓库 :https://github.com/magpie-community/plugins TypeSafe / Jev 模型说明 :https://docs.typesafe.ai/models OpenRouter 在 Magpie 中的用法 :https://usemagpie.ai/docs/openrouter