Codex 用得越多，遇到的报错越杂。这篇汇总了我踩过的坑和对应的解决办法，按报错现象归类，遇到直接对着查。
一、安装与启动阶段
报错：command not found: codex
npm 全局目录不在 PATH 里。检查安装时的输出里的 bin 路径，把它加进环境变量；Windows 用户也可以直接重开终端再试。
报错：Unsupported Node version
Codex 要求 Node 22 以上：
bash
node -v低于 22 就先升级 Node，nvm 用户直接 nvm install 22 即可。
二、登录阶段
报错：登录后终端一直转圈不出结果
多数是网络代理问题。Codex 登录会拉起浏览器回调本地端口，代理软件拦截回调会卡住。临时把 localhost 加入代理排除列表，或者切换直连重试 codex login。
报错：Unauthorized 或反复要求登录
登录态过期或写入失败。删除登录缓存目录后重新登录：
bash
codex logout
codex login三、执行阶段
报错：任务执行到一半提示沙箱拒绝操作
这是 Codex 的沙箱在工作，说明任务涉及敏感路径或网络请求。两种处理：把相关目录加入工作区，或者用 /approvals 切到更宽松的审批模式。
报错：Rate limit reached
用量到顶了。Plus 账号有每日额度，重负载时段容易触发。错峰使用、拆小任务都能缓解；长期高用量可以考虑升级订阅档位。
四、效果异常类问题
现象：改着改着偏离需求，越改越乱
多半是上下文被污染了。开新会话，用 AGENTS.md 把关键约束写下来再重跑，成功率立刻回升。
现象：报错信息答非所问
把完整报错、复现步骤、相关文件路径一起贴给它，不要只贴最后一行。AI 排错和人类排错一样，信息越全定位越快。
小结
排查 AI 工具问题的思路和排查传统程序一样：先定位是环境问题、配置问题还是用法问题。这份手册会持续更新，过程中用到的工具和文档清单我也整理在 gptupcn.com，遇到新报错可以先去翻翻。