Codex CLI 备用源配置：解决 429 与额度耗尽实战

下午三点四十,我正让 Codex 把一段三千多行的老模块拆开重构,跑到第七轮工具调用的时候,终端里蹦出一行429 too many requests,紧接着就是codex exceeded retry limit, last status: 429 too many requests。那一刻我很清楚,不是网络抽风,是 5 小时窗口的额度被我一个上午加小半个下午的连续重构吃干净了。摆在面前的选择只有两个:要么干等窗口重置,要么马上给 Codex 挂一个备用源,一条命令切过去接着干。我选了后者,而且这件事做完之后,我几乎再也没被额度打断过节奏。

这篇文章讲的就是这套备用源方案:它是什么、为什么值得配、怎么接进 Codex CLI、切换的时候会撞上哪些报错、以及哪些参数不对齐会让备用源明明接通了却干不了活。适合已经在用 Codex CLI 或准备上手的人看,不管你是刚装完还在研究codex安装教程,还是已经能熟练跑codex cli,都能从里面抄到能直接用的配置。我假设你至少能打开终端、会改文本文件,剩下的细节我都会讲透。

1. 5 小时窗口是怎么被悄悄吃光的

1.1 用量窗口的计费口径,和你想的不太一样

很多人对 Codex 额度的第一印象是"问一句算一次",这个理解偏差很大。实际计费口径是按 token 消耗和请求次数综合算的,而且是在一个滚动的时间窗口里统计。也就是说,你在上午十点用掉的量,会一直挂在这个窗口里,直到窗口滑过去才释放。具体是一次几小时重置、总共能用多少,会随账号档位变化,我不想给你一个记死的数字,以你客户端里弹出的提示为准就行。

真正需要注意的是这个机制的连带效应:窗口内的额度是共享的,你不可能把它拆成"上午额度"和"下午额度"分开用。所以一旦你上午做了一次大重构,下午想再推进一个模块,很可能就卡在中间那口气上。我在最开始的几天里,习惯把重活和轻活混着排,结果就是经常在下午两三点撞墙。后来我把重活集中到窗口刚重置的那段时间做,轻活留给窗口尾部,撞墙频率明显下降。

还有一点容易被忽略:额度是按账号算的,不是按机器算。同一账号在笔记本、台式机、VS Code 里的 Codex 插件同时开着,消耗是加在一起的。我有一次以为是额度算错了,排查了半天才发现是另一台机器上挂着个忘关的会话,一直在轮询重连,顺手也把额度带走了一部分。

1.2 真正吃额度的是工具调用循环,不是你的提问

这是我想重点说的一件事。你打的那句话可能只有二十个字,但 Codex 为了回答你,会读文件、跑命令、看 diff、再读文件,每一轮都要把上下文重新送上去。你以为是一问一答,实际上是十几二十次请求在里面滚动。

我做过一个粗略的统计:一个中等复杂度的重构任务,我自己的输入大概占全部 token 消耗的百分之三到百分之五,剩下全是工具调用的往返。尤其是它读大文件的时候,一次拉进来几千行,下一轮又带着这堆内容去跑测试,再下一轮还要带着测试输出,上下文像滚雪球一样涨。分段拆任务之所以能省额度,根本原因不是"任务变小了",而是每一段的上下文都被重置了,后面几轮不用背着前面的包袱跑。

理解了这一层,你就能明白为什么有些操作看起来没干什么却特别贵:让它在一个巨大仓库里做全文搜索、让它反复跑同一个失败的测试、让它自己猜半天再改。我在初期特别爱干的一件事是"你帮我看看为什么这个测试挂了",然后放手让它自己折腾,结果它跑了二十多轮才找到问题。现在我改成先自己定位到具体文件和行号,再让它修,额度消耗能压掉六七成。

1.3 额度耗尽、并发限流、上游抖动,三种情况别混为一谈

撞上错误提示的时候,先别急着切备用源,得分清是哪一类问题。这三种表现很像,处理方式完全不同。

我踩过最典型的一个坑,是把"上游抖动"当成"额度用尽"。有天晚上一直提示重连,我直接切了备用源,结果备用源也慢,折腾了半小时才发现是主通道自己在恢复,再切回去就正常了。后来我养成了一个习惯:出现报错先看提示原文,是明确的额度类提示才切,含糊的就先等三到五分钟再看一眼。

2. 备用源的三种形态,我为什么先做本地那一种

2.1 本地自托管模型:零边际成本,但要挑对模型

备用源的第一种形态,是在自己机器或者局域网里跑一个模型服务,对外暴露 OpenAI 兼容接口。常见做法是用 Ollama 起一个本地服务,或者用 vLLM 起一个带并发能力的推理服务。这条路最大的好处是成本和可控性:不消耗任何外部额度,代码内容不出本机,想跑多久跑多久。对于"主力通道额度耗尽时顶一两个小时"这种需求,它是最合适的兜底。

但它有一个硬门槛:模型能力。Codex 这类工具对模型的工具调用能力、长上下文理解、指令遵循要求都不低,如果随便找一个通用小模型来顶班,它可能连你想让它改哪个文件都搞不清楚,最后你花在纠正上的时间比自己写还多。我的经验是,本地备用源优先选代码专精的模型,参数量别太小,量化等级别压得太狠——用 Q4 量化跑代码任务,经常出现改对了语法但改错了逻辑的情况。

另外要提前说明,这是基于常见实践的合理补充:不同版本的 Codex CLI 对本地服务的兼容程度会有差异,有的字段名会改,所以你一定要以自己本地codex --help的输出和该版本的配置文档为准,别照抄我下面给的配置就完事。

2.2 另一家独立供应商账号:性价比高,但要处理接口差异

第二种形态是再准备一个独立的模型供应商账号。这条路的好处是能力有保障,切换过去之后基本可以无缝接着干活,延迟通常也能接受。国内外的模型服务里,不少都提供了 OpenAI 兼容的对话接口,配置上不算复杂。

麻烦的地方在于接口协议不一致。Codex CLI 在对接不同供应商时,会用到不同的协议模式,有的走 Responses 风格的接口,有的走传统的对话补全接口。如果你的备用供应商只支持后者,你必须在配置里明确告诉 Codex 用哪种模式,否则请求会打到错误的端点上,表现就是各种奇怪的报错。这一点我在第四节会详细拆。

还有一个现实问题:独立供应商账号也需要管理密钥、可能需要实名或验证,额度和限流规则也各不相同。所以它更适合当"第二主力",也就是你平时就配好、偶尔小任务上跑一跑,确认它能用,而不是等到出事那天才第一次配。

2.3 自建接入网关:团队场景更合适,个人没必要

第三种形态是自己搭一层接入网关,统一管理密钥、做调用审计、按人分配限额。如果是团队多人共用,这个做法很值,因为你可以把"谁用了多少"这件事看清楚,也能在主通道和备用通道之间做自动分流。

个人用户我不太建议走这条路,维护成本远大于收益,尤其是你只是想解决"额度用完了顶一下"这种问题。这里顺便提一个安全上的提醒:我不建议使用来源不明的第三方转发服务来充当备用源。原因很直接,这类服务在链路中间能看到你发出去的完整代码内容,而 Codex 场景里你发的往往是整个项目的源码。密钥和代码这两样东西一旦外泄,代价远高于省下来的那点额度。

3. 把备用源写进 config.toml:一次配置,两条通道

3.1 配置文件在哪,最小可用结构长什么样

Codex CLI 的主配置文件通常放在用户目录下的.codex/config.toml。Windows 上大致是C:\Users\你的用户名\.codex\config.toml,macOS 和 Linux 上是~/.codex/config.toml。这个文件不存在就自己新建一个,注意是 TOML 格式,键值对用等号,表用方括号。

一个能跑起来的最简结构大概是这样:

# 默认使用的模型和供应商 model = "your-main-model" model_provider = "main" [model_providers.main] name = "Main" base_url = "https://主通道的接口地址/v1" env_key = "MAIN_API_KEY" wire_api = "responses" [model_providers.backup] name = "Backup" base_url = "http://127.0.0.1:11434/v1" env_key = "BACKUP_API_KEY" wire_api = "chat"

这里几个字段值得单独说清楚。base_url指向的是接口根路径,大部分兼容服务都以/v1结尾,写错了会直接 404,而且报错信息往往很含糊,所以配置完先确认这一项。env_key不是让你把密钥写进来,而是告诉 Codex 去读哪个环境变量,这是安全上非常关键的一个设计,下一小节展开。wire_api决定走哪种协议模式,本地服务和多数兼容服务用chat,官方主通道通常用responses,这一项填错是后面一大堆怪报错的源头。

3.2 用 profile 装下两套供应商,切换只改一个参数

配置文件支持 profile 机制,这是整套方案的核心。你可以把主通道和备用源分别定义成一个 profile,平时用默认的,需要切换时指定 profile 名字即可。

[profiles.main] model = "your-main-model" model_provider = "main" model_reasoning_effort = "high" [profiles.backup] model = "your-local-code-model" model_provider = "backup" model_reasoning_effort = "medium"

启动时带上 profile 名字:

codex --profile backup

这样切换的成本就降到了一条命令。比起到处翻文件改model_provider,这种方式几乎不会改错,也不会在慌乱的时候把主通道配置弄坏。我在配置里把main设为默认 profile,把backup准备好但不启用,主通道一挂就换参数,切回来的时候什么都不用改。

3.3 密钥走环境变量,别写进配置文件

配置里写env_key = "MAIN_API_KEY",意思是让 Codex 去读名为MAIN_API_KEY的环境变量。这样做的原因很实际:配置文件很容易被同步到云盘、被提交进仓库、被截图分享出去,密钥写在里面基本等于公开。环境变量则只在当前 shell 会话里存在,风险小得多。

在 macOS 或 Linux 上大致是这样:

export MAIN_API_KEY="你的主通道密钥" export BACKUP_API_KEY="备用源的密钥,本地服务可随便填一个占位值"

Windows PowerShell 里:

$env:MAIN_API_KEY="你的主通道密钥" $env:BACKUP_API_KEY="本地占位值"

想省事就写进 shell 的启动文件里。本地服务通常不校验密钥,但很多客户端要求这个字段非空,所以随便填一个占位字符串就行,别留空,留空有时候会被判定为配置缺失。

3.4 三种切换手感:改文件、写别名、用切换工具

最原始的方式是手改配置文件,适合偶尔切一次。稍微顺手一点的是在 shell 里写两个别名:

alias cx='codex --profile main' alias cxb='codex --profile backup'

这样你敲cx就是走主通道,敲cxb就是走备用源,肌肉记忆一旦形成,切换几乎不需要思考。我个人长期用的是这种,因为它完全透明,出问题的时候一眼就能看出走的哪条路。

再往上就是配置切换类的小工具,圈子里常提到的 ccswitch 就是这类东西。它的思路是帮你管理多套配置并在它们之间快速切换,省掉手改文件的步骤,也能同时管多个工具的配置。用这类工具要注意一件事:有些实现会在本地起一个转换层来承接请求,这一层如果处理不好协议差异,就会出现类似cc switch local proxy failed while handling codex endpoint /responses的报错。我的建议是,如果你的备用源本身支持对话补全协议,就在配置里把wire_api直接设成chat,让 Codex 直连备用源,绕开转换层,少一层就少一类故障。

4. 切换之后最常撞上的五个报错,逐个拆

4.1 本地转换层处理 /responses 失败

这个报错的完整形态通常是cc switch local proxy failed while handling codex endpoint /responses。字面意思是本地那一层在处理 Codex 发往/responses的请求时失败了。根因一般有两个:一是转换层只实现了对话补全协议的转发,没实现 Responses 风格的接口,Codex 一发过来就对不上;二是备用源本身不接受这种请求格式,转换层也没做适配。

排查链路我是这么走的:先确认 Codex 到底在往哪个端点发请求,也就是看配置里的wire_api是responses还是chat;再去确认备用源对外暴露的端点是什么,本地服务一般是/v1/chat/completions;最后看两者是否匹配。绝大多数情况下,把wire_api改成chat、base_url改成备用源的根地址,问题就消失了。改完记得重启会话,配置不会热加载。

4.2 找不到 CLI 可执行文件

unable to locate the codex cli binary or required runtime components这个报错,和你切不切备用源没关系,但切换过程中特别容易撞上,因为它经常发生在你刚装完、准备第一次配置的时候。它说的是客户端找不到 CLI 本体或者运行所需的组件。

这条报错的高发场景是在编辑器插件里。编辑器扩展本身往往只是一个外壳,真正干活的是命令行程序,如果它的运行环境里没有把 CLI 的安装路径加进去,就会报这个错。我的处理顺序是:先在独立终端里确认命令行程序能不能直接跑起来;能跑,再去查编辑器的运行环境是否继承了 PATH;Windows 上还得留意安装过程有没有真的完成,codex windows 安装未完成是相当常见的状态,看着像装好了,其实依赖没落地。重装一遍并确认安装脚本走到最后一步,通常能解决。

4.3 提示某个模型在当前账号类型下不支持

你可能见过类似the 'gpt-5.6-sol' model is not supported when using codex with a ChatGPT account这样的提示。它的含义是:你配置里指定的这个模型,在你当前的账号类型下不可用。这里的关键词是"账号类型",不同登录方式能访问的模型范围不一样,有的模型只在特定类型下开放。

遇到这个报错,先别怀疑配置写错了,大概率是配置里的模型名和你当前账号能用的模型对不上。处理方式有两种:一是把模型名换成你账号确实可用的那一个;二是切到另一套凭证下运行。我在配备用源的时候也遇到过类似性质的报错,原因是备用源的模型标识和它实际提供的模型名不一致,改成供应商文档里写的确切名称就好了。这里有个经验:模型名一定要从供应商那边复制,别自己按习惯拼。

4.4 上下文撑爆:ran out of room in the model's context window

codex ran out of room in the model's context window说的是上下文窗口满了,这和额度耗尽完全是两回事,但撞上的时候容易误判,因为它也是"不让干活了"。上下文满的典型特征是:前几轮都正常,任务做到一半突然开始报这个错,而且报错之后你继续追问,它还是这个提示。

根因是这次会话累积的内容超过了模型能吃下的上限。备用源如果本身窗口比主通道小,这个问题会来得更快,所以切换之后的第一件事往往是检查配置里的上下文参数和备用源的真实能力是否对齐。处理手段有这么几个:开新会话重来,把任务拆小;用它自带的压缩功能把历史精简掉,但如果压缩任务本身也失败,会看到类似error running remote compact task的报错,那就只能开新会话;再就是养成习惯,一个任务做完就退出,别在一个会话里连做三件事。

4.5 登录态和验证相关的麻烦

还有一类报错不指向配置,而指向账号状态。常见的表现是切换之后请求发不出去,或者提示需要重新验证,严重的时候会看到要求完成手机号验证之类的提示。这类问题在主力通道上也可能出现。

我的处理原则是:先确认主通道本身是否正常。如果主通道也在报同类错误,那就不是备用源的问题,而是账号侧的状态需要处理,先按提示把验证流程走完。如果主通道正常、只有备用源异常,再回头查备用源的密钥和地址。这个顺序很重要,我见过不少人一看到报错就去改配置,结果把本来好的主通道也改乱了,最后两边都用不了。

5. 让备用源真能顶班:几个必须调的参数

5.1 上下文窗口和最大输出要对齐真实能力

配置里的上下文相关字段,写小了浪费模型能力,写大了会直接报错。备用源接的是本地模型或者第三方接口,它们各自的实际窗口上限不一样,你不能按主通道的数值抄过去。

我的做法是分两步:先查备用源文档里写的最大上下文是多少,再在这个数值上留出一部分余量,因为系统提示、工具定义、历史消息都要占位置。输出上限同理,设得比模型能力还大会被上游拒绝,设得太小会出现回答被硬截断的情况,表现出来就是"它说到一半没了"。这个参数建议按任务类型调:纯改代码的任务不需要太长的输出,做方案分析的任务才需要放开。

5.2 温度、超时和重试,别用默认值硬扛

备用源的延迟往往和主通道不一样,本地模型尤其明显。默认超时时间对本地模型来说经常偏短,表现出来就是请求发出去,等一会儿直接失败,你还以为是额度问题。我的建议是把超时适当放宽,同时把重试次数压低一点。

这里有个取舍要说清楚:重试次数高,遇到偶发失败能自己恢复;但重试次数高加上额度类错误,会导致同一个请求反复打,把问题放大,codex exceeded retry limit之后的那串状态码就是这么攒出来的。我的配置是超时给足,重试给到两三次,遇到连续失败就让它直接停下报错,我自己判断要不要换通道,而不是让客户端在那儿死磕。

至于温度,写代码的场景不需要发散,调低一点更符合预期。我在备用源上把温度压得比主通道更低,因为本地小模型本来就容易跑偏,再放开随机性就更难控制了。

5.3 让回复说中文:用项目指令而不是找汉化包

顺便说一个很多人关心的问题,搜索里codex 汉化、codex 设置中文这类词一直很热。界面层的汉化包我一般不折腾,升级一次就可能失效,而且来源不明的汉化包本身有风险。让回复用中文有个更省事的做法:在项目根目录放一个指令文件,把你的偏好写进去,比如要求用中文回答、改动前先说明思路、不要一次改太多文件。这样每次会话它都会读到这些约束,效果比汉化界面实在得多。

5.4 我实测下来的切换节奏和成本感受

最后说说实际体感,这部分纯属个人经验。本地备用源的响应延迟比主通道明显高一档,复杂任务上差距更大,所以我只把它用在两类场景:一是主通道额度耗尽但我必须继续推进的紧急情况,主要做局部修改和单文件重构;二是涉及敏感代码、不想发出去的时候。需要全局理解和跨文件重构的任务,我还是愿意等窗口重置,或者切到独立供应商那条路上去。

独立供应商那条路的体感更接近主通道,延迟可以接受,复杂任务的完成度也够用,缺点是要管好密钥和额度。我现在的主备策略是三层:主通道跑重活,独立供应商账号做第一备用,本地模型做最后兜底。三层里任意一层挂掉,都不至于让我干等。

还有个特别实用的小习惯:切换通道之前先提交一次代码。备用源的能力和主通道有差距,同一个任务给出的改动风格会不一样,如果工作区里堆着一堆未提交的修改,切过去之后出了岔子,你会很难分清哪部分是主通道改的、哪部分是备用源改的。用分支或者工作区隔离来做这件事,成本很低,救回来的时间很多。

有一次我因为没提交,在备用源上跑了半小时,回头发现它把一个主通道已经改对的文件又改回去了,而我没法用版本控制回滚,只能靠记忆一点点比。从那次以后,我给自己定了个规矩:换通道等于换人干活,换人之前先存档。这个规矩听着朴素,但据我的经验,它能省掉的麻烦比任何参数调优都多。