故障排查手册
排障的第一原则：保留完整报错，缩小变量，一次只改变一件事。不要只说“Codex 不工作”，要提供版本、目录、执行命令、预期、实际结果和最小复现。
先收集现场#
codex --version
pwd
git status --short
git rev-parse --show-toplevel
同时记录：
- 操作系统与终端；
- Codex 的启动方式；
- 是否使用自定义
config.toml； - 当前仓库是否有
AGENTS.md； - 报错发生在读取、修改、执行命令还是联网阶段。
登录或账户不可用#
- 确认网络和系统时间正常；
- 退出后重新完成官方登录流程；
- 确认组织管理员没有限制相关产品或模型；
- 不要在 issue 或截图中暴露令牌；
- 若只在某个网络环境失败，记录代理、VPN 和 DNS 差异。
账户能力可能因套餐和组织策略不同；以官方产品提示为准。
配置解析失败#
典型信号是启动即报未知字段、TOML 语法或无效值。
- 备份
~/.codex/config.toml； - 临时改为最小文件或移走；
- 重启确认默认配置能否启动；
- 对照当前版本的配置参考逐项恢复；
- 注意引号、表名和布尔值格式。
不要凭旧博客中的字段猜测当前配置。
无法修改文件#
先区分原因：
| 现象 | 常见原因 | 检查 |
|---|---|---|
| 所有文件都不能写 | 只读模式 | 当前 sandbox / mode |
| 只有某路径不能写 | 路径在工作区外 | pwd、仓库根目录 |
| 需要反复确认 | 审批策略较严格 | approval policy |
| 写入后又消失 | 任务被中断或工具回滚 | 会话日志、Git 状态 |
| 文件本身拒绝写入 | 系统权限或锁定 | ls -l、编辑器锁 |
不要直接切到无限制权限。先把工作目录和必要写入范围设对。
命令执行失败#
让 Codex展示完整命令、工作目录、退出码和输出。常见排查顺序：
- 人工在同一目录运行同一命令；
- 确认依赖已经安装；
- 检查 shell、环境变量与 PATH；
- 确认命令是否需要网络或工作区外写入；
- 缩小为单个测试或单个脚本。
如果人工运行也失败，问题通常在项目环境，不在代理。
Git 看起来不对#
先运行：
git status --short --branch
git diff --stat
git diff --check
git remote -v
常见情况：
- 在错误目录或嵌套仓库中执行；
- 工作区原本就有用户改动；
- 分支没有跟踪远端；
- 远端需要重新授权；
- 工作流文件修改需要额外 OAuth scope；
- 大小写文件名在不同系统表现不一致。
任何修复前先保护用户现有改动，避免使用破坏性 reset。
网络或 MCP 连接失败#
检查是否真的需要网络、当前模式是否允许访问、服务地址是否正确、认证是否过期。MCP 问题还要确认：
- 服务器能独立启动；
- 配置的命令和参数正确；
- 必要环境变量存在；
- 客户端看得到服务器暴露的工具；
- 超时不是由交互式登录造成。
最小化配置，只连接一个服务器验证，再逐个恢复。
输出质量差，但没有报错#
这通常不是“模型坏了”，而是任务信息不足：
- 目标是否具体？
- 范围和禁区是否明确？
- 是否给了验证标准？
- Codex 是否先读了关键文件？
- 任务是否大到需要拆分？
AGENTS.md是否包含冲突或过期规则？
把失败样例加入提示，并要求先复述理解或先只读分析。
何时提交问题#
当最小复现仍失败时，附上：
- Codex 版本与系统；
- 脱敏后的配置；
- 最短复现步骤；
- 完整错误文本；
- 预期与实际结果；
- 是否在默认配置下复现。
先查官方 Troubleshooting和官方仓库已有问题，避免重复提交。