Codex 排障手册

Codex 出问题时，不要急着让它“再试一次”。先判断是任务描述问题、上下文问题、权限问题、环境问题，还是 Codex 的执行策略问题。

常见问题速查

问题	可能原因	先做什么
它理解错项目	没有先只读建图	让它总结目录和关键文件
改动范围太大	任务边界不清	限定文件和禁止重构
测试跑不起来	依赖、环境或命令错误	让它区分环境失败和代码失败
输出不准确	缺少源文件或数据	要求引用具体文件和行
登录失败	账户、网络、授权问题	先检查 CLI/App 登录状态
权限卡住	沙盒或审批限制	说明命令目的，拆成低风险步骤

先判断是哪一类问题

排障前先归类，不要直接让 Codex 继续改。

类型	典型表现	处理方向
上下文问题	它误解目录、读错文件、引用不存在内容	回到 上下文管理
任务问题	它一直问下一步，或者越改越远	重写 任务设计
权限问题	命令被拦截、外部目录不能写、网络失败	检查 沙盒与审批
环境问题	依赖缺失、版本不对、本地命令不存在	运行 codex doctor 或项目诊断命令
交付问题	它说完成，但 diff 或测试不可信	做 交付审查

上下文不准

使用这个提示：

请停止修改。
请重新只读检查项目上下文，并回答：
1. 你刚才基于哪些文件做判断；
2. 哪些文件你还没有读；
3. 你的判断里哪些是不确定的；
4. 下一步修改前需要确认什么。

改动过大

使用这个提示：

当前改动范围过大。请收敛任务：
1. 列出所有已改文件；
2. 标出哪些与目标直接相关；
3. 标出哪些是无关改动；
4. 不要继续修改，先给我一个最小修复方案。

测试失败

使用这个提示：

请分析测试失败原因。
不要马上改代码。
请区分：
1. 是否是环境依赖问题；
2. 是否是本次修改导致；
3. 是否是已有失败；
4. 最小复现路径是什么；
5. 你建议先改哪一个点。

输出不可靠

要求它引用证据：

请重新回答，并为每个判断附上来源：
1. 文件路径；
2. 相关函数或配置名；
3. 你依据的命令输出；
4. 如果只是推测，请明确标注“推测”。

排障原则

• 不要连续尝试超过三轮同类修复。
• 每次失败都要记录失败命令和错误信息。
• 先缩小范围，再修复。
• 如果任务变大，重新写任务说明。
• 不要让 Codex 用破坏性命令“清理现场”。

复位提示

当任务已经混乱时，可以直接让 Codex 停下来复位：

请停止继续修改。
请基于当前状态做一次复位总结：
1. 用户原始目标是什么；
2. 你已经做了什么；
3. 当前工作区有哪些改动；
4. 哪些改动可能无关；
5. 哪些验证通过或失败；
6. 继续前最需要我确认什么。

复位的目的不是责备模型，而是把混乱任务重新拉回可审查状态。