Codex 常见故障排查：目录、权限、命令与上下文

先确认问题发生在哪一层

排障时按目录、依赖、权限、命令、产品状态的顺序检查，比不断重试更有效。

找不到文件或改错项目

确认当前工作目录和仓库根目录，检查是否进入了同名目录、临时 worktree 或错误分支。让 Codex 先输出当前路径和 git status，不要立刻修改。

命令不存在或版本不对

读取项目的包管理器和版本文件，使用仓库已有命令。不要在没有确认的情况下全局安装替代工具。依赖锁文件存在时，应保持对应的包管理方式。

权限不足

区分文件系统、网络、账号登录和云平台权限。不要用扩大所有权限的方式解决单个命令失败；先确认需要访问的精确目标和原因。

测试在修改前就失败

先验证基线。记录修改前后是否是同一失败，并把与任务无关的既有错误单独说明。不要为了让结果“全绿”顺手改掉不在范围内的模块。

结果偏离需求

检查任务是否缺少范围和验收条件。把大任务拆成“先调查、再方案、后修改”，并要求引用具体文件。长期规则写入 AGENTS.md，一次性要求留在当前任务。

提交问题时准备什么

提供精简的错误信息、发生步骤、环境版本、当前目录、相关命令和预期结果。删除密钥、令牌、完整账号 ID 与客户数据。能够稳定复现的问题，通常比一长串截图更容易解决。