Codex 常见问题排查清单：从认证到沙箱

先定位在哪一层

绝大多数故障落在五层里的一层：认证（who）、沙箱与审批（what can it do）、网络（can it reach）、指令文件（what does it know）、运行环境（where does it run）。先判断层，再动手，可以省掉一半的试错。

codex --version
codex login status
codex doctor

认证失败、登录过期、账号不对

认证问题的信号很直接：提示未登录、反复跳浏览器、或者明明登录了却报没有权限。先用一条命令确认当前凭证状态，再决定是重登还是换方式。

codex login status
codex login
codex logout

登录缓存由 CLI 和 IDE 插件共用：在一个端登出，另一个端也要重新登录。凭证默认明文存在主目录的 auth.json 里，也可以改成系统凭据库；不管存在哪，都按密码对待，不要提交进仓库。

# ~/.codex/config.toml
cli_auth_credentials_store = "keyring"

命令被沙箱拦了

沙箱拦截不是 bug，是设计。关键是分清当前是哪一档，以及被拦的是“写文件”“联网”还是“跑命令”。判断依据其实就在错误信息里：被拒的命令与路径会写出来。

1. 01

   看当前档位与可写根目录

   用 /status 查看当前模型、审批策略与可写根目录；用 /permissions 切换权限档位。看不懂配置合并顺序就敲 /debug-config。

2. 02

   用同一套策略复现

   codex sandbox 会用和内部一致的安全策略跑一条命令，能直接验证“到底是沙箱拦的还是命令本身错了”。

3. 03

   只放行需要的那条命令

   把常跑的命令加进规则白名单，比把整个会话提到 full access 安全得多。

4. 04

   确认平台沙箱是否可用

   Linux 需要 bubblewrap；Windows 用原生沙箱；macOS 开箱可用。缺依赖时启动会有告警，按提示装即可。

sudo apt install bubblewrap
# 或
sudo dnf install bubblewrap

网络、TLS 与 MCP 连不上

网络层的问题有两种表现：请求根本发不出去（证书、DNS、公司网关），或者工具连不上（MCP 服务启动超时、需要 OAuth）。前者看证书配置，后者看日志和超时设置。

export CODEX_CA_CERTIFICATE=/path/to/corporate-root-ca.pem
codex login

[mcp_servers.my_server]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
startup_timeout_sec = 20
tool_timeout_sec = 120

排查 MCP 时先确认配置写在哪：用户级在 ~/.codex/config.toml，项目级在仓库的 .codex/config.toml，且项目级配置只对受信任的项目生效。桌面应用、CLI 和 IDE 插件共用同一份配置，一处写错三处都连不上。

AGENTS.md 好像没生效

指令文件不生效，九成是三个原因：目录不对、文件是空的、或者被上一层的 override 顶掉了。判断顺序永远是：先确认实际加载了哪些文件，再改内容。

codex debug prompt-input
# 想确认某个子目录的覆盖是否生效
codex --cd apps/web debug prompt-input

# ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536

云端、IDE、Windows 的差异

同一件事在不同端上表现不同，很多时候不是故障，而是端与端的能力差异。比如云端任务不接受 API key 登录、IDE 插件不提供定时任务管理界面、WSL1 已经不被支持。

1. 01

   先确认版本和端

   codex --version 看 CLI；桌面应用用的是它自带的那份，功能可能先到一个端。两端版本差太多时，先统一再排查。

2. 02

   任务卡住先看是不是在等审批

   无人值守或后台运行时，最容易“卡”在等人点确认。切到该会话看一眼，或调整审批策略。

3. 03

   终端卡了就地重开

   关掉终端面板再用快捷键开回来，跑 pwd、git status 验证；仍然无响应就等任务结束后重启应用。

4. 04

   找日志

   会话记录在主目录的 sessions 目录（默认 ~/.codex/sessions），macOS 应用日志在 ~/Library/Logs/com.openai.codex/ 下按日期分目录。

求助前先收集这些

把下面几项准备好，能让你在提 issue 或找同事时直接被回答，而不是来回问十轮。注意日志和会话记录里可能有密钥与业务数据，发出去之前先脱敏。

• codex doctor 的报告
• codex --version，以及你用的是 CLI、IDE 插件还是桌面应用
• codex login status 的结果（不要贴令牌本身）
• 出问题的那条命令，或那段最小可复现的提示词
• 完整报错文本，尤其是被拒绝的命令与路径
• 操作系统与版本；Windows 用户注明是原生还是 WSL，以及 WSL 版本
• 相关的配置片段（脱敏后的 config.toml），以及 /debug-config 的层顺序
• /status 显示的模型、审批策略与可写根目录

codex doctor > codex-doctor.txt
codex --version >> codex-doctor.txt
codex login status >> codex-doctor.txt 2>&1
uname -a >> codex-doctor.txt

提交反馈时可以在输入框敲斜杠调出反馈入口，它会带上会话 ID，方便定位到具体那次运行。