Codex CLI 的 `-c` 到底覆盖了什么：四条规则与一次配置加载失败的实测

用 Codex（OpenAI Codex）的命令行工具久了，你迟早会遇到这种需求：只想这一次换个模型跑，或者只想这一次把沙箱调严一点，但完全不想动 ~/.codex/config.toml——那个文件一旦被改乱，后面每次启动都受影响。

Codex CLI 给的答案是顶层选项 -c, --config <key=value>。它看起来只是个普通的键值覆盖，实际上它的行为是四条规则叠加出来的，其中最后一条相当反直觉：写错了不一定当场报错。下面这些结论，命令行选项部分来自本机 codex --help 的逐字输出，行为部分来自在 codex-cli 0.147.0（Windows 11）上执行的只读命令。

一、四条规则，逐条拆

codex --help 里对 -c 的说明可以拆成四条独立的规则：

#	规则	你需要记住的后果
1	覆盖 ~/.codex/config.toml 里的值	作用范围是本次调用，不写回文件
2	点号路径表示嵌套（foo.bar.baz）	深层表不用写 TOML 段落头
3	value 按 TOML 解析	数组、布尔、数字都能直接传
4	解析失败则按字面字符串处理	语法写错不会在参数解析阶段拦住你

官方在 help 里给了三个例子，原样抄下来最保险：

codex -c model="o3"
codex -c 'sandbox_permissions=["disk-full-read-access"]'
codex -c shell_environment_policy.inherit=all

这三个例子恰好一条对应一种典型形态：字符串、数组、点号路径。

规则二：点号路径不只是省事

shell_environment_policy.inherit=all 这种写法，等价于在 config.toml 里写一个 [shell_environment_policy] 段落再写 inherit = "all"。在命令行上没法写多行段落，点号路径就是唯一的通道。

有个现成的例证能佐证这条规则的地位：--enable <FEATURE> 和 --disable <FEATURE> 这两个选项，help 里明说等价于 -c features.<name>=true / =false。也就是说，特性开关的专用选项本质上就是点号路径覆盖的一层语法糖。你如果记不住 --enable 的拼写，直接写 -c features.memories=true 是同一件事（memories 在 codex-cli 0.147.0 上 codex features list 里显示为 stable 阶段、生效值 false）。

规则三与规则四的交界：什么时候必须加引号

这两条要合起来读才有意义。规则三说「按 TOML 解析」，规则四说「解析不了就当字面字符串」。所以真正的分界线是：你想要的那个类型，靠不靠 TOML 语法才能表达出来。

• 想传布尔或数字：必须让它能被 TOML 解析成布尔/数字。TOML 里加了双引号就是字符串，这是 TOML 语法本身决定的，跟 Codex 无关。
• 想传数组：必须写成 ["a", "b"] 这种合法 TOML 数组，官方例子里外面那层单引号是给 shell 看的，不是 TOML 的一部分。
• 想传普通字符串：官方例子写的是 model="o3"，照抄最稳。规则四也解释了为什么不少人不加引号也没出事——解析不成合法 TOML 值时，它会被当成字面字符串收下。

这里有个很实在的 Windows 提醒。我们的实测环境是 Git Bash，官方例子里的单引号在这里能正常把整段 key=[...] 包住。换到 PowerShell 或 cmd，引号与转义规则是另一套，同一行命令抄过去未必得到同样的字符串。改完之后别凭感觉，用下一节的方法验一下。

二、写错之后会发生什么：一次实测

规则四最容易被读成「写错也没关系」。我们在 codex-cli 0.147.0（Windows 11）上故意构造了一个语法不合法的 TOML 值来看它到底怎么处理：

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

[unclosed 是个没闭合的数组，绝不可能解析成合法 TOML。实测结果是：命令没有崩溃退出，doctor 照常跑完全部检查项，但在输出里出现了这么一行：

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

把这两个观测拼起来，能得到一个对日常排查很有用的判断：参数解析阶段确实没有拦住你（规则四生效，它没在命令行这一层报错），但错误只是被推迟到了配置加载阶段。整份配置没有加载成功，而你在终端上看到的只是一行状态标记，不是醒目的红色崩溃。

如果你恰好没跑 doctor，而是直接开了会话，那么你会看到的现象就是经典的那句抱怨：「我明明加了 -c，怎么一点没生效？」——事实是整个配置都没加载，你原本 config.toml 里的设置也一起没生效了。

所以判断依据只有一条：任何时候你觉得「改完配置没生效」，第一步不是反复重读 config.toml，而是把当次那串 -c 原样带上跑一遍：

codex -c <你那串覆盖> doctor --summary

然后在 doctor 输出里找 config 这一行。在 codex-cli 0.147.0（Windows 11）上，正常运行时它出现在 Configuration 分组里、显示 loaded；而上面那次配置加载失败的实测里，输出中出现的是 ✗ config config could not be loaded 这一行（我们观测到它在 Notes 区）。所以别去死记它归在哪个分组，直接在输出里搜 config could not be loaded 这串字最省事。这是最短的判定路径，因为 doctor 本身不需要配置正确就能跑起来。

顺带一个能省掉纠结的事实：codex doctor --json 的官方说明是 “Emit a redacted machine-readable report”——它是脱敏的。所以要把诊断结果贴给同事或贴进 issue，用 --json 这条路本身是有官方依据的。不过贴之前自己再扫一眼，脱敏针对的是它已知的敏感项，不等于替你审阅了全部内容。

三、--strict-config 拦得住什么，拦不住什么

既然写错的键会被静默吞掉，很自然会想到那个看起来专治此病的选项：--strict-config，help 里的说明是「config.toml 里出现本版本不认识的字段时直接报错退出」。

我们同样在 codex-cli 0.147.0（Windows 11）上试了它的边界，故意把 model_reasoning_effort 多打了一个 t：

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

实测结果是：正常打印 help，没有报未知字段错误。

这条观测给出的判断依据是：--strict-config 的校验发生在真正加载配置去跑会话的时候，而 --help 这类根本不进入会话的路径不会触发校验。换句话说，别拿 --help 当配置写法的试金石——它能跑通，不代表你的键名拼对了。

那它该起作用的场景到底是哪一类？把 help 原文读准很关键：--strict-config 说明里点名的对象是 config.toml 里出现本版本不认识的字段，也就是写进那个文件的键。至于本节这种通过 -c 传进来的键名拼错，在真正进入会话的路径下会不会同样被它拦住，我们没有实测过，以官方文档为准。

所以给自动化脚本的建议要收着说：别把 --strict-config 默认当成一个「命令行拼写检查器」来依赖——至少在 --help 这类路径上，它确实没拦住我们那次故意拼错的键名。脚本里真正该做的，是上一节那条 doctor 判定，它验的是「整份配置有没有加载成功」这件更硬的事。

四、什么时候用 -c，什么时候别用

-c 不是唯一的配置入口，选错入口是另一类常见的浪费时间。按「这次改动要活多久」来分：

• 只活这一次 → 用 -c。它不写回文件，跑完就没了，适合临时试一个模型、临时试一个开关。
• 想固化下来 → 用 codex features enable / disable（help 里明说这两个子命令会写进 config.toml），或者直接编辑 config.toml。别用 -c 反复敲同一串参数。
• 一整套配置要成组切换 → 用 -p, --profile <CONFIG_PROFILE_V2>，help 的说明是把 $CODEX_HOME/<name>.config.toml 叠加到基础用户配置之上。适合「工作项目一套、玩具项目一套」。
• 完全不想吃用户配置 → codex exec 有个专属选项 --ignore-user-config，不加载 $CODEX_HOME/config.toml。注意 help 里特别写了：auth 仍然使用 CODEX_HOME。也就是说它隔离的是配置，不是登录状态，别指望用它来切账号。

有一处我不打算替你猜：-c 和 -p 同时出现时谁压谁，--help 里没写，我们也没有实测过。真要把两者混用，请以官方《Configuration Reference》页面为准，或者干脆分开用，省得靠猜。

五、一段可以直接抄的组合示例

把上面几条串起来，一个「临时收紧权限 + 临时改推理强度 + 顺手校验」的组合大致长这样（Git Bash 下的写法）：

# 第一步：先验配置能不能加载，再跑正事
codex -c model_reasoning_effort="high" \
      -c sandbox_mode="read-only" \
      --strict-config \
      doctor --summary

# 确认输出里 config 那行是 loaded、没出现 config could not be loaded，再进会话
codex -c model_reasoning_effort="high" -s read-only --strict-config

其中 model_reasoning_effort 的取值枚举是 minimal / low / medium / high / xhigh，sandbox_mode 的取值是 read-only / workspace-write / danger-full-access；沙箱这一项也有等价的顶层选项 -s, --sandbox，取值枚举完全一致。以上为按官方文档键位组合的示例，未逐项实测，以官方文档为准。

顺便说一个能立刻验证枚举有没有写错的小办法：顶层选项 -s 的取值是被严格校验的。在 codex-cli 0.147.0（Windows 11）上执行 codex -s bogus-mode，得到的是：

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

这是很好的对照组：走专用选项的取值会被当场卡住并把合法值列给你看，走 -c 的取值不会。 这也是我个人的习惯——有专用选项的（-s、-m、-a、--enable/--disable）就用专用选项，只有专用选项覆盖不到的键才动 -c。

六、两个别踩的坑

一是别把密钥往 -c 里塞。 官方在自定义模型提供方那一节明确写了 experimental_bearer_token 不建议使用、应改用 env_key（放 API key 的环境变量名）。命令行参数会进 shell 历史、会被同屏的人看见、贴日志时容易漏掉，所以密钥的正确形态是 <YOUR_API_KEY> 存在环境变量里、配置里只写变量名。

二是别望文生义地覆盖那些名字有歧义的键。 最典型的是 shell_environment_policy.ignore_default_excludes，官方给的默认值是 true，含义是在过滤之前保留含 KEY、SECRET、TOKEN 的变量。这个名字读起来像「忽略默认排除项」，很容易被理解反，一个 -c 敲下去方向就错了。改这类键之前，先把《Configuration Reference》上那一行说明读完整，比事后排查便宜得多。

收个尾：三步自检

改完一串 -c 之后，按这个顺序过一遍，基本不会再出现「改了没生效」的悬案：

1. codex -c <原样的覆盖串> doctor --summary，在输出里找 config 这一行看是不是 loaded，只要搜到 config could not be loaded 就说明整份配置压根没加载；
2. 想拦住键名拼写错误就带上 --strict-config，但记住它不在 --help 这类路径上生效，别用 --help 验证；
3. 判断这次改动要活多久：只活一次留在 -c，要固化就走 features enable 或写进 config.toml，成组切换用 -p。

最后提醒一句版本问题。同一台机器上我们采集时先后拿到过两个不同的 codex --version 输出，Codex 本身具备自更新能力（config 里的 check_for_update_on_startup 默认为 true）。所以排查任何与选项、默认值、特性阶段有关的问题时，都以你当次 codex --version 的实时输出为准，别用记忆里的版本号，也别直接照搬本文里的版本结论。

相关阅读

• Codex CLI 的 --profile：给不同项目挂不同配置层
• Codex 特性开关的五个阶段：removed 不等于功能没了
• codex doctor 里那行 ✗ config 是什么意思：配置加载失败的判定与处置
• Codex 的六个使用面：一张图看懂该用哪个

---

本文依据 Codex 官方文档（learn.chatgpt.com/docs/ 的《Configuration Reference》页面）整理，核对日 2026-08-09；文中命令行选项的原文说明与标注「本机实测」的部分，基于 codex-cli 0.147.0 / Windows 11 环境下的只读命令输出（--help、doctor --summary 及故意构造的错误参数），全程未发起模型对话请求。产品功能、模型与价格以官方最新说明为准。