把订阅接进 Agent：9Router、Magpie、CLIProxyAPI 源码深读

这三款工具做的是同一件事：在本机或服务器上开一个兼容 OpenAI / Anthropic / Gemini 协议的端口，让 Claude Code、Codex、OpenCode 等编码 Agent 把请求发给它，再由它转发到你已有的订阅账号或 API key。它们和第 2 篇的 Sub2API、New API、LiteLLM 的区别在于重心：这三款重在接入个人手里的订阅账号，用户管理、计费和充值都很薄，或者干脆没有。

文中证据分四类，就近标注：〔文档〕 官方 README / 文档原话；〔源码〕 本文核对过的具体代码；〔部署观察〕 本站自己部署时看到的现象，只代表该版本、该配置；〔推断〕 由前几类推出、没有实测的结论。本文没有做性能测试，不给吞吐、内存等数字。

1. 先看版本和许可

三款都更新得很快，选型前要先固定版本。

• 9Router：GitHub Releases 页面停在 v0.5.35（7 月），实际版本记录在 CHANGELOG 和标签里，一直到 v0.5.104。
• Magpie：维护者在 LESSONS.md 里写明，代码由 agent 编写、评审、合并并发布；2026-10-05 一天有 220 次提交、约 170 次发布。仓库不接受外部 PR，反馈要走 Discord。
• CLIProxyAPI：社区有若干标着 “Plus” 的分发和面板，本文只讨论本体仓库，不把这些分发的能力算到本体头上。

2. 9Router：功能最多的个人路由器，也改动请求最多

形态与存储。 9Router 用 npm install -g 9router 安装，或用 Docker 运行。服务启动后监听 20128 端口，管理面板和 /v1/* 接口共用这个端口〔文档〕。数据存在 SQLite 文件 ~/.9router/db/data.sqlite 里，可以用 DATA_DIR 改位置。代码会按运行时依次尝试 bun:sqlite、better-sqlite3、node:sqlite 和 sql.js 四种驱动〔源码：paths.js〕。上游连接（含 OAuth 令牌）存在 providerConnections 表的 data 文本列里。数据库层没有看到额外加密，凭据安全取决于文件权限和主机本身〔源码 + 推断〕。从源码构建时 README 建议先临时加 2 GB swap，小内存机器最好直接用镜像。

接入与协议。 上游分三类：OAuth 订阅（Claude Code、Codex、Copilot、Cursor、Kiro 等）、40 多家 API key 服务商、免登录的免费渠道〔文档〕。对外的路由比只写着 “OpenAI 兼容” 的 README 更多：源码里有 /v1/chat/completions、/v1/responses、/v1/messages、/v1beta/models/*，还有嵌入、图片、语音和视频接口。

格式转换以 OpenAI 格式为中转：源格式先转成 OpenAI，再转成目标格式。只有注册了直连转换器的组合（比如 Claude→Kiro）才跳过中转〔源码：translator/index.js〕。中转的好处是新增一家上游只要写一对转换器。代价是两种非 OpenAI 格式之间互转时，一方特有、OpenAI 格式里没有的字段可能在中途丢掉〔推断〕。

多账号与失败语义。 账号选择默认用 fill-first，也就是按优先级先用满第一个账号。可以改成 round-robin，每个账号连续用满 3 次再换下一个〔源码：auth.js〕。错误先按文本规则匹配，再按 HTTP 状态码匹配：

• 文本含 “rate limit”“quota exceeded”“overloaded” 等字样时，账号按指数退避冷却，从 2 秒起，最长 5 分钟；
• 上游报出的重置时间最多只认 30 分钟；
• 没有匹配到任何规则的错误冷却 30 秒〔源码：errorConfig.js〕。

有一个细节处理得好：除 401、402、403、429 以外的 4xx（上下文超长、请求格式错误等）不会切换账号，而是把上游错误原样返回。源码注释写明了原因：如果因为请求本身的错误把唯一的账号冷却掉，之后所有请求都会收到同一条错误，真正的原因反而看不到了〔源码：accountFallback.js〕。在账号这一层之上还有 combo（模型组合），按“订阅 → 便宜 → 免费”逐级回退。

用量口径要分开看。 README 明确说面板上的“成本”只是按公开价估算的“如果走付费 API 要花多少”，不是账单〔文档：Costs & Billing〕。更容易被忽略的是：流式响应结束时，9Router 会给返回给客户端的 usage 加上 2000 个输入 token，注释说是为了“防止上下文错误”。本地日志记录的仍是原值〔源码：usageTracking.js、stream.js〕。如果在 9Router 前面再放一层按响应 usage 计费的平台，每次流式请求都会多记 2000 个输入 token。本站早期部署这样串联过，当时只能自己打补丁去掉这个缓冲〔部署观察〕；当前 master 里这段逻辑仍在〔源码〕。

会改写请求的功能。 下面这些功能都会改变上游收到的内容：

• RTK、Caveman、Ponytail 等“省 token”功能会压缩工具输出，或注入提示词〔文档〕。README 说能省 20–40% 的 token，这是维护者自己的说法，本文没有测试。单个请求可以用 X-9Router-Token-Saver: off 关闭。
• CodeBuddy 执行器会把识别为编码 Agent 的系统提示词替换成一句中性提示，并强制开启流式〔源码：codebuddy-cn.js〕。Agent 依赖的系统指令在这条路径上会丢失。
• 可选的 MITM 模块会往系统信任库安装本地根证书，并修改 hosts 文件，用来接管部分 IDE 的流量（src/mitm/cert/install.js、src/mitm/dns/）。这属于高权限改动，开启前要清楚它做了什么。
• 部分渠道带有模拟官方客户端身份的处理，CHANGELOG 里有记录。这类适配随时可能失效，也正是条款风险集中的地方。

适合与不适合。 适合一个人手上有好几家订阅和免费额度、想要图形面板、配额倒计时和一键回退的开发者。安全默认值是合理的：requireLogin 和 requireApiKey 都默认开启〔源码：settingsRepo.js〕。

不适合：

• 需要逐字透传、或要求上游 usage 可直接对账的场景；
• 多租户计费；
• 对“网关改写系统提示”零容忍的团队。

云同步的服务端不在这个仓库里，用前要想清楚配置要不要出本机。

3. Magpie：以 Agent 为中心的桌面网关，账号策略最细

形态。 Magpie 是一个 Go 单二进制，同时提供菜单栏应用、窗口、TUI、Web UI 和 CLI，也有 Docker 镜像，还能在 Termux 上跑〔文档〕。它和另外两款最大的不同在于：除了网关，它还会改写每个 Agent 自己的配置文件。在列表里给 Claude Code 选一个模型，Magpie 会原子地修改 Claude Code 配置里对应的那个键，注释和格式保持不变；配合 profile 可以一次切换所有 Agent。网关默认监听 127.0.0.1:3425，支持 OpenAI Chat、Responses、Anthropic Messages 和 Gemini 四种协议互转，包括流式、工具调用和推理内容〔文档〕。

凭据与刷新：尽量不另存一份。 对已经登录的 Agent，Magpie 每次都直接读取它们自己的登录文件（Claude Code 的钥匙串或 credentials 文件、Codex 的 auth.json 等），并按 Agent 自己的方式刷新令牌，再把轮换后的令牌写回原处〔文档：Signed-in agents〕。从文件导入 ChatGPT 账号时，Magpie 会先刷新一次令牌。文档说导入后 Magpie 成为该账号的唯一持有者，来源工具需要重新登录〔文档：L1646〕。按文档的描述，这是刷新时令牌轮换导致旧副本失效的结果，并不是 Magpie 主动去调用来源工具的登出。对于采用 refresh token 轮换、又没有跨进程协调的集成，让同一凭据只有一个写入者是稳妥的做法。但各提供方对旧令牌的宽限期和并发刷新的规则可能不同，不能一概而论。

Claude 订阅走的是另一条路：Magpie 驱动本机已登录的 claude 进程，用 MCP 把调用方的工具桥接进去，所以需要先装好并登录 Claude Code〔文档：L1617〕。如果不想让 Magpie 读取任何本机登录，可以用 MAGPIE_NO_ACCOUNTS=1 或 magpie accounts discovery off 关闭。WorkBuddy 这类订阅已经改由社区插件 @magpie-community/opencode-workbuddy-auth 提供，内置代码只保留迁移和签到等少量功能〔源码：workbuddy.go〕。

路由：按额度何时重置来排队。 路由组有 smart、order、rotate、usage、pace 五种模式。默认的 Smart 先排除已用 90% 以上的账号，再在剩下的账号里优先用额度最快重置的那个，因为它剩下的额度到重置时就作废了。会话粘性是带条件的：同一会话只有在上一轮命中或写入了至少 1024 token 的厂商缓存、并且 5 分钟内应答过时，才继续留在原账号〔文档：How magpie picks an account〕。

失败时的语义写得也很具体：

• 表示额度用完的 429：账号休息到额度恢复。恢复时间依次取拒绝消息里的重置时间、最近一次读到的窗口重置时间、Retry-After（最多 1 小时），都没有就休息 15 分钟。
• 短暂限流：按厂商要求的时间休息，否则从 1 分钟开始，连续触发就翻倍，最多 30 分钟。
• 其他错误：从 1 分钟开始递增，最多 10 分钟。
• 换账号重试只在响应还没开始发送时进行〔文档：L1493〕。

网关 key 与用量。 每个网关 key 最多可以设 5 条限额，每条按 token 或估算美元计，周期可以是日、周、月、N 天或 N 小时。key 还可以限定可用的模型，以及可用的账号〔文档：L529〕。文档也承认了限额的边界：成本是按列表价估算的；同时发出的多个请求可能超出约一次调用的量。每次请求记一行 usage.jsonl，路由决策按天存档，并且可以导出到 OTLP。

面板的启动方式要分清。 v0.1.1293 的源码里：

• magpie serve 只有网关；
• magpie serve --web 在同一进程里另开一个监听地址提供网页面板，访问需要 MAGPIE_WEB_KEY 或启动链接里的 key，由 webGuard 校验〔源码：web_cli.go、web.go〕；
• 单独的 magpie web 自带完整的网关后端。如果网关已被另一个 Magpie 进程占用，它只显示同一份设置，等对方停止后再接管网关。

所以不要在 serve 旁边再并行起一个 magpie web 当“只读面板”：它不是只读的，而且会参与接管网关。

适合与不适合。 适合同时用多个 Agent、多个订阅的个人开发者，也适合需要按 key 隔离账号池的小型共享网关。

要注意的地方：

• 每天会发一次使用统计（随机 ID、版本、用了哪些 Agent 和 provider 等），可以用 DO_NOT_TRACK=1 关闭〔文档：Privacy〕；
• 发版极快，必须固定版本或镜像 digest；
• 插件运行时依赖 Bun 和 npm，带来额外的供应链面；
• 不提供面向终端用户的充值和计费。

本站部署观察（WorkBuddy 场景）

下面是本站把 WorkBuddy 账号从旧网关迁到 Magpie 时得到的经验，只代表 v0.1.1293 加 WorkBuddy 插件 0.1.25 这个组合：

• 令牌单写入者（本次部署策略）。 迁移后只有 Magpie 负责刷新令牌，旁路的采集器改成只读，用按账号池绑定的网关 key 读取 /v1/magpie/quotas 和请求台账。采集和认证不放在同一个进程里。
• 签到只覆盖国内版。 国内版账号的每日签到已经确认领取成功，台账和日志都对得上。源码注释写的是“只有国内版有签到活动，WorkBuddy AI 默认关闭”〔源码：workbuddy_checkin.go〕，所以在这个版本组合里，国际版签到不在 Magpie 的覆盖范围内。国际站官方现在有没有签到活动，我们没有确认，不能写成“所有账号都会自动签到”。
• 缺失值保留未知。 成功请求的积分字段都是数值，包括 0；缺积分的几条记录全是 400 失败请求。我们把这些记为“未知”，没有填 0，也不推断“失败请求不扣积分”。
• 账号档位不等于协议支持。 某个模型被上游以“当前用户类型不允许”拒绝，而同一账号请求另一个模型正常。这说明的是账号档位限制，不能推出模型已下架，也不能推出 Magpie 不支持该协议。
• 面板功能存在，不等于已经部署。 这个版本支持网页面板，但我们的部署还没有配置面板的访问入口和凭据。

4. CLIProxyAPI：配置驱动的无头代理，可观测性要自己补

形态与安全默认。 CLIProxyAPI 是一个 Go 二进制加一个 config.yaml，默认端口 8317。它有一处默认值要特别注意：server.host 默认为空字符串，含义是监听所有网卡，只在本机用时要手动改成 127.0.0.1〔源码：config.example.yaml〕。客户端用 access.api-keys 鉴权，和上游 key 完全分开。管理 API 必须设置 secret-key，明文写入的值会在启动时被哈希；留空则整个管理 API 关闭，返回 404。allow-remote 默认是 false〔源码：L81-L89〕。

管理面板 CPAMC 是单独的仓库，默认从 GitHub 下载并自动更新。对供应链敏感的环境可以打开 disable-auto-update-panel，或者干脆关掉控制面板。官方另有桌面客户端 EasyCLIProxyAPI，代码也可以作为 Go SDK 嵌入别的程序。

接入与凭据。 OAuth 登录覆盖 Claude、Codex、Antigravity、Kimi、xAI、Devin、Meta，以及插件注册的 provider；Vertex 用导入服务账号的方式接入〔文档：management-api-v8.md〕。凭据以 JSON 文件形式存在 ~/.cli-proxy-api 目录，store 包另外提供 PostgreSQL、Git 和对象存储三种后端〔源码〕。

协议转换不经过中转格式：internal/translator 下按“源格式/目标格式”逐对组织目录，覆盖 OpenAI、Claude、Gemini、Codex、Antigravity 和 Gemini Interactions。README 写明支持流式、非流式和 WebSocket（视上游而定），以及 tools 和图片输入〔文档〕。

多账号与失败语义。 routing.strategy 有三种：round-robin（默认）、weighted-round-robin 和 fill-first。会话粘性默认关闭；打开后，绑定关系保留 1 小时，子 Agent 默认沿用父会话的凭据，以便复用提示缓存。session-affinity-rebind-on: quota 的含义是：只有额度和认证类错误才改绑凭据，408、5xx 这类瞬时错误只在本次请求里切换。重试按“轮”进行，默认额外 3 轮，适用于 403、408、429 和 5xx〔源码：routing 段〕。这套配置的粒度在三款里最细，代价是默认值不一定适合你，需要逐项读注释。

用量：从 v6.10.0 起不再内置统计。 README 写明，从 v6.10.0 起本体和 CPAMC 都不再提供内置的用量统计，推荐改用 CPA Usage Keeper 等外部项目〔文档：README〕。配置里 usage-statistics-enabled 默认是 false；打开后，用量事件也只在内存队列里保留 60 秒（最多 3600 秒），由外部程序通过管理 API 的 /observability/usage/queue 取走〔源码：L1174-L1181〕。也就是说，消费方停一会儿，这段时间的用量就丢了；要做账务，必须配一个常驻的采集方〔推断〕。

此外还有 commercial-mode，用来在高并发下关掉高开销的日志中间件；还有一个 Home 集群模式，需要 HOME_JWT，并且由 Home 下发的并发配置优先于本地配置。

适合与不适合。 适合愿意写 YAML、需要无头部署、要把订阅凭据池做成稳定后端供上层平台调用的人。它常被放在 New API 或 Sub2API 这类平台的后面，第 3 篇会讲这种组合。不适合想要开箱即用的用量面板和成本报表的人，也不适合不想自己维护外部采集组件的人。

5. 三款放在一起看

三款都没有“用户注册、充值、按倍率计费”这一层。需要这一层时，看第 2 篇。

精选参考资料

• 9Router：README、CHANGELOG、accountFallback.js、LICENSE
• Magpie：README、docs/reference.md、LESSONS.md、LICENSE
• CLIProxyAPI：README、config.example.yaml、Management API v8、store 包（PG / Git / 对象存储）、LICENSE