Codex CLI 提示 usage limits exceeded,第二天仍未恢复怎么办?最小排查顺序
11 月 10 日晚上 22:17,我跑一个多文件重构任务时遇到 usage limits exceeded。睡了一觉起来,限制仍然没有恢复。
别急着删除 ~/.codex,看到 429 也不要连续重试。按照“认证方式 → 错误类型 → 额度窗口 → 项目与组织归属 → 局部重新登录”的顺序排查,通常 10~20 分钟就能判断是账户周期额度、短时速率限制,还是 API 项目配额出了问题。
Codex CLI 可能使用 ChatGPT 账号登录,也可能读取 OPENAI_API_KEY。两套额度相互独立,所以“等到第二天”不是通用解法。
先按报错对号入座
根据 2026 年 11 月 11 日核对的 RFC 6585 和 OpenAI API 错误说明,HTTP 429 表示请求因限制而暂时无法继续,但不等于账户一定没有余额。
| 你看到的内容 | 优先判断 | 该怎么处理 |
|---|---|---|
You've hit your usage limit | ChatGPT 套餐或滚动窗口额度 | 确认登录账号和重置时间 |
rate_limit_exceeded | RPM、TPM 或并发过高 | 降低并发,按响应头退避 |
insufficient_quota | API 余额、预算或配额不足 | 检查项目账单与预算,单纯等待通常没用 |
| 只有笼统的 429 | 信息不足 | 保留响应正文和响应头 |
| 昨天能用,切换账号后失效 | 登录状态或组织归属异常 | 核对账号、Project 和 Org |
最短排查路径如下:
flowchart TD
A[Codex CLI 报 usage limits exceeded] --> B{设置了 OPENAI_API_KEY?}
B -- 否 --> C[检查 ChatGPT 登录账号与重置窗口]
B -- 是 --> D{错误类型是什么?}
D -- rate_limit_exceeded --> E[降低并发和上下文并退避]
D -- insufficient_quota --> F[检查余额 项目预算 组织归属]
D -- 只有 429 --> G[保留响应头与正文继续判断]
C --> H[仍异常才局部重新登录]
E --> H
F --> H
G --> H
为什么等到第二天也没恢复
问题就出在“第二天”这三个字。
Codex 的使用限制可能采用滚动时间窗口,并不一定在每天零点清空。API 项目预算也可能按账期控制。短时速率限制等几秒或几分钟往往有用,但 insufficient_quota 属于额度、预算或项目配置问题。连续重试很久,它仍然可能返回 429。
我当时看到的是:
You've hit your usage limit. Please try again later.
另一次 API Key 异常则是:
Error code: 429 - You exceeded your current quota, please check your plan and billing details.
两条报错看起来相似,处理方向却完全不同。
不同版本的 Codex CLI 可能会附带重置时间、升级提示或错误详情。具体措辞应以当前版本的终端输出为准,不要直接套用其他人的截图。
方案一:先确认 Codex CLI 到底在用谁的额度
不要急着执行:
rm -rf ~/.codex
这是破坏性很强的处理方式。登录状态、历史配置和自定义参数可能一起消失,问题还未必能够解决。
先检查版本和安装来源:
codex --version
command -v codex
npm list -g @openai/codex --depth=0
npm 渠道的包名是 @openai/codex。版本变化较快,不必在排障文档里写死“最新版”。可以通过下面的命令查询当前发布版本:
npm view @openai/codex version
接着只检查环境变量是否存在,不要打印 Key 的内容:
printf 'KEY: %s\n' "${OPENAI_API_KEY:+已设置}"
printf 'ORG: %s\n' "${OPENAI_ORG_ID:+已设置}"
printf 'PROJECT: %s\n' "${OPENAI_PROJECT_ID:+已设置}"
printf 'BASE_URL: %s\n' "${OPENAI_BASE_URL:+已设置}"
如果 KEY 显示“已设置”,就不要默认 Codex CLI 正在消耗 ChatGPT 套餐额度。环境变量可能来自:
~/.zshrc~/.bashrc~/.profile- 终端启动脚本
direnv- IDE 配置
- CI/CD 配置
还要留意 OPENAI_BASE_URL。如果它被设置,实际请求可能发往代理或第三方兼容服务,而不是 OpenAI 官方 API。此时应检查对应服务的配额和日志。
我就踩过这个坑:网页上登录的是个人账号,Shell 里却残留着旧项目的 Key,结果查了半天错误的账单。
方案二:先区分网络故障、速率限制和额度不足
使用 API Key 时,可以通过模型列表接口进行低成本连通性测试,并保留响应头和响应正文:
curl --connect-timeout 10 --max-time 30 \
-sS \
-D /tmp/openai.headers \
-o /tmp/openai.json \
-H "Authorization: Bearer $OPENAI_API_KEY" \
https://api.openai.com/v1/models
printf 'curl exit code: %s\n' "$?"
https://api.openai.com/v1/models 是 OpenAI API 的模型列表端点,不是供浏览器直接打开的普通网页。它通常需要 API 认证。
如果核查工具访问这个地址时出现超时或 DNS 失败,并不能据此认定 URL 写错了。应先区分以下情况:
- 返回
200:网络和认证基本正常; - 返回
401:端点可达,但 Key 无效、缺失或未被接受; - 返回
403:端点可达,但可能存在权限、区域或策略限制; - 返回
429:端点可达,继续查看错误类型和响应头; curl退出码为6:DNS 解析失败;curl退出码为7:无法连接目标主机;curl退出码为28:连接或请求超时。
DNS 失败、连接失败或超时属于网络可达性问题,不应直接归类为额度不足。需要检查本机 DNS、代理、防火墙、出口网络和区域可用性。
查看响应状态、请求 ID 和重试提示:
grep -iE 'HTTP/|retry-after|x-request-id|x-ratelimit' \
/tmp/openai.headers
查看错误正文时要注意脱敏:
cat /tmp/openai.json
模型列表接口返回成功,只能证明端点、Key 和基础权限大致正常。它不能证明生成请求仍有足够预算,也不能证明具体模型没有单独的速率限制。
如果配置了自定义 Base URL,应测试实际使用的端点,而不是固定测试 OpenAI 官方地址。例如:
BASE_URL="${OPENAI_BASE_URL%/}"
curl --connect-timeout 10 --max-time 30 \
-sS \
-D /tmp/provider.headers \
-o /tmp/provider.json \
-H "Authorization: Bearer $OPENAI_API_KEY" \
"$BASE_URL/models"
当 $BASE_URL 指向 OpenRouter、Together AI 或 ofox.io 这类聚合网关/中转方案时,还要核对其模型列表路径、认证头格式和模型名称映射,不能默认都与 https://api.openai.com/v1 完全一致。
只有确认 OPENAI_BASE_URL 已设置且格式正确时,才执行这段命令。
方案三:根据 429 的具体类型处理
rate_limit_exceeded
如果响应正文明确包含 rate_limit_exceeded,优先减少:
- 并行任务数量;
- 单次输入上下文;
- 多文件同时分析范围;
- 短时间内的重复请求;
- 自动重试频率。
然后使用指数退避:
等待时间 = min(等待上限, 基础时间 × 2^重试次数) + 随机抖动
服务端返回 Retry-After 时,应优先按它给出的时间等待。该响应头可能是等待秒数,也可能是具体重试时间,而且不是每次 429 都会提供。
不要无上限重试。除了浪费时间,失败请求在某些限流策略中也可能计入请求速率。
insufficient_quota
如果响应正文明确包含 insufficient_quota,直接检查:
- API 账户是否还有可用额度;
- 当前 Project 是否触发预算上限;
- Key 是否属于预期的 Project;
OPENAI_PROJECT_ID是否指向正确项目;OPENAI_ORG_ID是否指向正确组织;- 账单状态或付款方式是否异常。
这类问题通常不是等几分钟就能解决的。连续重试只会增加无效日志,甚至让真正的错误信息更难查找。
只有笼统的 429
如果终端只显示 429,没有错误类型:
- 保留完整响应正文;
- 保留响应头;
- 记录
x-request-id; - 记录请求时间和时区;
- 记录 Codex CLI 版本;
- 确认认证方式;
- 用一个最短任务复现。
对比 OpenAI 直连与 OpenRouter、Together AI 或 ofox.io 等聚合网关/中转路径时,应分别记录 BASE_URL、HTTP 状态码、x-request-id 和错误正文;不同路径返回的 429 字段不一定相同。
不要只截取“429”这一行。没有正文、响应头和认证上下文,很难区分速率限制、套餐窗口和项目额度问题。
方案四:暂时切换计费路径,但不要掩盖根因
如果确认某个 API 项目的预算已经耗尽,而任务又不能停,可以临时切换到另一个已授权的 API 路径。
OpenRouter、Together AI 和 ofox.io 等服务可以作为聚合网关/中转方案之一进行比较,但在配置前必须确认当前 Codex CLI 版本是否支持自定义 Provider 或 Base URL。不要直接照抄旧版本教程。
这类平台可能提供按模型、用户或 API Key 查看请求量、Token、费用和失败记录的后台,因此有助于定位“哪个 Key 消耗了预算”。但它们不能修复 ChatGPT 登录状态,也不能解除 OpenAI 官方账户的限额。
配置前先备份:
cp -a ~/.codex ~/.codex.backup-$(date +%Y%m%d-%H%M%S)
然后通过当前版本的帮助信息确认支持项:
codex --help | grep -iE \
'login|provider|base|config'
自定义 Provider 的字段和配置方式可能随版本变化,应以本机 codex --help、当前配置文档和对应版本的 Release 信息为准。
如果 Codex CLI 当前版本不支持所需接口,可以临时在其他兼容客户端中验证 API,但不要为了赶进度直接破坏原配置。
任何第三方 API 服务都应被视为独立的认证、数据处理和计费路径。切换前还应确认:
- 是否允许发送当前代码或数据;
- 数据保留和隐私政策是否符合要求;
- 模型名称和接口参数是否兼容;
- 费用、限流和失败重试规则是否清楚;
- 是否需要单独设置 Base URL 和 API Key。
最小破坏式重新登录
前面的身份、网络和额度都核对完,仍然存在问题,再处理本地登录状态。
建议顺序如下:
- 记录
codex --version和安装路径; - 备份
~/.codex; - 记录当前环境变量是否存在;
- 暂时移除当前终端中的相关环境变量;
- 根据本机
codex --help执行退出和登录流程; - 使用一个短任务验证;
- 确认恢复后,再逐项加回原配置。
临时清理当前 Shell 环境可以这样做:
unset OPENAI_API_KEY
unset OPENAI_ORG_ID
unset OPENAI_PROJECT_ID
unset OPENAI_BASE_URL
这只影响当前 Shell,不会修改启动脚本。新开终端后变量再次出现,说明它们仍然写在 Shell 配置、终端配置或目录环境文件中,需要继续定位来源。
可以使用下面的命令搜索常见配置文件,但不要把搜索结果直接粘贴到公开渠道,因为其中可能包含密钥:
grep -nE \
'OPENAI_(API_KEY|ORG_ID|PROJECT_ID|BASE_URL)' \
~/.zshrc ~/.bashrc ~/.bash_profile ~/.profile 2>/dev/null
常见问题 FAQ
Codex CLI 提示 usage limits exceeded,究竟等多久会恢复?
没有统一时长。
如果终端给出重置时间,或者响应头包含 Retry-After,就按提示处理。没有提示时,应核对登录账号、用量页面、项目预算和账单状态。滚动窗口不一定在零点恢复。
已经订阅 ChatGPT,为什么 Codex CLI 还是提示限额?
ChatGPT 订阅额度和 API 计费通常是两套体系。
还要确认:
- Codex CLI 登录的是不是预期账号;
- Shell 中是否存在
OPENAI_API_KEY; - 是否设置了
OPENAI_BASE_URL; - API Key 属于哪个 Project 和 Org。
拥有 ChatGPT 订阅,不代表 API Key 自动获得可用余额,也不代表所有 Codex 任务都可以无限使用。
Codex CLI 报 429,是不是账户没余额了?
不一定。
rate_limit_exceeded 通常表示短时请求速率、Token 速率或并发限制;看到 insufficient_quota,才应优先检查余额、预算和项目归属。如果只有笼统的 429,需要结合响应正文、响应头和认证方式判断。
https://api.openai.com/v1/models 超时,说明地址写错了吗?
不一定。这个端点地址本身是正确的 OpenAI API 路径,但它不是普通网页,并且依赖网络可达性和 API 认证。
如果出现 DNS 失败或连接超时,应先检查代理、DNS、防火墙、出口网络和区域可用性。能够收到 401、403 或 429,反而说明域名和端点已经可以连接,下一步再处理认证、权限或额度问题。
删除 ~/.codex 能解决 usage limits exceeded 吗?
本地认证缓存损坏时可能有效,但代价较大。
账户额度、API 预算、网络不可达和组织归属异常,不会因为删除目录而自动恢复。稳妥做法是先备份,再进行局部退出和重新登录。
为什么缩短上下文能减少触发限制?
大仓库、长会话、多文件分析和并行任务通常会消耗更多 Token,更容易触发 TPM 或套餐窗口上限。
但不存在统一的“上下文缩短一半,消耗就降低一半”的规则。实际消耗取决于任务内容、缓存情况、工具调用和服务端计数方式。
我的最终排查顺序
现在我固定按下面的顺序检查:
- 查看
OPENAI_API_KEY和OPENAI_BASE_URL是否存在; - 确认 Codex CLI 实际使用的账号或 API 路径;
- 读取完整错误类型,而不是只看 429;
- 区分 DNS、连接超时和服务端限流;
- 查看重置时间、
Retry-After和x-request-id; - 核对 Project、Org、余额和预算;
- 备份后再做局部重新登录。
不要一报错就清空配置,也不要机械地等到第二天。前者容易破坏排障现场,后者对 insufficient_quota、错误项目归属和网络不可达都没有作用。
先弄清楚 Codex CLI 正在使用哪种认证方式、请求发往哪个端点、消耗哪套额度,后面的排查会省事很多。
383



被折叠的 条评论
为什么被折叠?



