Codex CLI 报 usage limits exceeded 怎么办？三种限速场景逐个击破

上周四我用 Codex CLI 重构一个老项目的测试用例，跑到第 40 多个文件的时候突然卡住了，终端里蹦出来一行：

Error: 429 - {"error":{"message":"Usage limits exceeded","type":"requests","code":"rate_limit_exceeded"}}

说实话一开始我以为是网络问题，重试了几次还是不行。后来花了大半天把 Codex CLI 的三种限速机制摸清楚了，发现不同情况的报错响应体长得不一样，处理方式也完全不同。这里直接把结论和方案整理出来。

直接回答：三种限速分别怎么处理

Codex CLI 的 usage limits exceeded 报错本质上对应三层不同的限速机制：每日 Token 配额耗尽、每分钟请求数（RPM）超限、并发 Session 数上限。每种的响应体里 type 字段不一样，处理方案也不同——RPM 超限等一分钟就好，Token 配额耗尽要么等第二天重置要么换 API 源，并发上限则需要调整 config.toml 里的 session 配置。

为什么 Codex CLI 特别容易触发限速

跟普通的单次 API 调用不同，Codex CLI 在执行任务时会：

1. 把整个项目的上下文（文件树、相关代码片段）打包发送
2. 多轮对话式地逐步执行修改
3. 每次 diff 确认后又发一轮请求

一个"帮我重构这个模块"的指令，背后可能产生 8-15 次 API 调用，每次都带着几千 token 的上下文。我那天跑测试用例生成，40 个文件下来大概消耗了 180k+ token，RPM 也飙到了限制线。

sequenceDiagram
 participant U as 你的终端
 participant C as Codex CLI
 participant A as OpenAI API
 U->>C: codex "重构 auth 模块"
 C->>A: 请求1: 读取项目结构 (~2k tokens)
 A-->>C: 响应1
 C->>A: 请求2: 分析代码 (~8k tokens)
 A-->>C: 响应2
 C->>A: 请求3: 生成修改方案 (~4k tokens)
 A-->>C: 响应3
 C->>A: 请求4: 应用 diff (~3k tokens)
 Note over A: RPM/TPM 累积触发限速
 A-->>C: 429 rate_limit_exceeded
 C-->>U: Error: Usage limits exceeded

第一种：每日 Token 配额耗尽

报错特征

{
 "error": {
 "message": "You exceeded your current usage limit. Please check your plan and billing details.",
 "type": "insufficient_quota",
 "code": "rate_limit_exceeded",
 "param": null
 }
}

关键识别点是 type: "insufficient_quota"。这说明你当天（或当月）的 token 总量用完了。Codex CLI 在终端里显示的是：

⚠ Usage limits exceeded - daily token quota exhausted. Resets at 00:00 UTC.

处理方式

没什么花哨的办法。要么等 UTC 0 点重置（北京时间早上 8 点），要么升级 plan。我之前用的是 Usage Tier 1，每天上限大概 200k token，跑大项目根本不够。

升到 Tier 2 之后上限变成了 2M/天，但如果你团队里好几个人同时在用 Codex CLI，这个额度也撑不了多久。

还有一个办法是在 ~/.codex/config.toml 里配一个 token 预警：

[usage]
daily_token_warning = 150000 # 到 150k 时提醒
daily_token_hard_limit = 190000 # 到 190k 主动停止，留 buffer

这样至少不会跑到一半突然断掉，能在接近上限时收到提示。

第二种：每分钟请求数（RPM）超限

报错特征

{
 "error": {
 "message": "Rate limit reached for codex-mini-latest on requests per min (RPM): Limit 20, Used 20, Requested 1.",
 "type": "requests",
 "code": "rate_limit_exceeded",
 "param": null
 }
}

注意 type: "requests" 和 message 里会明确告诉你 RPM 限制是多少。Codex CLI 终端显示：

⚠ Rate limited (RPM). Retrying in 42s...

处理方式

Codex CLI 本身有内置的退避重试逻辑，但默认配置比较保守。在 config.toml 里可以调：

[rate_limit]
# 触发 RPM 限速后的初始等待时间（秒）
retry_initial_delay = 10
# 最大等待时间
retry_max_delay = 120
# 退避倍数
retry_backoff_multiplier = 2.0
# 主动限速：两次请求之间至少间隔多少 ms
request_interval_ms = 3500

request_interval_ms 这个参数挺有用的。设成 3500ms 意味着 Codex CLI 每分钟最多发 17 个请求，留了点余量不容易撞到 20 RPM 的墙。

我实测设成 3200ms 偶尔还是会触发（可能有网络延迟导致请求堆积），3500ms 基本稳了。代价是整体执行速度慢了大概 15-20%，但至少不会中断。

第三种：并发 Session 数上限

报错特征

这个最坑，因为报错信息和 RPM 超限长得很像：

{
 "error": {
 "message": "Rate limit reached for codex-mini-latest on active sessions: Limit 3, Active 3, Requested 1.",
 "type": "sessions",
 "code": "rate_limit_exceeded",
 "param": null
 }
}

关键区分点是 type: "sessions" 和 message 里的 active sessions。

这种情况通常发生在你开了多个终端窗口同时跑 Codex，或者上一个 session 没正常关闭（Ctrl+C 强退有时候不会立即释放 session）。

处理方式

[session]
# 超时自动释放（秒），默认 300
idle_timeout = 120
# 最大并发 session 数（不能超过你 plan 的上限，但可以设更低来避免误触发）
max_concurrent = 2
# 启动前检查是否有残留 session
cleanup_on_start = true

cleanup_on_start = true 这个设置帮了大忙。之前我经常遇到明明只开了一个终端，但报 session 超限，后来发现是之前 SSH 断连留下的僵尸 session。加了这个配置后 Codex CLI 启动时会先清理掉自己名下的过期 session。

手动查看和释放也行：

codex sessions list
codex sessions kill <session-id>

换一个不共享限速池的 API 源

折腾了半天限速配置，我后来发现一个更根本的问题——如果你白天正常开发也在调 OpenAI 的 API（比如 Cursor 里也配了同一个 key），那 Codex CLI 和 Cursor 的调用量是共享同一个 RPM/TPM 池的。

这种情况下光调 config.toml 治标不治本。我后来的做法是给 Codex CLI 单独配一个 API 源。在 config.toml 里：

[api]
base_url = "https://api.ofox.io/v1"
api_key = "your-key-here"
model = "codex-mini-latest"

OpenRouter 和 ofox.io 这类聚合平台的好处是限速策略独立于你的 OpenAI 官方账号，不会和 Cursor、其他工具抢同一个配额池。ofox.io 是 0% 加价直接对齐官方价格，OpenRouter 收 5.5% 手续费，看你自己取舍。

完整的 config.toml 防限速配置

把上面几种情况的配置合在一起，我目前在用的完整配置长这样：

# ~/.codex/config.toml

[api]
model = "codex-mini-latest"
# 如果不换源就注释掉下面两行
# base_url = "https://api.ofox.io/v1"
# api_key = "sk-xxx"

[rate_limit]
retry_initial_delay = 10
retry_max_delay = 120
retry_backoff_multiplier = 2.0
request_interval_ms = 3500

[session]
idle_timeout = 120
max_concurrent = 2
cleanup_on_start = true

[usage]
daily_token_warning = 150000
daily_token_hard_limit = 190000

快速判断是哪种限速

遇到 429 的时候别慌，看响应体里的 type 字段：

我的最终选择

现在我的工作流是这样的：白天正常开发用 Cursor（走 OpenAI 官方 key），Codex CLI 单独配一个独立的 key 源，两边互不干扰。config.toml 里 request_interval_ms 设 3500，基本不会再撞 RPM 墙了。

唯一还没解决的是 Token 配额的问题——跑大规模重构任务（比如一次性改 100+ 文件）的时候，一天 2M token 有时候还是不够。目前的 workaround 是把大任务拆成几天跑，或者用 --dry-run 先预估一下 token 消耗再决定要不要执行。反正也不是每天都有这种大活。