三个 Agent，各配一遍 key，各有各的配置文件格式。Claude 的订阅只能在 Claude Code 里花，换个工具就用不上。更常见的是：一句简单的「今天几号」也在烧最贵的那个模型，因为你根本没地方设规则。
读完这篇，你会有一个丝滑畅快的路由组：难题自动交给强模型，简单活自动走免费额度，配置一次，所有 Agent 共用。
你需要准备什么
| 项 | 要求 | 说明 |
|---|---|---|
| 系统 | macOS 12 及以上，Intel 也能装 | Windows / Linux 官网标了支持，本文未实测 |
| 一把 API key | 任意一家 OpenAI 兼容的 | 先用它跑通，不要一上来就接订阅 |
| 打算接几个 Agent | 2 到 3 个高频的就够 | 开太多只会把配置摊薄 |
| 时间 | 第一次约 20 分钟 | 建组和验证占一半 |
一、安装模型路由神器Magpie
官网 https://usemagpie.ai/ 给两种装法：下载 Mac 安装包，或者一行终端命令。装好后它会在菜单栏常驻显示。
装之前，先把会被改写的配置存一份原文，做好备份出问题好回滚：
mkdir -p ~/agent-config-backup && cd ~/agent-config-backup
for f in ~/.claude/settings.json ~/.codex/config.toml ~/.config/opencode/opencode.jsonc; do
[ -f "$f" ] && cp -p "$f" "./$(echo "$f" | tr '/' '_')"
done
tar -czf agent-configs-$(date +%Y%m%d-%H%M).tgz \
~/.claude/settings.json ~/.codex/config.toml ~/.gemini/settings.json 2>/dev/null
连注释一起存。magpie 会直接改这几个文件里的 model 键和 env 段，改完不 diff 就不知道它动了什么。
成功判据：菜单栏出现 magpie 图标，点开能看到「Agent / 会话 / 资源库 / 供应商 / 路由 / 网关 / 用量 / 插件」这一排入口。
二、先接一把 API key
打开「供应商」页。这一页把三类东西收在一处：已登录的订阅、你买的 API key、本地模型。我本机现在 12 个供应商；magpie models 列出 136 个可直接选的模型和 20 个路由组。
先加一把最便宜的 key。加完会亮绿点，点进去能看到它拉到了几个模型。
命令行查同一件事：
magpie providers # 每个供应商的域名、模型数、谁在用
magpie models # 分组列出 Agent 能选的模型和路由组
成功判据：这个 provider 后面亮绿点，且模型数不是 0。
这里需要注意一点：拉取到模型要把所有的模型全选中后保存，因为Agent只能看到已勾选的模型。
⚠️ 订阅账号发现默认是开着的，magpie 会读 Claude Code / Codex 的登录文件和钥匙串。不想接订阅，就在「设置 → 隐私 → 订阅账号」关掉，或 magpie accounts discovery off。
三、打开 2 到 3 个 Agent
回到「Agent」页。每个已接入的 Agent 后面写着它能用的模型数（我本机都是 60）。底部还有「安装其他 Agent」。
开完去那个 Agent 自己的模型选择框里看，magpie 的模型会以 provider magpie 的形式出现。
成功判据：Agent 的模型下拉里能看到 magpie，下面有 group/… 开头的分组名。
四、建第一个路由组（本文核心）
前三步解决的是「能用哪些模型」。路由组解决的是「这条消息该给哪个模型」。没有这一步，你装到手的只是一个手动切换器。
进「路由」，新建组。规则可以照这个样子写（下表是我现在实际在跑的，magpie group smart-split 原样输出）：
| 规则 | 条件 | 交给谁 |
|---|---|---|
| 1 | 意图是难题：设计、排错、跨文件修改、做计划 | claude/claude-opus-5-5 |
| 2 | 意图是简单任务 | group/auto-deepseek-v4-1-flash（五个平台的同名模型合并组） |
| 3 | 意图是生成图片 | group/auto-gemini-3-1-flash-lite |
| 4 | 意图是执行自动化、调研、简要分析、固定格式报告 | codex/gpt-6-luna |
截这张图时我用的还是三条规则、判定器是 Opus 的版本，正好可以拿它讲这个陷阱：页面最下面那栏写着，意图判断模型 Claude Opus 5.5 每轮开始都会先发一个请求，和 Agent 自己的请求一样计入该订阅的额度。你为了省钱建的组，判定器本身在花你的 Claude 额度。
后来我把它换成了免费模型。现在 magpie group smart-split 输出的最后一行是：
classifier opencode-jev-free/jev-1.13-free tells which intent a message is
判定器只需要判「这活难不难」，不需要旗舰模型。换成免费模型（或任何 API key 上的模型）之后，订阅额度才真正只留给 Agent 用。这一步不做，整套路由是净亏的。
组里的成员你可以添加独立的模型，也可以添加创建的模型分组。你可以独立创建一个DeepSeek的模型组，把所有DeepSeek的模型收录进去，然后就可以一键添加整组模型。
两种组类型，先记住区别：
- smart（按规则分派）：先给判定器看意图，再按规则表分派。上面这组是 smart。
- order（按顺序兜底）：主力放第一，便宜的放第二，第一个失败才用第二个。我的
workhorse组是 order：codex/gpt-6-sol → zenmux/deepseek/deepseek-v4-pro。
你可以根据你的使用需求创建不同的路由规则：
- 根据任务的难度、成本、能力等去做意图分析，并路由到组内的模型；
这部分可以交由Agent分析你的项目，帮你完成规则的配置。
成功判据：magpie groups 里能看到你的组；magpie group <id> 里的 models 和 rules 都不是空的。
五、验证它真的按规则跑了
建完之后，在Agent页面打开你的常用agent，并发送消息，在路由页面就可以看到magpie自动路由的线路。作者还做了一个小喜鹊来回送信，非常可爱。
在路由下面位置会有实时的调用显示，对于调用了什么模型，消耗了多少token都能一目了然，再也不用一个窗口一个窗口查剩余额度。
我本机今天 430 次请求：gpt-6-luna 171 次、gpt-6-sol 85 次、两条 DeepSeek V4.1 Flash 线合计 108 次、免费的 jev-1.13-free 判定器 27 次，claude-opus-5-5 只有 36 次、占 1% 的 token。贵模型没有在承担日常量，这就是配置生效的证据——不是「我觉得它在省」，是账面上写在模型名后面。
会话页能按 Agent 数，看哪条链路消耗最多，花费最费：
⚠️ Hermes Agent 那一栏上方有提示：这些会话在 magpie 里是只读的，能列出、不能继续也不能删。别指望在这里接管别的工具的会话。
所以magpie的定位非常明确，它就是用来做模型矩阵路由及管理的，它不负责对话框，不提供更多的Agent工具，它需要跟你长期喂养的Agent共同协作，达到一个更好的使用体验。
六、附：4 条模型矩阵路由原则
| 原则 | 怎么配 | 我的例子（命令行可核） |
|---|---|---|
| 按能力分层 | 一套规则 + 一个判定模型 | smart-split 共 4 条规则：难题→claude-opus-5-5、简单任务→auto-deepseek-v4-1-flash、生成图片→auto-gemini-3-1-flash-lite、自动化与调研→gpt-6-luna |
| 按成本 | 组类型选 order，主力第一、便宜第二 | workhorse：gpt-6-sol → deepseek/deepseek-v4-pro |
| 按场景 | 生图、生视频单独成组 | 我没单独建，但已经在 smart-split 里用一条规则把「生成图片」分给了 Gemini 3.1 Flash Lite |
| 按模型名 | 同名模型合并多平台额度 | 自动生成 17 个，auto-deepseek-v4-1-flash 一组含 5 个平台 |
我本机一共 20 个组：3 个手建的（workhorse、免费额度组、smart-split），17 个是 magpie 按模型名自动找出来的。自动组不用管，它们是系统自动生成，给你并额度的底子。
按这四条，模型矩阵就从概念变成了几张能跑的规则表。
七、装完要配置好的 3 件事
1、决定要不要让 magpie 读你的登录凭据
因为从官方角度来讲是严格拒绝反代的，尽管作者声明是调用官方Cli执行，但依然不能保证100%安全，如果担心就不要开订阅识别。
系统是默认开着，读 Claude Code / Codex 的登录文件和钥匙串。不需要订阅复用就关：设置 → 隐私 → 订阅账号，或 magpie accounts discovery off。
2、不要用同一家的多个账号轮流分摊额度
跨不同供应商兜底没问题；同一家多个账号轮流用，作者在 issue #2111 里说过，这正是 Anthropic 条款明确针对的用法。这条别配。
3、网关只给自己机器上的工具用
默认 http://127.0.0.1:3425/v1，key 填 magpie，任何能填 base URL 的工具都能接。但作者在 issue #26 里说，把订阅共享给多人或对外提供服务，是最容易触发风控的用法。
还有个容易忽略的点：开了「局域网共享」之后，网关监听全部网卡。来自其他机器的请求要带 key，本机回环调用不校验。也就是这台机器上的任何进程，不用 key 就能用你挂进去的凭据花额度。
八、进阶：用得久才会碰的四块
网关分账：网关页可以建多个密钥。我本机三个——Magpie、MacBook、win（magpie gateway-key list），各自统计用量，哪台机器吃得多一目了然。网关页显示的模型总数是网关口径，和 Agent 页的「模型 60」不是同一个数。
额度与签到：额度页看各家的 5 小时 / 7 天窗口和重置时间。本机实况（magpie quota）：Claude 5h 已用 6%、7d 56%；Codex Plus 5h 0%、7d 3%，还有 2 张重置卡；DeepSeek 余额 ¥-0.26（欠费）；Gemini CLI 已停服，官方要求迁移到 Antigravity。
部分平台签到送额度。这个开关默认是关的，只显示今日已签到 +100。要自动签得自己去打开，或 magpie accounts checkin。
资源库：支持把 AGENTS.md、MCP、Skills、Hook 维护成一套，同步给多个 Agent，也能从一个调教很久的 Agent 导入。
插件：官方没收录的供应商靠插件补。社区现在 8 个（Kimi Work、OpenCode Zen Free、ZCode、Qoder、Devin、Zed、Factory、Grok）。插件是别人的代码，建议只装你信得过的。
九、如果你需求简单，不建议折腾
如果你只有一个 Agent、一份订阅、也不嫌手改配置、也没有多任务执行的重度需求——够你用了，可以不用装。
另外提醒一个量级：这东西上线 24 天发了 1,259 个版本，中位间隔 12.3 分钟，open issue 1,044 条。你装的是一台一直开着的中间态，不是一块冻住的软件。
快速上手总结（照这个走一遍，立马跑起来）
- 备份三个配置文件 → 装 magpie → 菜单栏出现图标。
- 加一把 API key，看到绿点、模型数不为 0。
- 开 2 到 3 个 Agent，在它们的模型下拉里看到
magpie/group/…。 - 建「按能力分层」这一组，判定器换成免费模型。
- 发两条消息，用
magpie usage today和会话页确认派给了谁。 - 跑一周看额度页的账，再决定要不要接订阅、要不要加更多组。
综合使用下来确实是一个不错的工具，虽然我自己发布了freerouter，但magpie在实现上更加成熟完善，感兴趣的同学可以上手玩一玩。
那么最后问大家一个问题：
搞定了模型路由，你是如何判定自动分配合理的？
你是如何保证输出结果稳定靠谱的？
欢迎评论区聊聊。
#AI工作流 #Agent #模型路由 #效率工具 #magpie