Codex CLI 如何设置 model_reasoning_effort？

Codex CLI 可以在 config.toml 中设置 model_reasoning_effort。用户级默认配置写在 ~/.codex/config.toml，项目级配置写在仓库的 .codex/config.toml；一次性运行则可用 -c 或 --config 覆盖。常见值为 minimal、low、medium、high 和 xhigh，其中 xhigh 是否可用取决于模型。

最简单的用户级配置

打开用户目录中的 Codex 配置文件：

~/.codex/config.toml

加入模型和推理强度：

model = "当前使用的模型"
model_reasoning_effort = "medium"

这会成为当前用户启动 Codex CLI 时的默认值。模型名称应填写实际可用的模型标识，不要把示例占位文本直接保存。

项目级配置写在哪里

如果某个仓库需要不同配置，可以在项目中创建：

.codex/config.toml

例如，高风险代码库希望默认使用更充分的推理：

model_reasoning_effort = "high"

项目配置只会在 Codex 信任该项目时加载。未信任项目会跳过项目范围的 .codex 配置层，这是安全设计的一部分。

用户配置与项目配置如何选择

用户级配置适合个人通用习惯，项目级配置适合仓库特有需求。

位置	作用范围	适合用途
~/.codex/config.toml	当前用户	设置日常默认模型和推理强度
.codex/config.toml	当前项目或子目录	为特定代码库覆盖默认值
profile 配置	选定工作流	区分快速处理与深度审查
-c / --config	当前一次运行	临时试验，不修改文件

一次性从命令行覆盖

不想修改配置文件时，可以在启动命令中传入配置覆盖：

codex -c 'model_reasoning_effort="high"'

也可以使用长参数：

codex --config 'model_reasoning_effort="low"'

外层单引号由 shell 处理，内层双引号让值按 TOML 字符串解析。不同 shell 的引用规则可能不同，遇到解析错误时应先检查实际传给 Codex 的参数。

为什么不能省略 TOML 字符串引号

model_reasoning_effort 的值是字符串。以下写法明确可靠：

model_reasoning_effort = "high"

命令行覆盖同样需要让值被解析为字符串。若写成未加引号的裸值，解析器可能把它视为无效 TOML。

配置优先级是什么

Codex 会合并多个来源，官方配置顺序从高到低包括：

1. CLI 参数和 --config 覆盖。
2. 项目中的 .codex/config.toml，离当前目录最近的层级优先。
3. 通过 --profile 选择的 profile 文件。
4. 用户配置 ~/.codex/config.toml。
5. 工作区下发的云端默认配置。
6. 系统配置。
7. Codex 内置默认值。

因此，用户文件中写了 medium，但命令行显式传入 high 时，本次运行会使用命令行值。

子目录配置如何生效

Codex 可以从项目根目录到当前工作目录逐层读取项目配置，越接近当前目录的配置优先级越高。

这种方式适合单体仓库。例如，普通应用目录使用 medium，而安全组件子目录使用 high。不过配置层级过多会增加排错难度，应在仓库文档中说明覆盖关系。

如何设置 low

model_reasoning_effort = "low"

low 适合边界清楚、结果容易验证的任务，例如结构化提取、固定格式修改和局部代码调整。它偏向更低延迟和较少推理用量。

如何设置 medium

model_reasoning_effort = "medium"

medium 适合大多数交互式开发工作，可作为评测基线。它不是所有模型永久不变的默认值，因此需要可重复行为时应显式设置。

如何设置 high

model_reasoning_effort = "high"

high 适合跨模块调试、架构权衡、数据库一致性和安全审查。更高推理投入可能增加等待时间和用量，只有评测证明质量提升时才值得长期启用。

如何设置 xhigh

model_reasoning_effort = "xhigh"

xhigh 是模型相关档位。它适合最困难的异步 Agent 任务或能力上限评测，不适合作为所有会话的通用默认。

如果当前模型不支持，客户端或服务端可能拒绝请求。遇到问题时先切回 high，再检查模型文档。

minimal 是否可以设置

model_reasoning_effort = "minimal"

官方 Codex 配置参考将 minimal 列为候选值之一。它适合极其明确的机械任务，但具体模型仍需支持该档位。

不要混淆 API 与 Codex 配置

Responses API 使用 reasoning.effort，Codex CLI 配置使用 model_reasoning_effort。两者表达相近概念，但字段路径和支持值不应混用。

API 文档可能针对某些模型列出 none 或 max，而当前 Codex 配置参考列出的值集合可能不同。配置 CLI 时应以 Codex 配置参考为准。

把模型与推理强度一起记录

推理强度离不开具体模型。推荐在配置或测试记录中同时保存：

model = "团队批准的模型标识"
model_reasoning_effort = "medium"

切换模型后应重新确认支持值和默认行为。旧配置在新模型上可能失效，或得到不同的延迟与质量表现。

使用 profile 管理不同工作流

当同一开发者经常切换工作类型时，可以用 profile 隔离配置。profile 的具体文件名和选择方式应以当前版本文档为准，典型启动形式是：

codex --profile profile-name

可以为快速分诊设置 low，为日常开发设置 medium，为审计设置 high。这样比频繁修改用户配置更容易复现。

如何确认配置已经生效

1. 确认编辑的是 Codex 实际读取的文件。
2. 检查当前项目是否受信任。
3. 检查是否存在更高优先级的项目配置。
4. 检查启动命令是否带有 -c、--config 或 --profile。
5. 确认当前模型支持目标档位。
6. 重新启动会话并运行代表性任务。
7. 对照日志或运行信息核验模型与配置。

不要只根据回答长度判断是否生效。推理强度和输出长度是不同控制维度。

设置后没有变化怎么办

按以下顺序排查：

1. 检查键名是否准确为 model_reasoning_effort。
2. 检查等号、引号和 TOML 语法。
3. 确认键位于顶层，而不是误放进不相关表格。
4. 查看是否被项目配置或 CLI 参数覆盖。
5. 确认项目配置没有因未信任而被跳过。
6. 确认模型支持指定值。
7. 升级或重启客户端后再次验证。

常见错误一：键放错层级

如果先声明了一个 TOML 表格，后续键会属于该表格，直到出现新的表格声明。下面的写法可能让推理设置落入错误位置：

[features]
some_feature = true
model_reasoning_effort = "high"

推理强度应作为顶层配置。最稳妥的方式是把它放在文件顶部、任何表格声明之前。

常见错误二：忽略覆盖来源

很多“配置不生效”并非解析失败，而是有更高优先级的值。例如项目文件覆盖了用户文件，或启动脚本始终传入 --config。

排查时应列出所有配置层，而不是只反复编辑一个文件。

常见错误三：模型不支持档位

配置参考给出 Codex 接受的候选值，但最终还要由所选模型支持。尤其是 xhigh，官方明确标注为模型相关。

如果请求报无效参数，应先查模型能力，而不是把问题归因于网络或账号。

常见错误四：使用历史 Issue 作为现行文档

早期 GitHub Issue 可以说明用户曾经需要某项能力，但不能证明当前版本的配置方法。Issue 可能在功能实现前创建，也可能因后续变更而过时。

实际配置时应优先查看当前官方配置参考和客户端版本。

如何为团队提交项目配置

项目级配置会影响使用该仓库的成员，应做到：

• 只提交与项目确实相关的默认值。
• 说明为什么选择该推理档位。
• 记录已经验证的模型和客户端版本。
• 避免把个人路径或凭证写入配置。
• 为高成本档位提供评测依据。

成员仍可通过更高优先级的 CLI 覆盖进行一次性试验。

配置模板

日常交互开发：

model = "实际模型标识"
model_reasoning_effort = "medium"

低延迟、可自动验证的任务：

model = "实际模型标识"
model_reasoning_effort = "low"

复杂审查任务：

model = "确认支持的模型标识"
model_reasoning_effort = "high"

修改配置后的验证方法

准备一组固定任务，分别测试不同档位，记录首次通过率、测试结果、总完成时间、Token 用量和人工纠正次数。只有档位变化产生稳定差异时，才把结果固化为默认值。

模型升级后需要重新测试，因为支持能力和默认行为可能变化。

常见问题

只写 model_reasoning_effort 可以吗

可以使用当前模型，但为了复现实验，最好同时记录模型标识。

项目配置为什么没有加载

先检查项目是否受信任，再检查文件路径、当前工作目录和更高优先级覆盖。

命令行覆盖会永久保存吗

不会。-c 或 --config 只针对当前运行，长期默认应写入相应配置文件。

xhigh 报错怎么办

当前模型可能不支持。切换到 high 并查阅该模型的最新说明。

总结

Codex CLI 的推理强度通过顶层键 model_reasoning_effort 设置。个人默认写入 ~/.codex/config.toml，项目覆盖写入受信任仓库的 .codex/config.toml，临时试验使用 -c 或 --config。排错时重点检查 TOML 字符串、配置层优先级、项目信任状态和模型支持范围；不要用历史 Issue 或 API 的字段定义替代当前 Codex 配置参考。