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

CodexManager账号命中规则深度解析ordered顺序、balanced均衡与混合轮转3种路由策略【免费下载链接】Codex-Manager一个Codex cli 账号管理与切换工具。为 Codex cli提供本地网关转发。项目地址: https://gitcode.com/gh_mirrors/co/Codex-ManagerCodexManager 是一个 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混合轮转账号优先先尝试本地账号失败或过滤耗尽时回落到聚合 APIhybrid_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字段先确认策略是否符合预期再对照上面的跳过原因清单绝大多数命中疑问都能定位。延伸阅读网关目录架构与选路模块说明crates/service/src/gateway/README.md账号命中规则与额度切号 FAQdocs/zh-CN/report/FAQ与账号命中规则.md最小排障手册docs/zh-CN/report/最小排障手册.md环境变量与运行配置docs/zh-CN/report/环境变量与运行配置说明.md一句话总结ordered按你的序号优先尝试、balanced按密钥模型公平分摊、混合轮转则为账号池兜了一条聚合 API 退路——按需选择再用 trace 日志验证账号命中就不再是黑盒。【免费下载链接】Codex-Manager一个Codex cli 账号管理与切换工具。为 Codex cli提供本地网关转发。项目地址: https://gitcode.com/gh_mirrors/co/Codex-Manager创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考