Codex config.toml：哪个设置会生效？
定位 Codex 配置文件，核对 CLI、项目、profile 与用户配置的优先级，用可复现的命令发现被忽略的旧配置项。
最近更新: 2026-09-25
作者 Stometa · 核验依据与日期见正文中的来源和运行记录。
2026 年 9 月 25 日，我们用 Codex CLI 0.156.1 观察到三种不同结果：CLI 临时覆盖生效；项目里的 provider 字段被警告并忽略；旧 profile 选择器在会话启动前报错。改了 config.toml 却没有效果时，先用错误类型定位层级。TOML 语法正确，仍不足以证明字段已生效。
代价：项目配置增加了一个需要排查的层级。先用用户级默认值；只有团队需要共享行为时，才添加项目覆盖。凭证和 provider 路由留在用户配置里。
Codex 会读取哪个 config.toml？
OpenAI 官方配置说明列出了以下优先级，从高到低。只有上层没有设置某个值时，下层的值才会补上。
| 层级 | 位置或选择方式 | 9 月 25 日这次检查能证明什么 |
|---|---|---|
| CLI | 单次调用的 flag 或 -c key=value | 只读运行传入 -c 'model_reasoning_effort="low"' 后，运行头部显示 reasoning effort: low。 |
| 项目 | 受信任项目中，从根目录到当前目录的 .codex/config.toml | 官方文档称最近的文件优先；我们没有实测嵌套项目文件。 |
| Profile | $CODEX_HOME/<name>.config.toml，由 --profile <name> 选择 | 官方文档定义了这一层；本次没有选择 profile。 |
| 用户 | 默认 ~/.codex/config.toml | CLI 和 IDE extension 共用的默认配置。 |
| 云端、系统、内置 | 云端托管默认值、Unix 的 /etc/codex/config.toml，最后是内置默认值 | 存在时提供较低优先级的默认值；本次未实测。 |
项目文件不能用来改 provider 身份验证。官方高级配置说明明确说，项目级 model_provider、model_providers、openai_base_url、notify、profile 选择和遥测设置会被忽略。机器专属设置放在用户文件。项目没有被信任时，.codex/ 配置层也不会加载。
如果要长期指定推理 effort，先在用户文件中保留一个值：
model_reasoning_effort = "medium"
只想试一次时，在该次调用上传入 -c。CLI 将值按 TOML 解析，"low" 的双引号在 shell 的单引号参数内部：
codex exec --ephemeral --sandbox read-only \
-c 'model_reasoning_effort="low"' \
'Reply CONFIG_TEST_OK only. Do not use tools.'
上面就是 9 月 25 日执行的 shell 命令。运行头部出现 reasoning effort: low，最终输出 CONFIG_TEST_OK，退出码为 0。它继承了操作者已有的 provider 和全局指令，只能证明这次调用接受了覆盖值，不能证明后端模型身份、回答质量，或全新安装环境的表现。只读和临时会话限制了这个示例的目标；真实任务仍要核对自己的 sandbox 与审批设置。
怎么发现已失效或被忽略的字段？
Codex CLI 0.156.1 的 codex exec --help 列出了 --strict-config。普通未知字段的报错，其他配置指南已有介绍。我们在临时文件中检查了两个更有后果的情况：
- 在受信任的工作树里，临时
.codex/config.toml只写model_provider = "example-ignored"。一次只读、临时运行打印Ignored unsupported project-local config keys ...: model_provider，保留了原有 provider，输出PROJECT_CONFIG_TEST_OK，退出码为 0。运行后我们移除了临时文件。警告解释了为什么项目字段没有效果；只看退出码会漏掉它。 - 在一次性
$CODEX_HOME/config.toml中，我们把profile = "demo"放在[profiles.demo]表之前，然后执行codex exec --strict-config --ephemeral --sandbox read-only。会话启动前退出码为 1：legacy profile = "demo" config is no longer supported; use --profile demo with demo.config.toml instead。官方高级指南指出，这种格式从 CLI0.134.0起已经改变。
| 检查 | 9 月 25 日观察结果 | 下一步看什么 |
|---|---|---|
单次 -c 覆盖 | 退出码 0；头部为 reasoning effort: low；最终输出 CONFIG_TEST_OK | 在运行头部确认生效值。 |
项目级 model_provider | 退出码 0，但明确警告字段被忽略；原有 provider 保持生效 | 把 provider 路由移到用户配置。 |
旧版 profile = "demo" | 会话前退出码 1；迁移提示点名 --profile demo 和 demo.config.toml | 用独立 profile 文件取代旧选择器与表。 |
这只是同一个 CLI 版本的三项检查，没有覆盖所有设置。项目字段的检查继承了操作者原有的用户配置；旧 profile 选择器在加载配置时失败，因此一次性 home 无需登录。官方 CLI 文档与旧教程可能不同，改文件前先看本机 codex exec --help 是否支持对应参数。
哪些部分尚未验证？
本次没有实测嵌套项目文件或 profile 优先级。表格中的相关顺序来自 OpenAI 9 月 25 日文档，不是这一次运行的结果。下一次复现应使用一次性配置文件，记录生效值，同时避开凭证。首次使用流程可接着读Codex CLI 指南；仓库常驻指令见AGENTS.md 指南。