排障手册

本页收集 Codex 使用中的常见问题。欢迎通过 PR 持续补充。

Codex 找不到项目上下文

可能原因：

• 你不在项目根目录。
• 仓库缺少 README、测试命令或项目说明。
• monorepo 没有说明包边界。

处理方式：

• 先让 Codex 只读目录并总结项目结构。
• 添加或更新 AGENTS.md。
• 在任务说明里指定相关目录。

Codex 改动范围太大

处理方式：

• 明确“只修改这些文件”。
• 要求“先输出计划，不要动手”。
• 把任务拆成更小的步骤。
• 在 review 时拒绝无关重构。

测试跑不起来

处理方式：

• 让 Codex 先定位测试命令。
• 检查依赖是否安装。
• 区分环境问题和代码问题。
• 如果是环境问题，让 Codex 记录阻塞，而不是继续乱改。

生成内容不准确

处理方式：

• 要求 Codex 引用它依据的文件。
• 对官方事实要求附链接。
• 让它区分“已确认”和“推测”。
• 让它先读代码再写文档。

登录或权限问题

处理方式：

• 更新 Codex CLI 到最新版本。
• 重新运行登录流程。
• 检查当前账号计划和组织策略。
• 查看官方 Help Center 的 Codex 相关文章。