专题 C · TROUBLESHOOTING

排障：
照着报错原文查

Codex 停着不动、报错、改了设置没反应，多数时候不是坏了，而是某条规矩在起作用：没开新对话、项目没信任、默认不联网……这一页把官方文档里写到的问题按症状整理成问题库，每条都告诉你原因、怎么办、该回哪一课补课。

随用随查 10 节 · 问题库 80+ 条章末测验形式参考 luongnv89/claude-howto · 事实依据 OpenAI 官方文档

问题库里每一条都长这样

症状 → 原因 → 怎么办 → 相关课。第 2 节可以搜索、筛选全部条目。

入门先用起来原理弄懂为什么实战动手练深入进阶与避坑

急着解决问题，直接去第 2 节搜；想以后少踩坑，读第 4、5 节的"原理"。

01入门

先别慌：看清它停在哪

排障像修车：先看仪表盘上哪个灯亮，再翻说明书，最后才拿扳手。Codex 也一样，先判断它卡在哪一步，再照着报错原文去查。

先看它停在哪是登不上、干到一半不动，还是报了错、改了设置没反应？停的地方不同，查法也不同。

再抄报错原文原文比你的转述准。整句复制下来，粘到第 2 节问题库的搜索框里。

最后才动手修从最窄的办法开始：批准一次、开个新对话、补一项配置。别一上来就开 Full access。

它停在哪？点一个最像的

五个随手能用的检查点

不用离开对话就能看的地方。记住它们，排障时能少猜很多。

去哪看	能看到什么	什么时候用
`/status`	对话 ID、上下文用了多少、额度	怀疑额度或对话太长
`/mcp`	MCP 服务器的连接状态	外部工具突然用不了
审阅面板 Last turn	Codex 最近一轮改了什么	想分清哪些是它改的、哪些是你改的
集成终端	当前目录、分支、`git status`	对话卡住，或者命令结果和你想的不一样（`Ctrl`+` 打开）
`/feedback`	反馈对话框，可以附上日志	确认是 bug，要交给官方

官方给的"卡住三步"

对话看起来卡住时：① 先看它是不是在等你批准；② 打开终端跑一条简单命令，比如 git status；③ 开一个新对话，用更小、更聚焦的提示词重来。

02入门

问题库：按报错原文查

粘贴报错原文，或者输入几个关键词，也可以按类别翻。每一条都写着原因、怎么办和该回哪一课补课，只收官方文档写得到的问题。

试试：

条目依据 2026-09-30 的官方文档；按钮用的是官方英文名，位置和文字以你的 App 为准。点条目里的星标可以收藏，收藏只存在这个浏览器里。

03实战

练一练：看症状猜原因

6 个场景，每个只有一个主因。选完看解析；拿不准，就去问题库搜一下再答。

04原理

改了没生效：逐项对一遍

改完 AGENTS.md、配置、hook、插件却没反应，几乎都卡在四件事上：什么时候重新读、项目信任了没有、有没有审查信任、放对地方没有。选你改的东西，看它要满足哪些条件。

为什么项目要"信任"了才加载

项目里的 .codex/ 可以带 hooks 和 rules：前者能在你的电脑上跑脚本，后者能放行命令。别人的仓库里放了什么，你不一定清楚，所以 Codex 要你先信任这个项目，才加载这一层。你自己的 ~/.codex 不受影响。

05原理

是谁拦下的：四道关

住小区的人都懂：进门要过围墙、门卫、物业规定，最后还有自家的门锁。Codex 被拦下时也一样，先分清是哪一关，才知道该改哪里。

哪一关	你会看到	怎么办
沙箱围墙：技术上过不去	要联网、要写项目外的文件、要写 `.git` 的命令过不去。默认档位下它会先停下来问你；没人批准时（比如定时任务）就直接失败。	这一次需要就批准一次；经常需要就调配置，例如 `network_access`、`writable_roots`（第 3、7 课）。
审批门卫：你或自动审查说了算	批准卡片；Approve for me 下是自动审查条目，状态有 Reviewing、Approved、Denied、Aborted、Timed out。被拒太多次会中止这一轮。	选最窄的范围批准；被拒了就换更安全的做法，确认没问题可以用 `/approve` 放行一次重试。
组织策略物业规定：管理员定的	某个权限档位是灰的；一登录就被登出；hook 一个都不跑；有些设置你改了也不起作用。	本地改不了，找管理员。管理员的强制要求（如 `requirements.toml`）你用 `config.toml` 覆盖不了。
操作系统自家门锁：系统自己的权限	macOS 弹窗要访问"下载""桌面"；Windows 报 `1385`、提示 Everyone 可写；Linux 启动时警告缺 `bwrap`。	按系统提示处理；Windows 的细节见专题 B。

别拿 Full access 当万能钥匙

官方把"还没弄懂流程，就把电脑的完全权限交给 Codex"列为新手常见错误。它拆掉的只是沙箱和审批这两关，管不了组织策略；而且没人再替你把关。能批准一次解决的，就别换档位。

06实战

排障实况：Worktree 里测试跑不起来

接着 order-admin 的剧情：你想让 Codex 在 Worktree 里给退款接口补测试，结果连测试都跑不起来。点"开始"跟着查一遍，中途的批准卡片"允许"和"拒绝"都可以点。

画面为教学示意：报错文字、测试数量和 Codex 说的话都是虚构的；Worktree 不带被忽略的文件、.worktreeinclude、Hand off 的行为与官方文档一致。

07实战

练一练：先去哪儿看

第 1 节的五个检查点，各自该在什么时候用？每个场景选一个最先去看的地方。

08深入

日志、版本与求助

问题库里查不到，或者怀疑是 bug，就该拿证据说话了：日志在哪、版本多少、怎么把问题交给官方。

日志放在哪

什么	在哪
App 日志（macOS）	`~/Library/Logs/com.openai.codex/YYYY/MM/DD`
对话记录	`$CODEX_HOME/sessions`（默认 `~/.codex/sessions`）
归档的对话	`$CODEX_HOME/archived_sessions`
Windows 沙箱日志	`CODEX_HOME/.sandbox/sandbox.log`
登录日志（命令行）	日志目录里的 `codex-login.log`
终端界面日志（命令行）	设了 `log_dir` 后，那个目录里的 `codex-tui.log`

自动审查的记录也在 ~/.codex/sessions 里。你可以让 Codex 帮你分析这些记录，再决定要不要调权限。

先确认版本

App 和 CLI 各自带着一份 Codex，版本可能不一样。新功能会先到其中一边，实验功能也常常先上 CLI。所以"CLI 里能用、App 里没有"不一定是故障。

终端

# 命令行版本
codex --version
# App 自带的 Codex 版本（macOS）
/Applications/Codex.app/Contents/Resources/codex --version

当前最新版本和发布节奏见专题 A。

自己先测一测（命令行）

终端

# 这条命令在沙箱里会怎样？顺便记下被拦的操作（macOS）
codex sandbox macos --log-denials npm install
# 这条命令命中哪条 Rules、最后是什么决定？
codex execpolicy check --pretty --rules ~/.codex/rules/default.rules -- git push
# 它现在读到了哪些 AGENTS.md？
codex --ask-for-approval never "Summarize the current instructions."

Linux 用 codex sandbox linux，Windows 用 codex sandbox windows。命令行的用法第 14 课讲。

把问题交给官方

先到 GitHub 的 openai/codex issues 搜一下，看是不是已经有人报过。
在输入框里打 /feedback 提交反馈。在已有对话里触发时，可以选择把这个对话一起附上；提交后会拿到一个会话 ID。
新开 issue 时带上：会话 ID、报错原文、你在用哪个入口（App / CLI / IDE）、系统和版本、你想做什么。

发日志之前先看一眼

官方提醒：分享日志前先检查里面有没有敏感信息。~/.codex/auth.json 里是登录令牌，等同于密码，不要提交、不要贴进工单或群聊。Windows 用户发沙箱日志时，不要发 CODEX_HOME/.sandbox-secrets/ 里的内容。

09深入

升级后才冒出来的问题

有些故障是旧写法造成的：以前能用的配置和命令，升级后被废弃或移除了。照着旧教程配出来的环境，最容易踩到这些。

旧教程对照

approval_policy = "untrusted"：已退役，留在配置里可能让 App 和 CLI 都起不来。改成 sandbox_mode = "read-only" 加 approval_policy = "on-request"；想让某个项目的命令都要批准，给它设 trust_level = "untrusted"。on-failure 也已废弃。
[profiles.名字] 表和 profile = "名字"：新版 CLI 不再读取，改成单独的 ~/.codex/名字.config.toml，用 --profile 名字 选。
codex exec --full-auto：已废弃，还能跑但会打印警告，改用 --sandbox workspace-write。
codex mcp-server（把 Codex 当 MCP 服务器）：已移除，集成改用 app server（实验）。接外部 MCP 服务器不受影响。
custom prompts（/prompts:名字）：已废弃，改用 skills（第 8 课）。
features.web_search* 开关：已废弃，改用顶层的 web_search；codex_hooks 功能键也已废弃，改用 hooks。
WSL1：已不支持，要用 WSL2（专题 B）。

排障问答

重启 Codex、开新对话，到底该做哪个？

看你改了什么。AGENTS.md 和刚装的插件：开新对话。Rules、config.toml 里的改动（包括停用某个 skill）：官方写的是重启 Codex。MCP 服务器：在 App 的设置里保存后点 Restart。skill 会被自动发现，没出现再重启。第 4 节的检查器里逐项列着。

同样的操作，为什么只有我这台电脑出问题？

逐个对比：App 和 CLI 的版本可能不同；CODEX_HOME 可能指向了别的目录，你改的不是它在读的那份；公司电脑可能有管理员的强制配置或 Windows 策略；这个项目在你这里可能没被信任。

要不要干脆开 Full access，一劳永逸？

不建议。官方把"还没弄懂流程就给完全权限"列为常见错误。更窄的办法几乎总是够用：这一次就批准一次；经常联网就开 network_access；要写某个目录就加一个 writable_roots；某几条命令用 Rules 放行（第 3、7、10 课）。

一个对话里修了半天，越改越乱

官方的办法是开一个新对话，用更小、更聚焦的提示词重来。一个对话只做一件完整的事；整个项目挤在一个对话里，上下文越堆越大，效果会越来越差。

App 里的按钮和这里写的不一样

App 改版很勤。本页的界面都是示意，按钮名用官方英文名；位置和文字以你电脑上的 App 为准。版本变化见专题 A。

为什么问题库里没有我遇到的报错？

这里只收官方文档写得到的问题，文档没写的不猜。遇到新问题，按第 8 节的步骤：先搜 GitHub issues，再用 /feedback 报告。

10检验

小测验

8 道题，每题选完会立刻看到解析。