看懂 `codex doctor` 的每一行：六个分组逐条读法与排查判定
Codex（OpenAI Codex）的命令行工具 Codex CLI 出状况时，最常见的反应是去翻文档、去搜报错。但更省事的顺序是先跑一次 codex doctor——它把安装、配置、认证、沙箱、网络这些容易出问题的地方一次性体检完，直接告诉你哪一格是红的。
问题在于，doctor 一口气打出十几行，符号有四种，还有一行统计。第一次看的人很难分清：哪一行是真故障，哪一行只是”这个东西现在没在跑，但本来就不该跑”。这篇按分组把它拆开讲。
下面所有输出结构和文案，都来自本机在 codex-cli 0.147.0（Windows 11、zh-CN）上执行只读命令得到的结果。特性阶段、默认值、检查项都会随版本变化，你手上的版本如果不是这个，以你自己跑出来的输出为准。
先看抬头和结尾这两行
抬头长这样：
Codex Doctor v0.147.0 · windows-x86_64
两个信息：doctor 自报的版本号，以及平台三元组（本机是 windows-x86_64）。版本号这行别跳过——同一台机器上，本次采集开头执行 codex --version 拿到的是 codex-cli 0.131.0，十几分钟后再执行同一条命令变成了 codex-cli 0.147.0，而 which -a codex 全程只有一个可执行文件。Codex 是有自更新能力的（配置里有 check_for_update_on_startup，默认为 true），所以”我昨天记得的版本号和今天对不上”是正常现象。
由此有一条排查纪律：凡是涉及版本的判断，一律以当次实时输出为准，不要用记忆里的版本号去对文档。
结尾是一行统计，格式是这样：
17 ok · 1 idle · 1 notes · 0 warn · 0 fail ok
以及两句提示：加 --all 可以展开被截断的列表，加 --json 输出一份脱敏的机器可读报告。
状态符号一共观测到四种：✓ 对应 ok，○ 对应 idle，⚠ 对应 notes 或 warn，✗ 对应 fail。**看输出的正确顺序是先扫 ✗，再看 ⚠，○ 基本可以放过。**很多人被 ○ 吓到，其实它表示”这个组件当前处于空闲/未启动状态”，不是错误——后面讲 Background Server 时会具体说。
六个分组分别管什么
本机执行 codex doctor --summary 观测到的分组和检查项如下，检查项名逐字照抄：
| 分组 | 检查项 | 本机观测到的说明 |
|---|---|---|
| Notes | rollouts | 405 active files · 3.07 GB on disk |
| Environment | system | 语言环境（本机 zh-CN） |
| Environment | runtime | 安装方式 npm，含 package、bin、resources、path 四个路径 |
| Environment | install | consistent |
| Environment | search | 随包附带的 rg.exe 是否存在 |
| Environment | git | git version … |
| Environment | terminal / title | TERM=… |
| Environment | state | databases healthy |
| Environment | threads | rollout files and state DB thread inventory agree |
| Configuration | config | loaded |
| Configuration | auth | auth is configured |
| Configuration | mcp | N server (N stdio) · N disabled |
| Configuration | sandbox | restricted fs + restricted network · approval OnRequest |
| Updates | updates | update configuration is locally consistent |
| Connectivity | network / websocket / reachability | websocket 本机为 connected (HTTP 101 Switching Protocols) · 15s timeout |
| Background Server | app-server | not running (ephemeral mode) |
这张表的读法：**Environment 组回答”装对了吗”，Configuration 组回答”配置和身份读进来了吗”，Connectivity 组回答”出得去吗”，Notes 和 Background Server 是提示性的、不代表坏。**你遇到的现象归到哪一组，就重点盯那一组，别把整屏都当成待办清单。
其中三项值得单独说：
runtime会把 package、bin、resources、path 四个路径都打出来，配合install的consistent，用来判断”是不是装了多份、命令指向的和你以为的不是同一个”。sandbox那行是当前生效的沙箱与审批策略摘要，本机是受限文件系统 + 受限网络、审批策略 OnRequest。改了沙箱相关设置后，看它是最快的确认方式，比翻配置文件靠谱。threads检查的是 rollout 会话文件和状态数据库里的线程清单对不对得上，属于本地数据一致性检查。
现象一：改完配置没生效
这是最高频的一类。你改了 ~/.codex/config.toml，或者用 -c 传了个覆盖项，结果行为一点没变。
怎么确认是这个问题：直接跑
codex doctor --summary
盯 Configuration 组的 config 那一行。本机故意构造过一个语法不合法的 TOML 覆盖：
codex -c 'features=[unclosed' doctor --summary
结果是——命令没有崩溃退出，doctor 照常跑完，但输出里出现了这一行：
✗ config config could not be loaded - Fix the reported config error, then rerun codex doctor.
这个行为很关键：配置坏掉的时候 Codex 不会拦着你不让跑，它只是悄悄没加载配置。所以”我明明改了却没生效”，绝大多数情况就是这一行在告诉你答案。
处置：按报出的配置错误改掉 ~/.codex/config.toml（或修正你 -c 传的那串值），然后重跑 doctor。这也是官方提示语本身给的做法——原文就是”Fix the reported config error, then rerun codex doctor”。
顺带一个容易踩的点：-c 的 value 是按 TOML 解析的，解析失败就按字面字符串处理。所以像 -c 'sandbox_permissions=["disk-full-read-access"]' 这种带引号和方括号的，在不同 shell 里外层引号要写对，否则你以为传了个数组，实际传进去的是一串字符。
处置后怎么验证：重跑 codex doctor --summary，config 那行从 ✗ 变回 loaded，同时结尾统计行的 fail 计数应该回到 0。
什么情况说明不是这个原因：如果 config 一直显示 loaded，那配置文件本身是好的，问题多半出在你改的键名拼错了、或者被别的层级覆盖了。这里要提醒一句 --strict-config 的边界——它的作用是”config.toml 里出现本版本不认识的字段时直接报错退出”，但本机实测执行
codex -c model_reasoning_effortt=high --strict-config exec --help
照常打印了 help，没有报未知字段错误。说明这类校验发生在真正加载配置去跑会话的时候，--help 这种不进入会话的路径不触发校验。所以别把 --strict-config 当成”任何情况下都能帮我抓拼写错误”的保险丝。
现象二：磁盘莫名其妙被吃掉几个 G
怎么确认：看 doctor 的 Notes 组。本机 rollouts 这一项直接写着 405 active files · 3.07 GB on disk。
这不是报错，是提示。但它指向一个真实存在的运维问题：~/.codex/ 目录下有 sessions/（会话 rollout 落盘，按年份分子目录）、archived_sessions/、history.jsonl，以及若干 SQLite 库。本机 logs_2.sqlite 这一个文件就占了 763 MB。
处置边界：这里必须说清楚——关于”该删哪些、能不能删”，本文没有官方依据，所以不给删除方案。Codex CLI 本身提供了 archive / unarchive / delete 三个子命令，可以按 id 或会话名归档、取消归档、永久删除已保存的会话；codex exec 还有 --ephemeral 选项，作用是不把会话文件落盘。是否使用、用在哪些会话上，你自己判断，delete 是永久删除。
处置后怎么验证：这一项没有”修好”的标准态，唯一有依据的验证点是那两个数字本身——如果你按自己的判断用 archive 归档了部分会话，重跑 codex doctor --summary，看 Notes 组 rollouts 那行的 active files 与 on disk 是否比处置前下降。数字没动，说明你动的不是这块占用。
什么情况说明不是这个原因：Notes 里的 rollouts 数字只统计 Codex 自己的会话落盘。如果你的磁盘告急量级远大于这里报的数字，那跟 Codex 无关，别在这儿耗时间。
现象三：疑似连不上
怎么确认：看 Connectivity 组三行。network、websocket、reachability 分别覆盖基础网络、长连接和服务端点可达性。本机 websocket 那行是 connected (HTTP 101 Switching Protocols) · 15s timeout，reachability 是”active provider endpoints are reachable over HTTP”。
HTTP 101 是协议切换，也就是长连接握手成功了。这行如果没成，和 network 一起看能大致分清是”完全出不去”还是”HTTP 通但长连接被掐”。后半段的 15s timeout 是这次检测用的超时值，在网络慢的环境下值得留意。
处置与验证：websocket 或 reachability 没过时，本文不给具体的网络侧改法——代理、防火墙、DNS 这些改动本机没有实测过，事实卡里也没有官方依据，照抄来路不明的方案只会把环境搞得更乱。能给的是判定口径：不管你在网络侧做了什么调整，处置后统一以重跑 codex doctor --summary 为准，看 Connectivity 那三行是否全部转成 ✓，以及结尾统计行的 fail 计数是否回到 0。只要这两处没变，就说明你的调整没作用在 Codex 实际走的这条链路上，别继续加码。
**别把这一组和登录问题混为一谈。**认证状态在 Configuration 组的 auth 行（本机 auth is configured），单独确认可以跑：
codex login status
本机实测这条命令输出一行：Logged in using ChatGPT。auth 显示已配置、login status 也正常，那就不是身份问题，别再去反复重登。
现象四：app-server 显示 not running
本机 Background Server 组的 app-server 是 not running (ephemeral mode)，对应的符号是 ○（idle）而不是 ✗。
这是最容易被误读成故障的一行。它只是说后台服务当前没有常驻在跑，并不代表哪里坏了。顺带一提，app-server 和 remote-control 这两个子命令在 codex --help 里都明确标着 [experimental]，cloud 与 exec-server 标的是 [EXPERIMENTAL]——处在这个阶段的东西，不建议拿去撑生产流程。
同样的道理适用于 codex features list：它列出的特性阶段共观测到五种，stable、under development、experimental、deprecated、removed。这里有个反直觉的地方——removed 阶段的特性仍然会出现在列表里，而且部分 removed 项的生效值是 true。合理的理解是：removed 指的是这个开关本身不再需要你去控制、行为已经固化，不等于功能没了。看到 removed 就以为功能被砍掉，是常见的误读。
把 doctor 结果贴给别人之前
codex doctor --json 的官方说明是 “Emit a redacted machine-readable report”——是脱敏的。这对”能不能把诊断结果贴到 issue 或工作群里”有直接的结论意义：用 --json 这一份比人肉复制终端截图更稳妥。
类似的设计还有一处：本机 codex mcp list 的表头是 Name | Command | Args | Env | Cwd | Status | Auth，其中 Env 列里的环境变量值会被打成 *****，只显示键名。也就是说这条命令自带脱敏，可以安全贴出来。
即便如此，贴之前自己扫一眼仍然是必要的：runtime 那几个路径里会带你的用户目录。写进公开渠道时把它替换成 ~/.codex/… 这种形式，密钥一律写 <YOUR_API_KEY>。~/.codex/auth.json 存的是登录凭据，官方明确要求当密码看待，任何情况下都不要贴出来。
什么情况下 doctor 帮不上忙
三种情况，别在 doctor 上耗时间：
一是全绿但行为不对。doctor 检查的是安装、配置、认证、沙箱、连通性这一圈本地健康度，它不评估模型输出质量，也不做任务级诊断。全绿只说明”环境没毛病”。
二是桌面应用侧的问题。官方《Troubleshooting》页里的排查条目大多面向桌面应用——侧栏、diff 面板视图、字体设置这类，跟 CLI 是两套。看到某条解法提到点某个菜单，先确认它说的是不是你正在用的这一面，别张冠李戴。
三是版本对不上导致的”功能有没有”之争。CLI 和桌面应用是各自独立的版本线，官方给的做法是分别查各自的版本号再比对，而不是默认两边同步。
最后回到最省事的那条：任何 Codex CLI 的怪问题，第一条命令都跑 codex doctor --summary，先扫 ✗，再看 ⚠，○ 放过——多数”改了没生效""连不上""装了两份”的问题能在这一步定位到是哪一格。
相关阅读
- 版本号自己变了：Codex CLI 自动更新与版本口径排查
~/.codex悄悄吃掉几个 GB：rollout 会话与 SQLite 日志的磁盘占用排查- Codex 的日志、SQLite 状态库与 OTel 遥测：先分清三层，再决定开什么
- Codex 的六个使用面：一张图看懂该用哪个
本文依据 Codex 官方文档（learn.chatgpt.com/docs/ 的《Troubleshooting》《Codex CLI》页面）整理，核对日 2026-08-09；文中标注「本机实测」的部分基于 codex-cli 0.147.0 / Windows 11 环境下的只读命令输出。产品功能、模型与价格以官方最新说明为准。桌面应用与云端部分为官方文档口径，非本机实测。