最后核验：2026-11-02
Codex 出现异常时，先分清看到的是谁的改动、运行在哪个目录、用了哪套环境和权限。这几个边界没对齐，即使重开对话或换模型，也可能重复同一故障。
本文面向 Codex 桌面应用的本地项目、受管 worktree 与本机 CLI。依据官方排障说明整理，未逐项在本站重现实测；下面的“验证”是处理后应检查的结果，不是本站运行记录。远端和云端任务的路径、环境准备方式需另按对应文档核对。
按症状选择检查顺序
| 症状 | 第一处检查 | 接下来检查 |
|---|---|---|
| Review 出现大量不是刚改的文件 | 切换 Last turn，区分本轮与整个 Git 状态 | staged、unstaged 和相对 main 的差异 |
| 主目录能跑，worktree 不能跑 | 当前 worktree 路径及环境准备 | 缺依赖、被忽略的本地文件、环境配置根目录 |
| Approve for me 不见了 | 应用版本、当前对话菜单 | 有效配置、权限配置和组织限制 |
| 终端与应用表现不同 | 各自 CLI 版本 | 打开的项目、profile 与权限 |
| 任务停在同一处 | 是否在等待审批或外部工具 | 本地 Git 是否响应、能否缩成单个步骤 |
Review 混入旧改动：先确认差异范围
官方说明，Review 侧栏可能展示整个仓库的 Git 状态，并不只展示 Codex 刚刚改的内容。先切到 Last turn，再按需要查看 staged、unstaged 或相对 main 的差异。
对照你在启动任务前已有的改动，确认哪些文件属于当前轮次。若你当时没有记录基线，仅凭“现在出现在侧栏里”无法判断修改归属。
处理： 明确只让 Codex 处理当前目标文件，逐个审查它产生的差异。不要先执行 reset、clean 或整体恢复来“清掉杂项”，这些操作可能删除你或其他工具尚未保存到提交里的成果。
验证： 本轮 diff 能对应到原任务；其他已有修改仍在。还无法判断归属的文件保持原样，补查编辑器或 Git 中已有记录。更多分支与工作目录的关系见worktree 实战指南。
worktree 缺依赖：Git checkout 不等于开发环境
主目录里已经安装的依赖、构建缓存与被忽略的本地配置，不一定存在于新 worktree。先核对当前目录，再根据具体错误查环境，不要把“找不到模块”直接判断成代码改坏了。
- 确认失败发生在哪个 worktree。 对照终端目录与对话所选工作目录，避免在主目录装依赖，却在另一个目录重试。
- 检查环境准备。 按仓库已有说明安装依赖，或使用 Codex 的 local environment 配置；共享环境配置应位于打开的项目根下的
.codex，monorepo 尤其要确认层级。 - 判断是否缺本地文件。 如果需要在创建受管 worktree 时带入特定的 ignored 文件，查看官方
.worktreeinclude机制。只列任务确实需要的项目文件，不批量复制凭据。 - 在同一目录重试原来失败的检查。 安装命令成功只说明准备步骤结束，原来的测试或构建恢复才回答了故障是否解决。
.worktreeinclude 有明确边界：它复制匹配的被 Git 忽略的文件，不会把所有未跟踪文件都复制过去；会跳过源符号链接，不覆盖新 checkout 已存在的文件。它面向本地 Codex 受管 worktree，不能把这个行为推广到手工创建或远端 worktree。规则见官方 worktrees 文档。
验证： 同一 worktree 内，缺失文件或依赖已经按项目方式就位，原失败检查恢复。若仍报相同错误，继续沿错误栈检查具体路径，不反复重建整个 worktree。
定时任务留下越来越多 worktree
先查看哪些运行仍需保留，归档不再使用的运行，避免无必要地 pin。归档前检查未提交 diff，确认成果已保存；不要直接批量删除 worktree 目录来释放空间。保留策略与清理方式以当前客户端和官方说明为准。
Approve for me 消失：查有效配置与策略
先更新桌面应用，再检查当前对话的菜单。若仍没有该选项，官方排障建议检查本地有效配置是否设置了 features.guardian_approval = false，以及当前权限配置、审批策略与审查方式。
不要只搜索一个配置文件就下结论。CLI 参数、profile、项目配置和用户配置可能叠加；组织托管策略也可能限制功能，不能由本地设置覆盖。
处理： 找到实际生效的禁用项后，按你有权管理的配置层修正，再核对当前会话。组织策略限制时，由管理员确认可用范围。不要把切换成完全访问当作恢复自动审批的办法。
验证： 当前对话显示预期审批方式；需要审批的操作能按该方式处理。auto_review 只改变审批由谁处理，不改变文件和网络沙箱。配置实例和逐步放开方法见Codex 权限指南。
应用与终端版本不一致
官方给出的版本核对命令是：
codex --version
/Applications/Codex.app/Contents/Resources/codex --version
第一条检查终端找到的 CLI；第二条是官方保留兼容路径下的应用内 CLI。若第二条路径不存在，先在应用界面确认版本和安装位置，不能据此直接判断应用未安装。
处理： 分别按各自安装方式更新，随后确认调用的是预期程序和项目。不要为了“让版本一致”盲目复制应用内部文件覆盖终端程序。
验证： 能说明两端分别是什么版本、打开哪个目录、使用哪套权限；再用同一最小任务比较。版本一致只能排除一个差异来源，不能证明配置和环境也一致。
任务卡住：把等待与执行故障分开
先看是否正在等审批或外部工具返回。如果界面没有明确进展，在普通终端检查当前仓库的基本 Git 状态是否响应；Git 本身也卡住时，优先处理本地仓库或文件系统问题。
本地环境正常后，用新对话重试一个更小的任务，例如只定位失败检查的入口，并提供原任务、失败步骤与最小报错。不要连续重跑整项长任务来判断一个单步故障。
需要反馈问题时，保留客户端版本、操作系统、执行环境（本地、worktree 或远端）、症状、最小复现与必要的脱敏日志。不要直接公开完整会话历史、凭据或含用户数据的原始日志。如何让长任务更容易恢复，见Codex 长任务工作流。
官方来源
- Troubleshooting：Review、worktree、审批选项与版本核对
- Git worktrees：本地文件复制边界和清理
- Local environments：项目环境准备
- Configuration basics：配置加载与覆盖关系
- Auto-review：审批方式与沙箱的关系
核验日期：2026-11-02。本文未实际触发故障或执行模型任务，建议用你原来失败的最小检查验证修复。
