CODEXGUIDE / 故障排查
Codex FAQ
按你遇到的现象直接进入解决步骤,不需要返回目录重新寻找。先保留错误和当前 Git 状态,再按最小范围逐项排查。
从入口选择开始:比较 App、CLI、IDE 与 Cloud·进入 Sentry 线上排障·查看验证流程·参考真实案例
症状优先判断下一步
登录与认证
4 个问题症状
Codex 登录失败怎么办?
下一步先保留完整错误、当前入口和操作系统,确认网络、系统时间与账号状态,再重新完成认证。
进入解决步骤 → 症状
ChatGPT 登录和 API Key 应该怎么选?
下一步按当前入口和账号能力选择。Cloud 使用 ChatGPT 登录;本地脚本或可信 CI 才考虑 API Key,并单独确认计费与权限。
进入解决步骤 → 症状
auth.json、Token 或 .env 可以发给 Codex 吗?
下一步不要把凭据放进提示词、截图、Issue 或 Git 提交。只让 Codex 检查凭据是否存在,不要输出真实值。
进入解决步骤 → 症状
登录成功后第一步应该做什么?
下一步先只读检查项目、工作目录和 Git 状态,确认入口和环境正确后,再进入权限设置或修改任务。
进入解决步骤 → 权限与审批
4 个问题症状
Codex 没有权限修改文件怎么办?
下一步先确认文件是否在工作区内、任务是否需要写入范围外,再检查审批策略;不要为了绕过错误直接切换到 Full access。
进入解决步骤 → 症状
为什么 Codex 要求网络或命令审批?
下一步网络、工作区外写入和高风险命令会扩大影响面。先确认用途、目标和读写范围,再逐项批准。
进入解决步骤 → 症状
sandbox 限制和 approval policy 有什么区别?
下一步sandbox 决定执行环境能访问什么,approval policy 决定哪些动作需要人工确认;两者共同构成任务边界。
进入解决步骤 → 症状
什么时候可以使用 Full access?
下一步只有在任务明确需要更大范围,并且已经确认目标、备份、凭据和回滚方式时才考虑扩大权限。
进入解决步骤 → Git 与工作区
4 个问题症状
Codex 修改后 Git diff 看不到怎么办?
下一步先运行 git status --short --branch,确认当前目录、分支和文件是否正确,再排查是否修改了另一个工作区。
进入解决步骤 → 症状
已有未提交修改时能让 Codex 开始吗?
下一步先确认这些修改是谁做的、是否需要保留以及是否会与任务冲突;不要为了得到干净状态而删除或覆盖它们。
进入解决步骤 → 症状
如何避免 Codex 把无关文件一起改了?
下一步在任务中限定允许修改的目录,执行中查看 diff,结束后检查未跟踪文件、锁文件和配置文件是否超出范围。
进入解决步骤 → 症状
多个 worktree 或分支导致结果不一致怎么办?
下一步分别记录当前路径、分支和提交,确保 Codex 与你查看 diff 使用的是同一个工作区。
进入解决步骤 → 测试与验证
4 个问题症状
测试通过了,为什么还不能算完成?
下一步还要确认 diff 范围、页面行为、构建结果和未验证部分;Codex 的完成提示不是验收证据。
进入解决步骤 → 症状
验证失败后应该先做什么?
下一步保留失败命令、完整错误、路径和当前分支,先区分环境、权限、依赖、Git 和代码问题。
进入解决步骤 → 症状
项目修改前就已经测试失败怎么办?
下一步先记录基线错误,不要把它和本次修改混在一起;修改后用同一条命令比较结果。
进入解决步骤 → 症状
构建通过但页面仍然不对怎么办?
下一步补做浏览器或页面行为检查,确认路由、交互、移动端布局和控制台错误,而不是只依赖构建退出码。
进入解决步骤 → Windows 与 WSL
2 个问题症状
Windows 和 WSL 路径不一致怎么办?
下一步统一 Git、Node、包管理器和 Codex 的运行环境,确认工作目录、换行符、编码和执行权限。
进入解决步骤 → 症状
命令在终端可用,在 Codex 中却找不到怎么办?
下一步确认 Codex 使用的终端、PATH 和项目目录与人工验证时一致,再记录版本和完整命令。
进入解决步骤 →