Codex CLI 常见报错速查

排错总原则

收到报错时，先用这三步快速缩小范围，再看后面的具体条目：

1. 看错误类型：401/403 是认证问题；429 是限流；端口冲突或 os error 是本地环境问题；Reconnecting/stream disconnected 是网络问题。
2. 看是否能连上 OpenAI：curl -I https://api.openai.com/v1/models 返回 401 说明网络通，返回超时或连接拒绝说明是代理/网络问题（见 Reconnecting 排查）。
3. 看日志：会话内执行 /feedback 可捕获请求 ID、错误日志与连接快照，便于进一步定位。

报错速查表

认证类问题（401 / 登录失败 / Headless）

401 Unauthorized — Token 失效

401 Unauthorized 意味着你的登录令牌已过期，或 API Key 无效。处理步骤：

1. 退出并重新登录（ChatGPT 账号方式）：
   终端复制

   $ codex logout
   $ codex login

2. 如果使用 API Key，确认 Key 本身有效，且账号已开通 CLI 访问权限。
3. 确认没有在环境变量里同时设置了过期的 OPENAI_API_KEY：env | grep OPENAI。

Headless / 远程服务器登录失败

Codex 在没有浏览器的环境（SSH 服务器、CI、Docker 等）下会自动切换为设备码（Device Code）认证。如果你所在工作区的管理员禁用了 Device Code 认证，即便你的账号本身有权限，登录也会直接失败。

在管理员开启之前，有两种临时绕过方法：

1. 复制 auth.json：在一台有浏览器的机器上完成 OAuth 登录，把 ~/.codex/auth.json 复制到目标服务器的同一路径。
2. 改用 API Key：codex login --with-api-key，不依赖浏览器流程。

登录卡在"Sign in with ChatGPT"界面

OAuth 流程依赖浏览器把回调发到 localhost。如果回调被防火墙或网络策略拦截，页面会一直停在登录界面。

• 确认 localhost（127.0.0.1）的回调端口未被防火墙阻断。
• 在受限环境中直接改用 codex login --with-api-key 更可靠。

限流 429

当你的请求频率或总量超过当前订阅计划的上限时，Codex CLI 会返回 429 Too Many Requests。CLI 界面会同时显示配额重置的时间：

端口占用 — Address in use (os error 98 / 端口 1455）

Codex 登录流程会在本地监听 1455 端口（用于 OAuth 回调）。若该端口已被其他程序占用（最常见的是 SSH 端口转发隧道），登录会失败并报 Address in use (os error 98)。

1. 找出并关闭占用 1455 端口的进程：
   macOS / Linux复制

   # 查看 1455 端口被哪个进程占用
   $ lsof -i :1455
   # 或用 ss（Linux）
   $ ss -tlnp | grep 1455

2. 如果是 SSH 隧道占用，关闭该 SSH 连接或修改隧道转发的端口号。
3. 释放端口后，重新执行 codex login。

配置与沙箱问题

model 字段无效

如果 ~/.codex/config.toml 中的 model 行填写了一个不存在的模型名，Codex 会报配置错误无法启动。最简单的修复方式是直接删除该行，让 CLI 回退到内置默认模型：

# 把下面这行删掉（或在前面加 #）
# model = "某个不存在的模型名"

配置文件损坏

若 TOML 文件格式有误（如手动编辑时引入了语法错误），Codex 会拒绝启动。最快的修复方式是把损坏的文件重命名备份，让 Codex 以默认配置重新生成：

$ mv ~/.codex/config.toml ~/.codex/config.toml.bak
$ codex

沙箱拦截命令

Codex 的沙箱模式（sandbox）和审批模式（approvals）会限制 Codex 可以执行的命令类型。如果某个命令被意外拦截，检查你在 config.toml 或启动参数里配置的沙箱/审批级别，详见 命令与斜杠指令。

WSL 迁移冲突

在 Windows + WSL 双环境下，若 WSL 里的 Codex 与 Windows 里的 Codex 使用了同一个 CODEX_HOME（通常是 ~/.codex），内部数据库迁移记录会产生冲突，出现 migration N was previously applied but has been modified 错误。解决方法是为 WSL 单独设置一个路径：

export CODEX_HOME="$HOME/.codex-wsl"

查看日志与提交 /feedback

Codex 会在本地写入诊断日志（截至 2026）。遇到难以复现的问题时，最直接的方式是在 Codex 会话内执行内置命令：

› /feedback

/feedback 会自动捕获以下信息并打包：

• 当前会话的请求 ID（用于 OpenAI 侧溯源）
• 最近的错误日志片段
• 连接状态快照

常见问题