奇 奇连 AI
学习路线图课程工具计算器企业服务关于加入会员

`codex doctor` 里那行 ✗ config 是什么意思：配置加载失败的判定与处置

2026-08-09

改完配置没生效，是用 Codex（OpenAI Codex）命令行时最容易走弯路的一类问题。典型的弯路是：怀疑键名写错了，于是去翻配置文档；翻了半天发现键名没错，又怀疑是版本不支持；折腾一圈才发现整个配置文件压根就没被加载进来，里面写什么都不重要。

这一步本来有个非常快的判定方法，就是 codex doctor。下面把这条路径拆开讲。

一、现象：设置像是被无视了

能落到本文这一类的现象，共同特征是”配置写了但完全不起作用”，而不是”起作用了但效果不对”：

  • 在 config.toml 里设了 model，实际用的还是别的模型；
  • 配了 mcp_servers，codex mcp list 里却看不到那个服务器；
  • 调了 approval_policy，审批行为跟没改一样；
  • 加了 [windows] 段，Windows 侧沙箱表现没有任何变化。

注意区分另一类现象：配置生效了，但语义跟你以为的不一样（比如 web_search 官方默认值是 cached，既不是关闭也不是实时）。那不属于加载失败，本文最后一节会讲怎么把这两类分开。

二、怎么确认：让 doctor 自己说话

判定命令只有一条（下文命令均为 codex-cli 0.147.0 / Windows 11 下实测，其它平台请以 codex doctor --help 为准）：

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 分组。要看的是 Configuration 组里名为 config 的那一行——健康时它显示的是 loaded。

每行前面的状态符号本机观测到四种，含义如下：

符号含义
✓ok
○idle
⚠notes / warn
✗fail

输出结尾还有一行统计，格式是 17 ok · 1 idle · 1 notes · 0 warn · 0 fail ok。排查配置问题时，先扫这行里的 fail 计数，再去正文找是哪一项挂了，比逐行读快得多。

配置真的坏掉时长什么样？本机实测过一次：在 codex-cli 0.147.0（Windows 11）上故意传一段语法不合法的 TOML——

codex -c 'features=[unclosed' doctor --summary

命令没有崩溃退出，doctor 照常跑完了全部检查，但输出的 Notes 区里多了这么一行：

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

这条实测结论的价值在于两点。第一，配置坏了不会把 CLI 直接打挂，它可能就这么带着一份没加载成功的配置继续跑下去，你从表面行为上看只会觉得”设置没生效”。第二，doctor 在配置坏掉的时候仍然能跑，并且会明确告诉你配置没加载成功——所以**“改完配置没生效”的第一步永远是跑一次 doctor 看这一行**，而不是去翻键名。

补充一句 shell 相关的：上面这条命令是在 Git Bash 下执行的。Windows 上如果你用的是 PowerShell 或 cmd，引号规则跟 Git Bash 不一样，命令可能因为引号被 shell 吃掉而报出完全不同的错。遇到怪异报错时，先在 Git Bash 里复现一遍，确认是 Codex 的问题还是 shell 的问题。

三、分层定位：到底是哪一层配置坏了

Codex CLI 的配置不是一个文件说了算，它是叠起来的。从官方 help 原文可以看出至少三层：

  1. 基础用户配置：$CODEX_HOME/config.toml，默认在 ~/.codex/config.toml（Windows 上就是 <你的用户目录>\.codex\config.toml）。
  2. profile 叠加层：-p, --profile <CONFIG_PROFILE_V2>，把 $CODEX_HOME/<name>.config.toml 叠加到基础用户配置之上。
  3. 命令行覆盖层：-c, --config <key=value>，覆盖 ~/.codex/config.toml 里的值，点号路径表示嵌套（foo.bar.baz）。

看到 ✗ config 之后，用一组只读命令把这三层分开测，一次只动一个变量：

# A：什么都不带，只看基础配置
codex doctor --summary

# B：带上你怀疑的那条命令行覆盖
codex -c model="o3" doctor --summary

# C：带上你平时用的 profile（选项位置与 B 相同）
codex -p <你的档名> doctor --summary

判读方法很直接：A 就已经 ✗，问题在 config.toml 本身；A 正常而 B 挂了，问题在你那条 -c 的写法上；A、B 正常只有 C 挂，问题在那个 profile 对应的 <name>.config.toml 里。（B 里的 -c model="o3" 是官方 help 给的示例写法之一，另外两个官方示例是 -c 'sandbox_permissions=["disk-full-read-access"]' 和 -c shell_environment_policy.inherit=all。上面这组分层命令是按 help 里的选项位置组合出来的，未逐项实测，以官方文档为准。）

这里有个反直觉的点值得单独拎出来：官方 help 对 -c 的说明是，value 按 TOML 解析，解析失败则按字面字符串处理。也就是说，-c 后面跟的值写歪了，未必都会像上面那个 features=[unclosed 一样把配置整个搞挂——按 help 的这句原话，它也可能被当成一个字面字符串安安静静地生效。这正是”没报错但也没生效”的一种来源。所以判读 B 这一步时，✗ 是明确信号，但 ✓ 并不能证明你那条 -c 写对了，还得看行为。

四、逐项核对键名与取值

确认是某个文件坏了之后，回到文件里核对。TOML 语法错误（括号、引号没闭合）通常一眼能看出来，麻烦的是键名和取值枚举。几个高频对不上的地方：

键官方给的取值
sandbox_moderead-only / workspace-write / danger-full-access
model_reasoning_effortminimal / low / medium / high / xhigh
model_reasoning_summaryauto / concise / detailed / none
approval_policyuntrusted / on-request / never，或写成一张细粒度配置表

approval_policy 这一行要多说一句：它既可以是字符串（粗粒度三档），也可以是一张表，表里是 approval_policy.granular.sandbox_approval、.rules、.mcp_elicitations、.request_permissions、.skill_approval 五个布尔开关。想”只放行某一类弹窗”，只能用表形式，用字符串做不到——如果你按字符串的写法去表达细粒度意图，写出来的东西自然不会被认。

核对键名时，请对着官方《Configuration Reference》页逐字抄，别中译、别凭印象。这个页面（和整个文档站的其它页面一样）在 URL 后面加 .md 后缀就能拿到 Markdown 版本，站点还提供 llms.txt 页面索引和 llms-full.txt 合并全文，扔给编辑器里的 AI 一起对比着看会快不少。

五、--strict-config 能抓什么，不能抓什么

拼错字段名这种错，有个专门的开关：--strict-config——config.toml 里出现本版本不认识的字段时直接报错退出。听上去是个万能拼写检查器，但它有边界。

本机在 codex-cli 0.147.0（Windows 11）上试过这条：

codex -c model_reasoning_effortt=high --strict-config exec --help

字段名里那个多出来的 t 是故意打的错。结果是正常打印了 help，没有报未知字段错误。说明 --strict-config 的校验发生在真正加载配置去跑会话的时候，--help 这类不进入会话的路径不触发校验。

所以对它的正确预期是：它能在你真正开跑时拦住拼错的字段，但不能靠 --help 之类的空跑来做一次”配置体检”。想体检还是用 doctor。

六、处置之后怎么验证

改完再跑一次同样的判定命令：

codex doctor --summary

三处要看：

  1. Configuration 组的 config 行回到 ✓，文案是 loaded；
  2. 结尾统计行里 fail 计数为 0 fail；
  3. 如果你改的是 MCP 相关配置，顺带看同组的 mcp 行（本机输出形如 N server (N stdio) · N disabled），再跑一次 codex mcp list 看服务器有没有真的进来。

doctor 还提示可以用 --all 展开被截断的列表，--json 输出机器可读报告。这里有一条对协作很实用的事实：codex doctor --json 的官方说明是 “Emit a redacted machine-readable report”——是脱敏的。所以要把诊断结果贴给同事或提到 issue 里，用 --json 这一路比截图整个终端更合适。同理，codex mcp list 本机实测会把 Env 列里的环境变量值打成 *****、只显示键名，也可以放心外发。当然，贴之前自己再扫一眼，别把仓库路径这类信息一并带出去。

七、什么情况说明问题不在”配置加载”

一条道走到黑是排查里最费时间的事。下面几种情况出现时，就别在 config 加载这一环上继续挖了。

其一，报错是选项级校验，不是配置加载。 比如本机实测执行 codex -s bogus-mode，得到的是：

error: invalid value 'bogus-mode' for '--sandbox <SANDBOX_MODE>'
  [possible values: read-only, workspace-write, danger-full-access]

For more information, try '--help'.

这种把可选值列给你、直接退出的报错，是命令行参数校验，跟 config.toml 有没有加载成功是两回事，改配置文件不解决它。

其二，doctor 里 config 是 ✓，但行为跟预期不符。 这说明配置加载成功了，只是它的语义和你的理解有出入。几个官方口径里最容易读反的地方：

  • shell_environment_policy.ignore_default_excludes 默认 true，含义是保留含 KEY、SECRET、TOKEN 的变量，不是排除——这个键名读起来极容易理解反。
  • features.unified_exec 官方标注默认 true 但 Windows 除外。本机 codex features list 实测 unified_exec 生效值就是 false，两边对得上，不是坏了。
  • codex features list 里阶段为 removed 的特性仍会列出来，而且部分 removed 项生效值是 true（本机 0.147.0 上 steer 就是这样）。“removed” 指的是这个开关本身不再需要控制、行为已固化，不等于功能没了。
  • MCP 服务器的 startup_timeout_sec 官方默认只有 10 秒，慢启动的 server 得显式调大；disabled_tools 是在 enabled_tools 之后套用的，两个都配时以 deny 为准。
  • 自定义模型提供方的 wire_api 默认 responses，且官方明确只支持 responses——接不上第三方端点时，先确认对方提供的是不是 Responses 协议兼容端点，这不是配置文件写法问题。

其三，你比对的两个 Codex 不是同一个。 官方排查文档里明确列了这一条：某个功能在 CLI 有、桌面应用没有，原因是两个面的 Codex 版本不同，官方给的做法是分别查版本——CLI 用 codex --version，macOS 上的桌面应用用 /Applications/Codex.app/Contents/Resources/codex --version。桌面应用侧我们没有实测，这里只转述官方口径。

顺带提醒版本这件事本身：本机采集时有过一次真实观测，开头执行 codex --version 拿到 codex-cli 0.131.0，十几分钟后同一台机器同一条命令拿到 codex-cli 0.147.0，而 which -a codex 全程只有一个可执行文件。Codex 具备自更新能力（配置里 check_for_update_on_startup 默认 true），所以”我昨天看到的版本和今天不一样”是正常现象。排查任何跟版本、跟默认值、跟特性阶段有关的问题，都要以当次 codex --version 的实时输出为准，别用记忆里的版本号——默认值和特性阶段是会随版本变的，本文里所有标注”本机实测”的结论同样只对 0.147.0 负责。

相关阅读

本文依据 Codex 官方文档（learn.chatgpt.com/docs/ 的《Configuration Reference》《Troubleshooting》页面）与 codex --help 实测原文整理，核对日 2026-08-09；文中标注「本机实测」的部分基于 codex-cli 0.147.0 / Windows 11 环境下的只读命令输出。产品功能、模型与价格以官方最新说明为准。桌面应用与云端部分为官方文档口径，非本机实测。

想系统学会用 AI？报名体系课或加入会员，照着学、照着用。

浏览课程 加入会员