Codex 报错需要按错误类型逐层排查：401 先查认证状态并重新登录，403 重点检查权限设置（组织席位 / SSO），429 查看用量限制，浏览器已完成授权但终端卡住要检查回调链路（可改用 device-auth），出现 command not found 则优先排查安装状态和 PATH 环境变量。
遇到 Codex 报错时，不要一开始就删除配置或直接重装，正确做法是先按报错类型分层定位问题——401 代表认证失败，403 表示权限不足，429 通常是用量超限，浏览器授权成功但终端一直卡住说明回调链路可能中断，而命令找不到大多属于安装环境或 PATH 配置问题。不同错误对应的排查思路完全不同，分清类型才能更快解决。
先锁定错误类型再动手
建议先按照下面三个动作排查，处理效率会明显更高。第一步，把完整报错信息原样复制保存，不要只记“401”或“command not found”这类碎片化内容；第二步，结合报错出现的具体场景往前追溯——是执行codex login时报错，还是在codex generate后运行代码时出现问题，或者是在 VSCode 插件中一直无响应；第三步，再对照下表，先快速判断问题属于哪一层。
| 错误表现 | 所属类型 | 立即该查什么 |
|---|---|---|
| 401 Unauthorized | 认证层 | codex login status输出是否为logged in |
| 403 Forbidden | 授权层 | 当前工作区是否有席位、SSO是否强制启用、管理员是否禁用了你的模型访问 |
| 429 / usage limit | 用量层 | OpenAI账户页面的Usage Dashboard是否已达日限额 |
| 浏览器跳转成功，终端仍显示“Waiting for authorization…” | 回调层 | 是否在WSL/SSH/容器中运行？本地端口8080能否被CLI进程监听到 |
输入codex --version提示command not found | 安装层 | npm list -g @openai/codex是否返回包信息，npm root -g路径是否已加入PATH |
401 和 403 必须分开处理
方法一：401 Unauthorized（登录凭证未通过验证）
执行codex logout→codex login完成一次完整的重新登录；【不要跳过logout】如果直接执行codex login，有可能继续复用已失效的 token，从而导致 401 错误反复出现。
方法二：403 Forbidden（账号已识别，但当前无访问权限）
先检查~/.codex/auth.json中的organization_id，确认它与 OpenAI 平台中显示的组织 ID 完全一致；然后进入 OpenAI 后台，依次打开 Settings → Organization → Seats，确认你的账号状态为 Active，且没有被移出席位；如果组织启用了 SSO 单点登录，还需要联系管理员核实你的邮箱域名是否在允许范围内。
浏览器成功但终端卡在等待
第一步：先确认当前运行环境——如果你是在 WSL、Docker 容器、远程 SSH 或 GitHub Codespaces 中使用 Codex，本地回调 URL 往往无法自动返回到 CLI 进程。
第二步：改用设备码登录，执行：codex login --device-auth；终端会生成一次性设备代码和验证网址；在任意浏览器中打开该网址，输入设备代码并完成授权；【设备代码有效期仅15分钟，且不可重复使用】。
第三步：授权结束后，CLI 一般会自动完成登录；如果终端仍然停留在等待状态，可以手动中断（Ctrl+C），再执行codex login status确认当前登录状态是否正常。
命令根本不存在？从安装层开始挖
① 先执行npm install -g @openai/codex，确认 Codex CLI 已正确完成全局安装；
② 再运行npm list -g @openai/codex，如果输出结果为empty，通常说明全局安装没有成功；
③ 查看npm root -g返回的路径，Windows 用户要检查该目录是否已经加入系统环境变量PATH，Mac/Linux 用户则需要确认 shell 配置文件（如~/.zshrc）中是否正确导出了该路径；
④ 【最关键的一步】关闭当前所有终端窗口，重新打开一个新的终端再测试——旧终端通常不会自动加载最新添加的环境变量。