Codex 速率限制是实际使用 OpenAI Codex 时最容易踩的坑也是最容易被误判的问题。明明 API Key 没问题、代码逻辑也没问题连续跑几个任务后突然报错终端只返回一个 429 或“用量不足”提示。更麻烦的是有些错误根本不是限流而是配置和模型兼容性问题看起来也像限流实际处理方式完全不一样。下面围绕 Codex 速率限制的修复与用量重置来写。适合已经安装好 Codex、正在做单任务或批量任务、或者想搞清楚限流后到底该等还是该改参数的开发者。阅读前不需要把 Codex 的底层实现研究透但对命令行、环境变量和 API 的基本概念要有一定了解。按排查路径展开先认识限流的具体表现再查用量和日志然后按优先级处理错误最后讲清楚用量重置背后的时间窗口和批量任务稳定方案。最关键的一点是不要一报错就怀疑 API Key也不要急着调并发先看错误类型和剩余额度。1. 先搞清楚 Codex 速率限制到底是什么1.1 速率限制在网络请求里意味着什么Codex 不是一个纯本地工具它的核心能力来自远端模型服务。你在本地发起的每一次补全、生成、修改本质上都是向服务端发送一次 HTTP 请求。服务端为了控制资源消耗和维护稳定性会给每个账号、每个 API Key 设置单位时间内的请求次数和 token 消耗上限这就是速率限制。理解这一层很关键。Codex 的“速率限制”不是某个插件的故障而是平台侧的动态保护机制。它的存在很正常任何提供 API 的服务都有类似策略。你不需要绕过它只需要学会怎么在限制范围内工作。还要注意一点Codex 的一个任务并不等于一次请求。一次完整的编码任务可能包含多轮模型调用比如理解需求、生成代码、调用工具、读取文件、再生成下一步操作。所以哪怕你只跑一个任务实际产生的请求数也远高于一次。批量跑几十个任务时请求量会成倍增长限流很容易触发。1.2 Codex 的限流表现429、用量不足和模型报错Codex 被限流时最常见的信号是 HTTP 429。但 429 不是唯一表现有时日志里会显示“usage limit reached”“rate limit exceeded”“insufficient quota”等提示。这些提示对应的处理方向完全不同不能看到“limit”就急着改并发。另一种常见表现是任务中途停下。Codex 在批量任务中的某个子请求被限流后如果本地客户端没有自动重试整个任务就会挂起或标记为失败。你看到的是任务输出不完整实际原因是限流把请求链路切断了。这类问题如果只看结果很容易误判成业务代码问题。还有一类是返回结构化错误体。错误体里通常包含错误类型、状态码、错误码等字段。比如rate_limit_exceeded和insufficient_quota虽然都可能导致请求失败但一个代表请求太频繁一个代表钱或配额不够。排查第一步就是把这些字段读出来而不是凭感觉猜。遇到限流相关报错先把完整日志保存下来。终端被清空后你想找响应头里的重置时间就找不到了。1.3 限流窗口和计费额度不是一回事很多人把“用量重置”理解成“过一段时间所有限制全部恢复”。实际上系统里存在多个独立计数器。第一类是按时间滑动的请求频率窗口。比如约定每分钟最多 60 次请求这一分钟发满了就等下一分钟窗口重新计数。这类限制恢复很快一般几十秒到几分钟。第二类是 token 消耗配额同样有时间窗口但窗口尺度可能更长比如按小时或按天。你可以在短时间内发很多请求但 token 总量一旦超限后续请求同样会被拒。第三类是计费账户级别的月度预算或免费额度。这类额度与限流窗口无关需要等到下一个计费周期才能重置或者手动调整预算才能恢复。把这三种分开后面的排查就会快很多。很多人在“重置”这块卡住就是因为把所有限制都当成同一种机制。2. 在动手修复前先确认你的用量和剩余额度2.1 从哪里查看当前状态我建议把第一次限流当成一次“体检”先不要改任何配置。你需要确认三样东西当前账号的状态、当前模型是否可用、当前请求还有多少余量。Codex 的用量信息一般可以在平台的用量管理页面看到。如果你是个人开发者就关注当前账号下的限额如果属于组织账号还要确认自己使用的是哪个组织下的 API Key因为组织级的限额和个人 Key 的限额是两套体系不能混着看。CLI 日志同样能提供信息。Codex 在发起请求时响应头可能会包含x-ratelimit-limit-requests、x-ratelimit-remaining-requests、x-ratelimit-reset-requests等字段。这些字段分别代表本窗口允许的请求总数、剩余请求数、窗口重置时间和剩余 token 量。看到这些字段后你可以直接判断是否已经接近限制。2.2 日志和命令行里的关键信息限流排查离不开日志。Codex 日志里至少要看四类信息接口路径确认请求发到了预期端点。状态码429、400、401、500 处理方式完全不同。错误类型rate_limit_exceeded、insufficient_quota、model_not_found、invalid_request_error各有各的修法。上游错误说明有些日志会带cause或upstream_status它经常比外层错误描述更接近根因。如果看到upstream_status: http 400基本可以判断请求根本没进入限流阶段而是被服务端拒绝了。这时候去调并发和重试是浪费时间应该优先检查认证信息、端点地址、模型名称和请求结构。这里有一个经验日志里同时出现多个错误时优先处理状态码最大的那个。比如一个请求返回 401另一个返回 429你先解决 401因为认证错误会导致大多数请求根本没有合法身份后续所有限流判断都会失真。2.3 看到“用量不足”不等于流量被限“insufficient_quota” 和 “rate_limit_exceeded” 是两种常见错误前者不是严格意义上的限流而是配额不足。账户余额不足、月度预算触顶、免费额度用完都会触发 quota 相关报错。区别方法很简单去用量页面看当前周期实际消耗。如果已用额度已经接近上限那就是配额问题。如果剩余 token 还很多但请求仍然报 429那才是请求频率问题。很多人在这一步卡了很久因为只盯着“用量不足”这几个字没有去查账户预算。如果是个人开发环境还要注意 API Key 的权限范围。有些 Key 只允许访问特定模型或者只允许只读操作。权限不足时请求也会被拒绝但错误体里可能不会直接写“limit”。3. 遇到限流时按这个顺序排查和修复3.1 第一步区分错误类型和状态码我处理这类问题的顺序是固定的先看状态码再看错误码再看请求参数。这个顺序能过滤掉 80% 的干扰信息。429请求确实超限或配额不足。400请求结构有问题重试没意义。401认证过期或 API Key 错误。500、502、503服务端问题可以稍后重试。如果状态码是 429再看错误体里的具体错误码。rate_limit_exceeded表示需要调整频率insufficient_quota表示需要检查配额。两者处理路径不同不要混在一起改。一个容易忽略的细节429 错误体里可能包含retry-after或响应头里的x-ratelimit-reset-*。这些字段会直接告诉你需要等多久比你自己猜更准确。如果响应头里已经给了重置时间就不要反复手工重试等窗口过完再跑。3.2 第二步检查认证、端点和模型参数在确认是限流之前先排除掉“假限流”。Codex 可能被配置成使用自定义 OpenAI 兼容端点如果端点对应的模型不支持某些字段就会返回 400。典型示例日志里出现类似“reasoning_content 字段在 thinking mode 下必须传回 API”的 cause 信息或者模型名称在你的账号下不可用。这类错误不影响限流但表现很像接口不可用。如果你只盯着 429 的处理方式会一直修不好。检查清单API Key 是否有效授权范围是否覆盖当前模型。端点地址是否准确有没有多余的斜杠或空格。模型名称是否在当前账号的可用模型列表内。自定义端点返回的错误体里有没有cause字段有就优先看cause。这些检查看着基础但很多“限流修复失败”的案例最后都落在这几点上。尤其是更换过模型或端点之后旧的配置缓存可能还在生效。3.3 第三步检查请求频率和并发设置如果确认认证和模型都没问题再考虑请求频率。Codex 的批处理任务通常有并发能力或者你可能在配置里手动调高了并发。并发过高时RPM 限制很容易被触发。建议先把并发降到最低跑一次单任务。单任务能稳定跑通说明模型和认证正常问题出在频率控制。然后逐步增加并发找到当前账号能承受的上限。这里不要一上来就开最大并发。先跑 1再跑 3再跑 5。每档都要看日志里是否出现 429。找到临界点后把并发保持在临界值的 60% 左右留出安全余量不要顶满。如果你同时开着多个终端窗口每个窗口都在跑 Codex也要算进总并发里。即使单个窗口并发不高多窗口叠加后也可能触发限流。3.4 第四步处理上下文长度和超时有些时候请求失败不是 429而是上下文长度超限。Codex 会把编辑器内容、目录树、工具结果都算进上下文长期任务很容易把窗口塞满。日志里如果出现“context window”相关提示说明当前会话已经不能继续。处理方式是把任务拆小。一个超长任务拆成几步每一步是独立的会话用完上下文就开新会话。同时设置合理的超时时间超时后记录日志并退出而不是无限等待。如果在批量场景中频繁出现上下文超限建议减少 Codex 可以读取的文件范围。不要让它扫描整个项目只给它当前任务需要的目录这样上下文消耗会明显降低请求体积也会变小间接减少被限流的概率。4. 用量重置的机制和误区4.1 重置是时间窗口不是立即生效很多人误以为用量重置是“过几分钟全部恢复”。实际上RPM 和 TPM 是滑动窗口机制。你这一分钟发满 60 次请求服务端会在窗口滑动后重新计数而不是立刻把计数清零。响应头里的x-ratelimit-reset-requests会给出复位时间。看到这个字段后最稳妥的做法是等它走完再继续而不是频繁重试。频繁重试会让日志更乱还可能把多个请求堆在窗口临界点触发新的限流。窗口重置只代表请求次数恢复不代表 token 配额立即恢复。如果 token 已经消耗到较高水平重置请求次数后依然可能因为 TPM 超限而失败。所以不要看到“重置”就认定所有限制都解除了。实际任务里RPM 和 TPM 往往不是同时重置的。4.2 重置后为什么还会遇到限流一个常见场景等待 1 分钟后重新发起批量任务跑不到一半又遇到 429。原因通常是任务消耗的 token 速率远高于窗口允许值。请求次数窗口恢复了但 token 消耗窗口还处于高负荷状态。这时候要做的不是继续等而是降低单次任务的体量。你可以减少每个任务里包含的文件数缩短上下文或者减少工具调用次数。限制实际消耗才能让 token 窗口有余量。另外如果平台最近调整过限流策略重置窗口也可能变化。不要把前几天的参数当成永久参数每次更新后最好重新跑一次小样本测试确认当前限制水平。这一条在团队协作里更重要因为限额可能不止受你一个人影响。4.3 不要在“绕过”上花时间在“退避”上花时间每次提到限流总会有人想通过换 API Key、动态换端点、伪造请求头等方式绕过去。这类做法不但违反服务条款而且会让日志和计费变得不可追查。一旦任务出问题你不知道是哪个 Key、哪个端点、哪个请求导致的结果异常排查成本反而更高。更合理的做法是设计退避逻辑请求失败时从响应头读取retry-after或重置时间等待对应时长后重试。重试次数设上限超过上限就进入失败队列等待人工处理。这样即使限流也不会阻塞整个任务链路。记住限流是平台保护机制。合理的做法是排队等待而不是绕过保护。5. 批量任务下如何保持稳定5.1 为长时间任务设计退避重试一个人偶尔手工重试没问题批量任务不行。批量任务里只要有一个请求被限流后续任务可能连锁失败。所以我一般在任务入口加一层简单的重试封装。伪代码示例如下import time def run_with_retry(task, max_retries3): for attempt in range(max_retries): try: result task.run() return result except RateLimitError as err: wait parse_retry_after(err) time.sleep(wait) raise RuntimeError(task failed after retries)需要注意三点retry-after可能是秒数也可能是具体时间戳解析时两种都要兼容。重试时要能够恢复任务状态不要把已经生成的部分结果丢掉。重试不能无限循环必须设置上限否则一个坏任务会拖住整个队列。如果你的任务框架支持队列就把失败任务重新放回队尾而不是立即重试。这样可以让其他正常任务先跑降低整体请求压力。5.2 日志和输出命名让问题可回溯批量任务最容易出现的问题是结果混乱。跑了几百个文件哪些成功、哪些失败、哪些部分成功如果只看终端输出很难统计清楚。建议建立一个简单的输出目录规则把成功、失败、跳过分开保存。例如output/ 20250611_1600_task_001/ done/ failed/ logs/每个任务开始时写一条状态日志结束时再写一条。这样即使任务中途被限流打断你也能知道它停在哪一步而不是重新猜。输出目录带上时间戳和任务 ID后续要重跑时也能快速判断上次执行到哪了避免重复消耗额度。5.3 低配额环境下的参数取舍如果账号配额有限任务又多必须做取舍。我的优先级是先跑核心任务次要任务排队。减少上下文体积不让 Codex 读取无关目录。限制工具调用只允许必要的文件操作。分批处理不要一次提交全部文件。降低并发和单次请求的 token 消耗。这些调整不会让单次任务更快但能让整体执行成功率更高。快而频繁中断不如慢而稳定。尤其是跑长任务时宁可每批少跑几个文件也不要因为急于完成把所有请求堆在一轮里。6. 一些常见错误和处理经验6.1 自定义模型端点返回 400字段不兼容我见过很多“伪限流”案例日志显示upstream_status: http 400看起来像服务不可用实际是请求参数和模型能力不匹配。某个模型要求reasoning_content在 thinking mode 下必须原样传回或者根本不支持该字段于是上游直接返回 400。这类错误和限流无关重试没有意义。正确做法是先读错误体里的cause字段确认是哪个参数不被支持然后调整配置。如果使用默认 Codex 端点这类问题很少见如果使用自定义 OpenAI 兼容端点就要重点关注模型兼容性。遇到 400 时不要反复重试重试也不会成功只会浪费请求次数。6.2 上下文窗口满的提示日志里出现“ran out of room in the models context window”时任务会被迫中断。这不是速率限制但很多人在排查限流时一起遇到。解决方式是开启新会话或把任务拆小。Codex 在运行时会“看到”很多东西包括当前目录结构、打开的文件内容、工具调用结果等。如果你让它在整个项目目录下自由探索上下文会很快被塞满。建议在任务配置里限制它的工作目录只暴露当前任务相关的文件。这样既减少上下文占用也能降低每次请求的 token 消耗间接降低限流概率。不要指望靠加大上下文窗口解决所有问题窗口再大也有上限。6.3 连接中断和重试策略网络抖动或服务端过载时可能返回连接超时、502、503。这类错误和限流不同可以按一定间隔重试但最好分类处理。429按retry-after等待。500、502、503等 3 到 5 秒再重试。连接失败先检查本地网络和端点可达性。不要把三种情况统一用一套逻辑。统一逻辑要么等待时间过长浪费效率要么重试过快加重服务端压力反而更容易触发限流。更合理的做法是把重试等待时间做成可配置项不同错误类型使用不同策略。6.4 多次修复后仍然报错怎么办如果按上面流程走完问题还在就要把排查信息完整收集起来。我一般会保存以下内容复现步骤包括触发任务的小样本。当前模型名和端点配置。最近一次成功运行的配置。完整错误响应体和响应头。这些信息足够拿去反馈。很多时候排查到最后发现只是环境变量没设置或者某个版本更新后默认并发数变了。日志完整问题就更容易定位。不要只保留一行红字完整的响应头里往往藏着真正的重置时间和失败原因。我个人建议把速率限制当成 Codex 工程化的一部分来管理而不是遇到报错才处理。安装完 Codex 后先花十分钟跑一次小样本测试记录单任务、批量任务、不同并发下的错误率和耗时。有了基线数据后续任何变化都能快速定位。Codex 的用量重置不是玄学它是一套可以预测的窗口机制。学会读日志和响应头之后你就能在限流发生前主动调整任务节奏而不是每次都被动等窗口恢复。