Codex-X 供应商自动故障转移是怎么做到的：本地路由、熔断与恢复机制拆解

【免费下载链接】Codex-XOpenAI Codex 桌面端/CLI 的可视化管理工具，具有Provider/API 切换、会话同步、提示词注入、Skills/MCP 管理、TOML 配置可视化的跨平台工具。项目地址: https://gitcode.com/GitHub_Trending/co/Codex-X

你的主力 API 供应商突然开始返回 429，或者干脆连不通。此刻你要做的不是等它恢复，而是：打开 Codex 的 config.toml，找到当前供应商的 base_url，手动改成备用地址，再把 API Key 换掉，然后重新开会话。一次十几分钟，一次任务就废了。

如果你同时挂着三个供应商，这个流程会在凌晨两点重复三次。你甚至不敢让 Codex-X 之外的任何工具碰 config.toml，因为改错了恢复成本高，而改对了也没什么奖励——只是省了这一次。

这个痛点的本质是：Codex 原生只认一条供应商链路，链路断了它不会自己换。

Codex-X 的供应商自动故障转移（failover）就是为这一步设计的：它在本地起一个监听端口接管 Codex 的请求，按你排的优先级队列把请求转发给真正可用的供应商，并对持续失败的供应商执行熔断（连续失败达到阈值后暂停发送请求的保护机制）。本文拆解它的三个内部机制，并给出可以机械判定的验证步骤。

它为什么存在：Codex 断链时的手动成本

Codex 的供应商配置写在 config.toml 的model_providers表里，一次只生效一个。链路断开时，恢复动作落在你身上：编辑文件、换 Key、重开会话。

自动故障转移把这三个动作搬到了应用内部。你预先声明「主供应商是 P1，备胎按顺序是 P2、P3」，之后 P1 返回可重试错误时，请求自动落到 P2，你这边只会多等几秒。

它同时解决两件事：接管（让 Codex 的流量先经过一个本地端口）与切换（本地端口背后决定流量去哪家）。两件事分开做，是因为接管本身必须可回滚——任何一步失败都不能把 config.toml 留在半截状态。

它怎么进系统：固定监听端口、配置接管与熔断三件套

第一步：本地监听器与一个写死的端口

启用本地路由后，Codex-X 在127.0.0.1:15721上绑定一个 HTTP 监听器，这个地址和队列上限都是编译期常量，见 config.rs：

pub(crate) const DEFAULT_LISTEN_ADDRESS: &str = "127.0.0.1"; pub(crate) const DEFAULT_LISTEN_PORT: u16 = 15721; pub(crate) const MAX_QUEUE: usize = 64;

这就是全文的「可观察细节」：启用接管后，你的 config.toml 里会凭空多出一个指向本地回环地址的 base_url。看到这个地址，就说明请求已经不再直连供应商，而是走了 Codex-X 的本地路由。

超时与重试参数集中在 RoutingTuning：默认最多重试 3 次（即最多尝试 4 条链路），流式首字节超时 60 秒，全部参数有合法区间校验，越界直接拒绝保存。

第二步：接管——只改一个字段，且留了回滚账本

开启「为 Codex 启用路由」并保存时，attach_route 做四件事，顺序固定：

1. 读当前配置，生成一份原始表备份；
2. 把当前供应商表的base_url替换为本地地址，写入proxy_table（controller.rs），供应商名称显示为Codex-X Local Router；
3. 把这次改动的完整「账本」（原始表内容、端口、路由 token）存进应用的 SQLiteprovider_failover表；
4. 用原子写落盘 config.toml。

任何一步失败，前几步的回滚都会执行：配置写失败就恢复数据库记录，路由配置下发失败就恢复文件快照。这是条件 → 动作 → 可观察结果：只要接管成功，config.toml 里的base_url唯一期望值是http://127.0.0.1:15721/v1；如果你在运行中途手改了 config.toml，inspect_external_change 会检测到外部变更，主动解除接管并留下状态提示「Codex 配置已在外部改变，已停止接管」，而不是悄悄抢回去。

第三步：熔断与恢复——三个状态，数字都是默认值

每个队列供应商各挂一个熔断器，状态机只有三态（circuit_breaker.rs）：

pub enum CircuitState { Closed, // 正常放行 Open, // 熔断中，拒绝请求 HalfOpen, // 试探恢复 }

默认参数（CircuitBreakerConfig）：连续失败 4 次或错误率（满 10 次请求后统计）达到 60% 时切到 Open；Open 状态持续 60 秒后切到 HalfOpen；HalfOpen 一次只放行 1 个探测请求，连续 2 次成功才回到 Closed，探测失败立刻打回 Open。给不听话的供应商挂上「暂时休息」的牌子，恢复靠计时和试探，不靠人肉。

请求侧的判定在 handle_request：按队列顺序逐条链路尝试，某家返回可重试状态码（retryable_status：4xx/5xx 中排除 400、405、413 等客户端错误）就记录失败、跳到下一家；已经开始流式输出的回复不会重放，只走一条链路。

它能接什么活

队列上限 64 家、第一位即 P1、官方登录账号不参与自动切换，这三条在保存时强制校验（normalized_settings），非法队列直接报错不落盘。

怎么确认它真的生效

全部验证不需要抓包，只看界面与 config.toml 两处，每条都是「输入 → 唯一期望输出 → 判定标准」：

步骤 2 是核心判定：请求成功与 P1 进入 Open 必须同时成立，缺一说明队列顺序或熔断计数没按预期走。状态字段定义在 FailoverStatus，界面徽标映射见 ProviderFailoverPage.tsx。

# 接管成功后，config.toml 中当前供应商表的关键行 [model_providers.你的供应商key] name = "Codex-X Local Router" base_url = "http://127.0.0.1:15721/v1" wire_api = "responses"

什么时候别用它

与已有配置的共存方式：接管只替换当前供应商表的base_url等受管字段，你的其余配置行原样保留；解除接管或崩溃恢复时按账本逐字段还原，你自己加的字段不受影响。边界立场：Codex-X 只转发与切换，不替你决定用哪家供应商的模型——队列里排什么顺序、用什么模型，完全由你的配置决定，它不做任何「替选」。

回收一下：接管机制（本地监听 + config.toml 原子改写 + SQLite 账本）负责「流量怎么进来且不丢」，熔断机制（三态状态机 + 默认 4/60/2 参数）负责「坏供应商怎么被跳过、怎么自己回来」，队列校验（64 家上限、官方账号排除、凭证头拒绝）负责「什么能进这个链路」。三步验证对应的正是这三块：看到 15721 地址说明接管成立，看到 P1 倒计时说明熔断成立，队列保存不报错说明校验成立。

【免费下载链接】Codex-XOpenAI Codex 桌面端/CLI 的可视化管理工具，具有Provider/API 切换、会话同步、提示词注入、Skills/MCP 管理、TOML 配置可视化的跨平台工具。项目地址: https://gitcode.com/GitHub_Trending/co/Codex-X