文档中心
Codex CLI OpenAI 接入 FAQ:高频问题与修复步骤
汇总 Codex CLI 在 OpenAI 接入过程中最常见的 401、429、超时、网络异常等报错,并按问题给出可直接执行的排查顺序和修复步骤。
这篇 FAQ 只保留“高频且可直接执行”的问题。
1. 401 Unauthorized
排查顺序:
- 重新设置
OPENAI_API_KEY - 在同一终端执行
codex --help - 执行最小请求:
codex run "hello"
可以先确认变量是否为空,但不要打印完整密钥:
test -n "${OPENAI_API_KEY:-}" && echo "OPENAI_API_KEY 已设置" || echo "OPENAI_API_KEY 未设置"
如果变量存在仍然返回 401,再检查 Key 是否已撤销、是否属于当前接口以及账户是否有对应模型权限。
2. 429 Too Many Requests
处理顺序:
- 把并发降到 1
- 缩短单次请求内容
- 把批量任务改为分批执行
如果低并发仍然 429,记录发生时间和请求规模,再查看服务商的额度、限流和账单页面。不要通过无限重试放大请求量。
3. 超时或连接中断
处理顺序:
- 连续做 10 次最小请求测试
- 记录失败比例和失败时间段
- 再决定是网络排查还是链路切换
建议把测试结果记下来:
for i in $(seq 1 5); do
date -Is
codex run "只回复 OK" || true
done
4. 新终端失效
这是环境变量作用域问题。建议把变量写入 shell 配置,并在新终端加载。
不要把密钥直接写入公开仓库中的 shell 脚本。多人协作时,优先使用服务器环境变量或密钥管理工具。
5. 一键复测清单
codex --version
codex --help
codex run "say hello in chinese"
三步都通过后,再执行复杂任务。
6. 最小化复现信息
向服务商反馈问题时,提供 CLI 版本、操作系统、错误码、发生时间、是否设置 Base URL 和最小请求结果即可。请删除 API Key、Authorization 请求头、项目源码和用户数据。
常见问题
配置了 OPENAI_API_KEY 但还是 401,怎么排查?
优先检查 Key 是否完整复制、是否在当前终端会话生效。先在同一窗口重新 export/set,再执行最小请求复测。
为什么会出现 429 Too Many Requests?
通常是请求频率过高或短时间并发过大。先降并发、降低单次任务复杂度,再逐步恢复。
请求经常超时,是 CLI 问题吗?
多数情况是链路波动。先做最小请求连续测试,确认是偶发还是稳定复现,再定位网络或网关问题。
切换到新终端后命令又失败了,为什么?
环境变量通常只对当前会话生效。新终端需要重新加载 shell 配置或再次设置环境变量。