CodexManager账号命中规则深度解析：ordered顺序、balanced均衡与混合轮转3种路由策略-拓冰网站定制

CodexManager账号命中规则深度解析：ordered顺序、balanced均衡与混合轮转3种路由策略

【免费下载链接】Codex-Manager一个Codex cli 账号管理与切换工具。为 Codex cli提供本地网关转发。项目地址: https://gitcode.com/gh_mirrors/co/Codex-Manager

CodexManager 是一个 Codex CLI 账号管理与切换工具，可为 Codex CLI 提供本地网关转发。当你导入多个账号后，每次请求到底由哪个账号"接单"，就取决于账号命中规则（路由策略）。本文带你吃透 CodexManager 的 3 种路由策略：ordered顺序优先、balanced均衡轮询，以及账号与聚合 API 搭配的混合轮转，并附设置位置与排障技巧，帮你选对策略、看懂每次命中。

一图看懂：请求是如何选中账号的？

一次典型的请求链路是：routing/模块先按策略选出候选账号，再由auth/与upstream/组装并发送上游请求，最后observability/把命中过程写入 trace 日志。你可以直接阅读这份目录说明：crates/service/src/gateway/README.md。

候选池的基础顺序是固定的：账号按sort（排序值）升序、updated_at（更新时间）降序、id升序排列。这个顺序就是ordered模式"顺序"的来源——来自你在账号列表里排好的序号，而不是随机顺序。

ordered 顺序优先模式：如何按优先级尝试账号

ordered是默认策略（未配置CODEXMANAGER_ROUTE_STRATEGY时使用），它的行为可以概括为一句话：按你排好的优先级依次尝试，前序账号不可用就自动顺延。

网关按候选池顺序依次尝试，例如0 -> 1 -> 2 -> 3，这表示"按顺序尝试"，不是"永远命中 0 号"
默认启用健康度 P2C 小窗口换头（窗口默认 3），即头部候选可能被前 3 个中"更健康"的账号替换到第一位
适合场景：你有 1~2 个主力账号，希望平时优先用它，挂了再自动切到备用号

💡前序账号不被命中的 4 个常见原因（排查清单）：

账号状态不是active
账号缺少 token
用量判定不可用：主窗口已用尽，或用量字段缺失
账号处于 cooldown（冷却），或触发了单账号并发上限（默认为 1）

完整规则可对照官方文档：docs/zh-CN/report/FAQ与账号命中规则.md。

balanced 均衡轮询模式：如何按 Key+模型严格轮转

balanced是"公平派"：以平台密钥 + 模型为维度，在所有可用账号间严格轮询，让每个账号的使用量尽量均匀。

不保证从最小sort开始，每个 key、每个模型的轮询状态互相隔离
轮询游标记录的是"本轮起点账号 ID"，账号被临时移除或恢复时，下一轮从该账号之后的可用项继续——不会把旧数字索引错误套到变化后的候选池
默认健康度窗口为 1，不会发生健康度换头；只有显式调大CODEXMANAGER_ROUTE_HEALTH_P2C_BALANCED_WINDOW环境变量时，才会在轮询头部引入健康度挑战者
兼容别名round_robin、round-robin、rr会被后端统一归一化为balanced
适合场景：多账号额度相当，希望分摊用量、延缓单个账号窗口耗尽

混合轮转模式：账号与聚合 API 如何搭配

除了账号之间的路由，CodexManager 还为平台密钥提供了 4 种轮转策略，其中两种是"混合轮转"，把本地账号池和聚合 API 组合成一条链路（归一化逻辑见 crates/service/src/apikey/apikey_profile.rs）：

策略值	中文标签	行为
`account_rotation`	账号轮转	只在本地账号池内按`ordered`/`balanced`路由
`aggregate_api_rotation`	聚合 API 轮转	请求走聚合 API 通道
`hybrid_rotation`	混合轮转（账号优先）	先尝试本地账号，失败或过滤耗尽时回落到聚合 API
`hybrid_aggregate_first_rotation`	混合轮转（聚合优先）	先走聚合 API，失败再回落本地账号

"账号优先聚合兜底"和"聚合优先账号兜底"两种别名都会被识别。理解混合路由的关键在于：它解决的不是"哪个账号先上"，而是"账号池用尽后请求去哪"。

路由策略在哪里设置：设置页与配置项速查

路由策略有三个配置入口，优先级依次生效：

前端设置页：系统设置中的路由策略下拉框（默认显示ordered），对应 apps/src/app/settings/components/gateway-tab-content.tsx
持久化键：gateway.route_strategy
环境变量：CODEXMANAGER_ROUTE_STRATEGY

两个容易忽略的覆盖规则：

手动指定账号（preferred account）：一旦设置，该账号会被旋转到队首，只要它还在可用候选池内，就会覆盖普通ordered/balanced轮转；它不会因为一次 4xx/5xx 或一次临时过滤被自动清除
候选池与额度守卫：接近耗尽的账号（5 小时窗口剩余低于 5%、周窗口剩余低于 10%）会先被移出正常候选，仅当正常池为空时才按兜底开关启用低额度账号；force_enabled状态的账号不受此限制。相关选路实现位于 crates/service/src/gateway/routing/selection.rs

额度耗尽与自动切号：命中规则之外的保险

无论哪种策略，命中失败后还有自动切号兜底：

普通 HTTP429、明确的额度/停用错误，会在同一个客户端请求内继续尝试下一个账号
/v1/responses流式场景下，若上游在 SSE 正文中返回额度错误，网关会在实际文本、工具调用交付前透明切换账号，预检最多等待 10 秒
一旦文本或工具调用已交付给客户端，网关不会再透明重放到另一账号，避免重复输出、重复计费

另外，每次请求的route_strategy都会写入请求日志（迁移见 crates/core/migrations/068_request_logs_route_strategy_source.sql），方便你按策略维度复盘历史请求。

排障技巧：用 trace 日志看懂每次命中过程

遇到"为什么没命中我想用的账号"时，打开数据库同目录的gateway-trace.log，重点看三类事件：

CANDIDATE_POOL：本次请求的候选顺序（含strategy与ordered_candidates字段）
CANDIDATE_START/CANDIDATE_SKIP：实际尝试了哪个账号、跳过了谁以及跳过原因
REQUEST_FINAL：最终命中的账号

结合日志里的route_strategy字段，先确认"策略是否符合预期"，再对照上面的跳过原因清单，绝大多数命中疑问都能定位。

资讯详情

CodexManager账号命中规则深度解析：ordered顺序、balanced均衡与混合轮转3种路由策略