Magpie 路由组是什么
Magpie 路由组(routing group)是开源本机网关 Magpie(GitHub 约 1.1 万 Star,2026-10-13 查询)的核心路由机制:把多个模型或账号打包成一个 group/xxx,代理把它当一个模型来选,网关按设定的模式在成员之间分流——某个成员的配额用完或报错,就静默切到下一个,代理本身看不到错误(官方 README)。典型用法:给 Claude Code 配一个横跨 Claude 订阅、Copilot 和中转 key 的组,窗口烧完自动接力,长任务不用人守。五种分流模式、故障转移与会话粘性,这篇逐一拆开。
为什么需要路由组:配额是碎的
结论:只要有两份以上配额来源,就存在碎片浪费,路由组是 Magpie 的系统解法。
碎从哪来。官方 README 口径:Claude 与 ChatGPT 订阅按 5 小时窗口计,部分权益按周计;你手里往往还有按量 key、中转 key、本地模型。这些配额躺在不同账号里:大号烧到一半,小号整窗闲置;公司号周末不动,个人号周中见底。没有路由组时,每次接力都靠你手动改配置、重开会话——断掉的是工作流。
路由组把接力交给网关:组内每个成员的 key 和账号统一调度(README 原文:the gateway spreads requests over every member’s keys and accounts),你只管干活。
创建路由组:一条命令,代理里选 group/xxx
路由组的定义(docs/reference.md,2026-10-13 抓取):几个模型,来自一个或多个 provider,打包成一个 group/<id> 让代理整体选用。常用命令原样如下:
magpie groups # 看已有的组,含 magpie 自动发现的
magpie group add "Opus anywhere" models=claude/claude-opus-5-5,copilot/claude-opus-5.5 routing=smart
magpie claude group/opus-anywhere # Claude Code 选用这个组
magpie group set opus-anywhere models+=openrouter/anthropic/claude-opus-5.5 routing=usage
magpie group copy opus-anywhere "Opus test" # 复制一份改着玩,互不影响
magpie group rm opus-anywhere # 删除;restore 可找回
三个省事设计。其一,同名模型自动成组:两家 provider 供同一个模型名时,它自己就构成一个组互为备份(reference)。其二,组里可以套组(README:Groups can contain groups)。其三,listed=no 把组内成员模型从各 agent 的模型列表里藏起来,客户端只见 group/xxx 一个选项(reference)。
五种模式逐个讲,附对比表
结论:不确定就选 smart——它是默认值,也最符合”别浪费”的直觉。五种模式的规则与适用场景如下,规则列是 README 原文口径,解读列是工程判断。
| 模式 | 规则(README 原文口径) | 适用场景(工程解读) |
|---|---|---|
smart | 在还有配额的订阅里,用最临近重置的那个,减少重置时的浪费 | 默认选它;多订阅窗口错开时收益最大 |
order | 用第一个模型,直到答不了再换下一个 | 按量付费 key:主 key 顶住,备用兜底 |
rotate | 每一轮换下一个成员 | 请求量大且均匀,想摊到每个号上 |
usage | 最少用的成员先用 | 多账号拉平用量,避免某号长期闲置 |
pace | 每小时用”本周剩余额度最多”的账号,直到它重置 | 周配额订阅:怕重置时刻剩一大截作废 |
weight(补充) | 按权重分流,权重 1 到 1000,平滑交错 | 按固定比例给账号分流量(reference 文档,如 weight=claude/claude-opus-5-5=3) |
表里没说的三点:smart 的收益来自”窗口重置前把余量烧掉”,订阅重置时间越错开越赚;rotate 轮询最均匀,但会打断 prompt 缓存连续性,靠下文的粘性机制补;pace 的目标函数写在 reference 文档里——让每周在重置时刻损失的额度尽量少。order 与 usage 直白,不展开。
多账号 failover:代理看不到错误的工程意义
结论:路由组的价值一半在分流,一半在”无感”——代理只看到一个稳定的模型端点。
基本机制(README):订阅可以加多个账号,配额用完时网关在组内切到下一个账号或模型,代理看不到任何错误。对你的工作流,这改变三件事:过夜长任务不再半夜死在 429 上;会话不用重开,上下文不丢;不用再盯窗口倒计时。
“无感”的关键补充是会话粘性。README 原句(自行抓取补全):A conversation stays with the account that answered it while the vendor’s prompt cache is worth keeping——会话跟着答过它的账号走,直到厂商缓存不再值得复用。reference 文档给了参数级细节:stays= 可设 auto(默认)、session、turn、off、strict;auto 模式下同一轮内固定,跨轮的条件是上一请求至少 1,024 token 命中厂商缓存、且它在最近 5 分钟内应答过;已用掉窗口 98% 的账号不再被粘回。strict 则钉死一个号,报错直接透传给代理。
粘性为什么重要:prompt cache 命中直接省钱、省首 token 延迟,乱切号等于把缓存全废掉。Magpie 的处理是”分流时尽量粘,粘不住才切”,这是它和朴素轮询脚本最大的差别。账号调度还有六步排序兜底(reference 文档):限流的垫底、休息的靠后、会话原账号最优先。
Daily warm-up:把 5 小时窗口对齐到你的工作时段
结论:warm-up 解决的是”窗口从你不在的时候开始烧”的错位问题。
README 事实:Daily warm-up 在你选的时间(或上一个窗口重置的瞬间)启动各 Claude 与 ChatGPT 账号的 5 小时窗口。工程解读:窗口从首次使用起算,第一条消息发得晚,窗口就烧得晚;warm-up 把启动时刻挪到你指定的时间,多账号错峰点火,接力时间轴铺满工作时段(具体行为以官方文档为准)。
观测靠 magpie quota(每个订阅、plan、key 的余量,README);进阶有 magpie quota wait codex 阻塞等额度、magpie quota credits me@example.com off 把账号锁在限额内(reference)。Routing 视图实时显示每个路由决策(README)。
用 profiles 把策略固化成场景
结论:路由组管”一组怎么分”,profiles 管”什么场景用哪套组”。
README 事实:profiles 把所有 agent 的配置存成一个名字(“Budget”、“Focus”),一键切回;每个 agent 还可以有自己的模型短名单,profile 连短名单一起存。典型组合(工程建议):Budget profile 挂便宜模型按 order 跑的组,日常杂活用;Focus profile 挂旗舰模型的 smart 组,攻坚用。切场景就是 magpie save work && magpie use work,不用逐个 agent 改。
设计你自己的路由策略
给一套可以直接抄的方法论(工程建议,非官方说法):
- 按账号类型分组,不按项目分。 订阅账号一组走
smart,吃重置时间差的红利;按量付费 key 一组走order,成本曲线才可控。 - 中转 key 带窗口限额的,把 provider 的 Balance URL 配成中转的
/v1/usage,网关按 5 小时/日/7 天窗口计重(reference 文档;Kimi Code、GLM Coding Plan 这类 plan key 本身按 plan 窗口计重)。 - 高低搭配交给 intent routing。 README 提到它让一个小模型读每轮新请求,难题分给强模型、快问快答分给便宜模型。
- 先 smart 起步,观察一两天再调。 Routing 页的 Requests 列表(reference 支持按会话分组)是最诚实的反馈,别凭感觉调参。
横向比较看 Magpie vs CC Switch vs LiteLLM vs AgentDock;安装步骤在 Magpie 安装与配置教程;背景在 Magpie 是什么。
常见问题
claude code 配额用完怎么办?
把多个订阅账号或中转 key 组成一个 Magpie 路由组(magpie group add … routing=smart),配额用完时网关静默切到下一个成员,Claude Code 看不到报错、会话不中断。单账号可用 magpie quota 盯余量。
多个 claude 账号怎么做负载均衡?
Magpie 路由组内置五种模式:smart 按重置时间就近消耗、order 顺序瀑布、rotate 轮询、usage 拉平用量、pace 按周配额节奏消耗,另有 weight 按比例分流(reference 文档)。多账号加进同一个组即可,网关自动调度,会话粘性保住 prompt 缓存。
magpie 路由模式怎么选?
默认用 smart:它以”重置时剩余最少”为目标,多订阅场景基本总是对的。按量付费 key 选 order 控成本,周配额选 pace 防作废,多号拉平选 usage 或 rotate。拿不准就先 smart 跑一两天,看 Routing 视图的实际决策再调。