Codex 集成终端卡住不响应：官方给的处置动作与自查顺序

2026-08-09

用 Codex（OpenAI Codex）的时候有一类问题特别磨人：集成终端的面板还在，光标也在，但你敲下去的命令像掉进井里，既不回显结果也不报错。这种时候人最容易做的两件事是重启电脑、重装客户端，两件都很贵，而且做完往往还不知道到底是什么毛病。

这篇只干一件事：把 Codex 官方排查页对「终端卡住无响应」这一条给出的处置动作原样讲清楚，再补一套你在本机能立刻跑的只读判定命令，用来排除掉那些”看起来像卡住、其实是别的问题”的情况。

先分清是哪个「终端」

Codex 有多个使用面：ChatGPT 桌面应用、Codex CLI、Codex IDE 扩展、Codex cloud、ChatGPT Web、Codex Remote。官方文档站为「集成终端」单开了一页（《Integrated terminal》），而官方排查页里”终端卡住无响应”这一条给的动作是关闭面板再重开——带面板、能被关掉和重开的，是带界面的那几个面，不是你在 Git Bash 或 PowerShell 里直接敲的 codex 命令。

这里要先说清楚立场：桌面应用、IDE 扩展、云端我们没有实测，下面凡是涉及面板的部分，一律是”官方文档给的做法是……”，不是我打开看到的。而涉及 CLI 的判定命令，全部是在 codex-cli 0.147.0（Windows 11）上真实跑过的只读命令。

分清这一点很重要，因为两边的排查入口完全不同：面板卡住能靠重开面板解决，CLI 里的问题重开面板没有任何意义。

官方给的处置动作

官方排查页对这条现象的处理只有三步，很短，我原样转述：

关闭终端面板；
用 Ctrl+` 重新打开；
先跑一条基础命令，比如 pwd。

注意官方在这一条里没有给出原因——它承认这个现象存在、给了处置动作，但没有说明面板为什么会卡、也没有给出根因层面的修复。所以你不要指望”照着做就永远不再犯”，这套动作的定位是恢复手段，不是修复方案。截至 2026-08-09，官方文档里我能查到的就是这些。

第三步很多人会跳过，其实它是整套动作里唯一有信息量的一步。pwd 这类命令不依赖模型、不依赖网络、不依赖沙箱初始化，它只回一个当前目录。所以它是一个纯粹的探针：

pwd 有输出，说明面板与底层 shell 的通路已经恢复，可以继续干活；
pwd 仍然没输出，说明重开面板没解决问题，此时别再重复关开面板了，往下走判定流程；
pwd 有输出但目录不是你预期的那个，那你面对的根本不是”卡住”，而是工作目录选错了——后面接着敲的命令当然全都不对劲。

第三种情况特别值得留意。同样一个仓库，在 monorepo 里打开了错误的子目录，表现就会非常像”命令没生效”。

一套能立刻跑的只读判定命令

面板那侧我们没法实测，但你本机的 Codex CLI 安装、配置、认证、网络这几层是能自查的，而这几层出问题的表现常常被误当成”终端卡了”。下面这些命令全部只读，跑了不会改你的任何东西。

第一条，先把版本钉死：

codex --version

在 codex-cli 0.147.0（Windows 11）上，我遇到过一个很容易让人怀疑人生的现象：同一台机器，采集开头这条命令回的是 codex-cli 0.131.0，十几分钟后再敲同一条命令，回的是 codex-cli 0.147.0，而 which -a codex 全程只有一个可执行文件。Codex 具备自更新能力，所以”我昨天记得的版本号和今天不一样”是正常现象。结论就一句：排查任何版本相关的问题，以当次输出为准，别用记忆里的版本号。

顺带说一条相关的官方口径：CLI 和桌面应用可能是不同版本，这正是”CLI 有的功能桌面应用没有”的官方解释。官方给的查法是分别查——CLI 用 codex --version，macOS 上的桌面应用用 /Applications/Codex.app/Contents/Resources/codex --version。Windows 上桌面应用对应的可执行文件路径，官方文档里我没查到，我也不编一个给你。

第二条，跑体检：

codex doctor --summary

在 codex-cli 0.147.0（Windows 11）上，这条命令的抬头是 Codex Doctor v0.147.0 · windows-x86_64，结果按 Notes / Environment / Configuration / Updates / Connectivity / Background Server 分组，结尾是一行统计，格式形如 17 ok · 1 idle · 1 notes · 0 warn · 0 fail ok，状态符号有四种：✓、○、⚠、✗。它还会提示用 --all 展开被截断的列表。

排查这类问题时，重点看这几行：

分组	检查项	它能回答什么
Environment	`terminal`	本机这行显示 `TERM=…`，反映的是当前跑 doctor 的终端环境
Configuration	`config`	配置到底有没有被成功加载
Configuration	`sandbox`	本机显示 `restricted fs + restricted network · approval OnRequest`
Connectivity	`network` / `websocket` / `reachability`	本机 websocket 行显示 `connected (HTTP 101 Switching Protocols) · 15s timeout`
Background Server	`app-server`	本机显示 `not running (ephemeral mode)`

其中 config 那行是我实测里最有价值的一条。我故意用 codex -c 'features=[unclosed' doctor --summary 传了一段语法不合法的 TOML，结果 doctor 没有崩溃退出，照常跑完，只是在报告里多出一行：

✗ config       config could not be loaded - Fix the reported config error, then rerun codex doctor.

也就是说，配置坏掉的时候 doctor 依然能跑，而且会明确告诉你配置没加载成功。所以”我改了配置怎么一点反应都没有”这类问题，第一步就该是跑 doctor 看这一行，而不是去重开面板。

第三条，确认登录状态还在：

codex login status

在 codex-cli 0.147.0（Windows 11）上，这条命令的输出是一行：Logged in using ChatGPT。

要把诊断结果发给别人时用这条：

codex doctor --json

官方对这个选项的说明是 “Emit a redacted machine-readable report”——它是脱敏的。这一点对”能不能把诊断结果贴到 issue 里”有直接的结论意义：官方把它定义成脱敏报告，设计上就是给你拿出去分享的，所以它比你自己截一屏原始输出要稳妥得多；不过贴之前仍然建议自己把输出扫一眼，毕竟脱敏范围由官方定义，你的环境里有什么敏感信息只有你自己清楚。

相对的，~/.codex/auth.json 是另一回事。官方对它的原话是要当密码看待——不要 commit、不要贴进工单、不要在聊天里分享。这条要求跟 doctor 报告的口径正好相反，别把两者混为一谈：诊断报告可以给别人看，凭据文件任何情况下都不行。

处置之后怎么验证

按官方动作重开面板之后，验收顺序建议这样走，一步一步来，别跳：

先跑 pwd，确认通路恢复，并且目录是你要的那个；
再跑一条明确不改文件的只读命令，比如 codex --version，确认 CLI 本身响应正常；
需要的话跑 codex doctor --summary，看结尾统计行里 fail 与 warn 是不是都为 0；
如果这次卡住之前你刚改过配置，补跑一次 doctor，专门盯 config 那一行有没有 ✗。

只要第 1 步的 pwd 一直没有输出，就别在”关面板、开面板”上反复循环了，继续做下面的排除。

什么情况说明不是这个原因

这一节比上面几节更重要。下面几种表现都容易被当成”终端卡住”，但处置路径完全不同：

一、是「功能不存在」，不是「卡住」。 你在面板里找不到某个功能，但 CLI 里有。官方明确把这归因为 CLI 与桌面应用版本不同，解法是分别查版本，而不是重开面板。

二、是配置没加载。 doctor 里出现 ✗ config 那一行，说明你的 ~/.codex/config.toml 有问题。这时候命令”看起来不生效”是必然的，先按 doctor 的提示修配置再重跑。顺带提醒一个实测边界：--strict-config 并不是万能拼写检查——在 codex-cli 0.147.0（Windows 11）上，我用 codex -c model_reasoning_effortt=high --strict-config exec --help 跑，它正常打印了 help，没有报未知字段错误。说明这个校验发生在真正加载配置去跑会话的时候，--help 这类不进入会话的路径不触发它。别把它当成”任何情况下都会拦住拼写错误”的保险。

三、是 Windows 沙箱没初始化起来。 这是中文用户的高频坑，跟面板一点关系都没有。官方文档里 Windows 侧的沙箱是在 PowerShell 中原生运行的，elevated 模式需要管理员批准的初始化设置。有一个具体错误值得记住：错误 1385，官方原话是 “Windows is denying the logon type the sandbox user needs.”，含义是沙箱用户已经创建，但策略不允许它执行命令。官方还点名了初始化失败的常见原因：拒绝了 UAC 提示、本地用户创建被阻止、防火墙规则被限制。官方给的排查顺序是四步：① 重启 Codex ② 重试 elevated 初始化 ③ 需要时回退到 unelevated ④ 发送诊断，日志在 CODEX_HOME/.sandbox/sandbox.log。

这四步之外的改法我不写。网上流传的注册表改法、组策略改法，官方文档里没有，我不给你编一个。另外要说明：unelevated 是拿不到管理员批准时的回退档，官方自己写了它的保护更弱，别把它当成等价选择。

四、是命令被沙箱拦了，不是没执行。 在 codex-cli 0.147.0（Windows 11）上，我用 codex sandbox 在沙箱里执行了一条往仓库路径写文件的 cmd /c "echo hi > …"，命令返回之后目标文件并不存在。也就是说，默认沙箱状态下写入没有落盘，而表面上命令是”跑完了”的。如果你的困惑是”它说做完了但文件没变”，那方向应该是沙箱与审批，不是终端面板。

五、是登录掉了。 codex login status 不返回登录态时，后面一切都白搭，先把登录恢复。

顺手记两个查文档的技巧

排查过程中你多半要频繁翻官方文档，有两个事实很实用：

任何文档页的 URL 后面加 .md 后缀，就能拿到 Markdown 版本；
文档站提供 llms.txt（完整页面索引）与 llms-full.txt（合并全文），可以直接喂给 AI 工具。

排查这类问题时，与其凭印象回忆某个选项叫什么，不如把对应页面的 Markdown 版拉下来当场对一遍。

最后强调一次判断顺序：先用 pwd 判断通路，再用 codex --version 和 codex doctor --summary 判断本机层面有没有别的毛病，最后才轮到”面板本身卡了”这个结论。顺序反过来，你会在关面板开面板上耗掉一下午。