文档中心

Codex CLI OpenAI 接入 FAQ：高频问题与修复步骤

发布时间：2026-02-19 · 更新于：2026-02-19

汇总 Codex CLI 在 OpenAI 接入中的高频报错与排查路径，按问题到修复步骤直接执行。

这篇 FAQ 只保留“高频且可直接执行”的问题。

1. 401 Unauthorized

排查顺序：

  1. 重新设置 OPENAI_API_KEY
  2. 在同一终端执行 codex --help
  3. 执行最小请求：codex run "hello"

2. 429 Too Many Requests

处理顺序：

  1. 把并发降到 1
  2. 缩短单次请求内容
  3. 把批量任务改为分批执行

3. 超时或连接中断

处理顺序：

  1. 连续做 10 次最小请求测试
  2. 记录失败比例和失败时间段
  3. 再决定是网络排查还是链路切换

4. 新终端失效

这是环境变量作用域问题。建议把变量写入 shell 配置，并在新终端加载。

5. 一键复测清单

codex --version
codex --help
codex run "say hello in chinese"

三步都通过后，再执行复杂任务。

常见问题

配置了 OPENAI_API_KEY 但还是 401，怎么排查？

优先检查 Key 是否完整复制、是否在当前终端会话生效。先在同一窗口重新 export/set，再执行最小请求复测。

为什么会出现 429 Too Many Requests？

通常是请求频率过高或短时间并发过大。先降并发、降低单次任务复杂度，再逐步恢复。

请求经常超时，是 CLI 问题吗？

多数情况是链路波动。先做最小请求连续测试，确认是偶发还是稳定复现，再定位网络或网关问题。

切换到新终端后命令又失败了，为什么？

环境变量通常只对当前会话生效。新终端需要重新加载 shell 配置或再次设置环境变量。

相关阅读