排障手册

会排障，才算真的会用 Codex。

半桶水式学习里，失败不是“AI 不行”的证据，而是一次把边界、材料、任务卡和验证方式补清楚的机会。本页按常见症状整理处理路径。

排障先做三件事

1. 保留现场：不要急着清空对话或删除文件，先保存报错、截图、命令输出。
2. 分层判断：是项目上下文问题、权限问题、环境问题，还是任务描述问题？
3. 缩小范围：让 Codex 先只读分析，不要边猜边大改。

Codex 找不到项目上下文

可能原因：

• 你不在项目根目录。
• 仓库缺少 README、测试命令或项目说明。
• monorepo 没有说明包边界。
• 新对话没有继承你上一轮口头说明。

处理方式：

• 先让 Codex 只读目录并总结项目结构。
• 添加或更新 AGENTS.md。
• 在任务说明里指定相关目录。
• 把“项目是什么、怎么跑、哪些不能动”写成固定任务卡。

Codex 改动范围太大

处理方式：

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

可以这样说：

这次改动范围太大。请先停止继续修改，只总结你已经改了哪些文件、哪些改动和原目标直接相关、哪些可能需要撤回。不要继续编辑文件。

测试跑不起来

先区分两类问题：

类型	表现	处理方式
环境问题	依赖没装、命令不存在、端口冲突	先修环境或记录阻塞，不要乱改业务代码
代码问题	测试能跑但有失败断言	让 Codex 定位失败用例和相关代码

处理方式：

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

生成内容不准确

处理方式：

• 要求 Codex 引用它依据的文件。
• 对官方事实要求附链接。
• 让它区分“已确认”和“推测”。
• 让它先读代码或资料再写文档。
• 对课程文案要求它说明目标读者和使用场景。

登录或权限问题

处理方式：

• 更新 Codex CLI 到最新版本。
• 重新运行登录流程。
• 检查当前账号计划和组织策略。
• 查看官方 Help Center 的 Codex 相关文章。
• 把“账号问题”和“项目问题”分开，不要混在一起判断。

Windows 桌面 App / CLI 专项排障

如果问题发生在 Windows 桌面 App、Microsoft Store / winget 安装、Windows sandbox、Worktree、Browser / Computer Use 插件、WSL 混合路径或 PowerShell 环境，可以参考社区维护的 Windows 专项排障库：

• Community Codex Windows Troubleshooting
• Windows Codex Error Guide
• Dogfood Matrix

提交日志、截图或诊断输出前，请先脱敏用户名、路径、私有仓库名、token 和账号信息。

切换 provider 后旧会话不可见

可能原因：

• 修改过 config.toml 根级 model_provider。
• 旧会话文件还在，但会话 metadata、SQLite 状态或项目路径缓存仍指向旧 provider。
• CLI /resume 能看到旧会话，但 Codex Desktop 项目侧看不到，可能只是 Desktop 最近 50 条会话的首屏显示限制。

处理方式：

• 先确认 ~/.codex/sessions 或 ~/.codex/archived_sessions 里是否还存在旧会话文件。
• 如果只是 Desktop 项目侧不可见，先判断是否被最近 50 条显示限制挡住。
• 如果确认是切换 provider 后 metadata 不一致，再参考 config.toml 里的社区工具说明。
• 使用第三方工具前先备份 ~/.codex，不要把它当成官方认证或账号切换工具。

排障任务卡

请帮我排查下面的问题。先不要修改文件。

现象：

我已经尝试过：

相关截图 / 日志 / 命令输出：

请输出：
1. 最可能的 3 个原因
2. 需要补充确认的信息
3. 最小复现步骤
4. 推荐的下一步
5. 哪些操作暂时不要做

验收标准

学完这一页后，你应该能做到：

• 先保留现场，再让 Codex 分层判断。
• 区分上下文、权限、环境、代码、账号和事实错误。
• 在不确定时要求 Codex 只读分析。
• 把排障结果沉淀进工作流护照或团队排障手册。