Codex 故障排除与速查
排错先保存原始症状，再按安装、工作区、配置、权限、网络和外部服务逐层缩小范围。不要用扩大权限掩盖配置错误。
核对日期 2026-07-15 · 当前实测 CLI 0.144.3
先运行这组只读检查
codex --version
codex doctor --summary
git status --short --branch
pwd需要保存脱敏诊断：
codex doctor --json > codex-doctor.json分享前仍要人工检查路径、用户名、仓库名和环境信息；“redacted”不等于可以直接公开整份文件。
按症状查找
| 症状 | 先检查 | 不要先做 |
|---|---|---|
codex 找不到 | which codex、安装来源、shell PATH、重开终端 | 同时用 npm 和 Homebrew 反复安装 |
| 登录或认证失败 | codex login、账号类型、系统时间、代理和组织策略 | 把 Token 粘到聊天或截图里 |
| 打开了错误项目 | App 项目路径、CLI pwd、git rev-parse --show-toplevel | 用 --add-dir 开放更大范围来“找文件” |
| 配置没有生效 | CODEX_HOME、用户/项目配置层、--strict-config | 同时修改所有层 |
| 权限弹窗太多 | 当前 sandbox、approval、Rules 和动作原因 | 直接切危险全权限 |
| 命令在终端能跑，Codex 里不能 | shell、PATH、Local Environment、工作目录 | 把个人 shell 配置全部注入任务 |
| 网络请求失败 | sandbox、approval、目标域名、代理、组织策略 | 开放无限网络或输出代理凭据 |
| MCP 显示失败 | codex mcp list、启动命令、认证、作用域、服务日志 | 重复添加同名服务 |
| Review 不出现 | 当前产品是否为 Codex、项目是否是 Git 仓库 | 初始化 Git 前不看已有文件 |
| Worktree 缺文件 | tracked 状态、setup、.gitignore、.worktreeinclude | 把所有忽略文件和密钥复制过去 |
| Cloud 与本机结果不同 | 基线、setup、运行时、网络和环境变量名 | 假设 Cloud 是本机镜像 |
安装与 PATH
which codex
codex --version
npm list -g @openai/codex --depth=0
brew list --cask codex只保留你实际选择的安装渠道。更新后版本仍旧时，检查 which codex 指向的路径是否来自另一个 Node 版本管理器或旧安装。
目录与 Git 状态
pwd
git rev-parse --show-toplevel
git status --short --branch如果 pwd 在仓库子目录，而任务需要整个仓库，可以用 -C 明确根目录。只有确实跨仓库共享包时才使用 --add-dir。
发现已有修改时：
不要修改。先区分当前 diff 中哪些改动在本次会话开始前就存在，哪些是你产生的。不要还原任何无法确认所有者的内容。配置解析与作用域
codex --strict-config
codex -c 'approval_policy="on-request"' -s read-only一次性覆盖能帮助判断问题来自配置还是程序本身。按真实优先级从高到低检查：CLI flags 与 -c > 受信任项目中离当前目录最近的 .codex/config.toml > 选中的 profile > 用户 $CODEX_HOME/config.toml > 系统配置 > 内建默认值。
管理员 requirements.toml 与工作区策略是约束，不是普通覆盖层；即使高优先级配置请求了某个值，管理员仍可禁止它。未信任项目不会加载项目 .codex 配置、Hooks 或 Rules。
不要在排错记录中贴完整配置；保留相关键并遮盖 endpoint、路径和凭据。
Approval 与 Sandbox
权限被拒绝时先读失败信息：是文件不在 writable root、网络被禁、命令需要审批，还是组织策略禁止。
只读复现：
codex -s read-only -a untrusted日常开发基线：
codex -s workspace-write -a on-request如果某动作仍失败，解释它为什么需要更大范围，并只增加对应目录或规则。不要把 danger-full-access 当诊断开关，因为它会同时改变太多变量并扩大风险。
网络与代理
检查顺序：
- 任务是否真的需要网络。
- 当前 surface 是 Local、Worktree 还是 Cloud。
- sandbox 和 approval 是否允许网络动作。
- 组织是否限制目标域名或开发者模式。
- 代理是否只在交互 shell 中设置，App/IDE 是否读取到。
- 目标服务自身是否需要登录、VPN 或额外权限。
本地 workspace-write 中 spawned commands 默认不能联网。确需命令网络时使用 [sandbox_workspace_write] network_access = true，不要直接改成全权限。Web search 是独立控制面：普通本地任务默认 cached，--search 或 web_search = "live" 才会取实时结果，而且不会为每次搜索单独请求审批；--yolo 或其他 full-access sandbox 设置则默认 live。Browser、apps/connectors 和 Cloud agent 网络也分别受自己的设置控制。
不要让 Codex 输出代理 URL 中的用户名、密码或 Token。能用允许域名解决时，不开放任意网络。
MCP
codex mcp list
codex mcp --help逐项确认：
- 名称与作用域是否正确。
- stdio 启动命令能否在同一环境独立运行。
- HTTP endpoint 是否可达，认证是否过期。
- App/IDE 是否需要重启或新任务才能读取新配置。
- 工具是否被组织策略、插件状态或当前任务权限禁用。
先用无副作用查询验证连接，再尝试写操作。
IDE 与 App 上下文不同
- 确认 App 和 IDE 打开的是同一真实路径，而不是同名 Worktree。
- 确认两个 surface 使用预期登录、
CODEX_HOME和受信任项目。 - IDE 通过
chatgpt.addToThread/chatgpt.addFileToThread明确加入上下文；不要假设 App 自动得到 IDE 的选区、未保存内容或活跃任务。 - 每次切换入口后重新报告路径、Git HEAD、diff 和完成标准。
- 重启扩展或 App 后新建最小测试任务，判断问题来自历史任务还是配置层。
Worktree 与 Handoff
查看 Git worktree：
git worktree list
git status --short --branch错误 branch is already used by worktree 表示同一分支已在另一个 worktree checkout。使用 App 的 Handoff，或给两个工作区使用不同分支；不要强行删除仍在使用的 worktree 元数据。
依赖缺失时优先修 Local Environment setup。忽略文件确需复制时只列最小 .worktreeinclude，并检查 secret 生命周期。
Cloud
要求任务先输出环境事实：
不要修改。报告当前提交、操作系统、运行时版本、依赖状态、可用验证命令、环境变量名称和网络限制。不要输出 secret 值。对比本机与 Cloud：基线提交、锁文件、setup 输出、运行时、网络、时区和外部服务 endpoint。先解决环境差异，再判断代码是否有问题。
会话开始跑偏
使用短指令恢复控制：
停下，不要继续修改。把当前内容分为已验证事实、仍是推测、已产生的 diff 和下一步最小实验。回到原始完成标准。列出哪些修改超出范围；不要还原我原有的未提交改动。压缩会话时只保留：原始需求、已确认根因、修改文件、验证结果、失败结果和未完成步骤。目标或仓库已经改变时开新任务，比不断压缩旧上下文更可靠。
命令速查
# 健康检查
codex doctor --summary
codex doctor --json
# 交互会话
codex -C /path/to/repo
codex -s read-only -a untrusted
codex resume --last
codex fork --last
# 非交互
codex exec -s read-only "只读分析，不修改"
codex exec --json -s read-only "输出事件流"
codex review --uncommitted
codex review --base main
# 扩展
codex mcp list
codex plugin --help请求支持前准备
提供：
- Codex CLI 和 App/IDE 版本。
- 操作系统、入口和最小复现步骤。
- 脱敏后的完整错误文本。
codex doctor --summary或经人工检查的 JSON 相关部分。- 当前目录类型、Git 状态和是否使用 Worktree/Cloud。
- 已尝试的最小配置覆盖，以及结果有什么变化。
不要提供：API Key、浏览器 cookies、完整 .env、私人会话、客户仓库源码或未脱敏日志。