Codex CLI 如何通过配置文件管理 Reasoning Effort？

Codex CLI 可以通过用户配置、项目配置和 profile 文件分层管理 Reasoning Effort。个人默认写在 ~/.codex/config.toml，项目覆盖写在受信任仓库的 .codex/config.toml，可重复工作流使用 ~/.codex/<profile-name>.config.toml，一次性运行再用 -c 或 --config 覆盖。核心键是顶层的 model_reasoning_effort。

最小可用配置

用户级默认配置：

# ~/.codex/config.toml
model = "当前实际可用的模型标识"
model_reasoning_effort = "medium"

模型标识和推理档位应该一起记录，因为不同模型支持的 Reasoning Effort 范围可能不同。

常见推理档位

当前 Codex 配置参考列出的常见值包括：

• minimal
• low
• medium
• high
• xhigh

xhigh 是模型相关能力。默认值也由模型和 preset 决定，需要可重复行为时应显式配置。

配置文件的四个层次

层次	位置	用途
用户配置	~/.codex/config.toml	个人通用默认
profile	~/.codex/name.config.toml	可重复工作流覆盖
项目配置	.codex/config.toml	仓库或子目录要求
CLI 覆盖	-c key=value	一次性试验

配置优先级

当前官方顺序从高到低是：

1. CLI 标志和 --config 覆盖。
2. 项目配置，从项目根到当前目录，最近的层级优先。
3. 通过 --profile 选择的 profile 文件。
4. 用户配置。
5. 云端管理默认。
6. 系统配置。
7. 内置默认。

理解优先级是管理配置的关键。文件内容正确但运行值不同，通常是更高层覆盖，而不是 Codex 忽略了设置。

用户配置适合放什么

用户文件应保存适用于多数项目的保守默认：

model = "当前已验证的模型标识"
model_reasoning_effort = "medium"
model_reasoning_summary = "auto"

不要把某个特殊项目所需的高档位设为全局默认，除非团队评测证明所有日常任务都值得承担额外延迟和用量。

项目配置适合放什么

项目文件适合描述仓库自身需要的差异。例如安全敏感项目：

# .codex/config.toml
model_reasoning_effort = "high"

项目配置可以提交到版本控制，让团队共享默认行为。不过它只会在项目受信任时加载。

项目配置的信任边界

Codex 不会无条件执行仓库内的配置。未信任项目会跳过项目范围的 .codex 层，包括项目配置、Hooks 和规则。

这防止陌生仓库静默修改本机 Agent 行为。排查项目配置不生效时，应先确认信任状态。

子目录配置如何合并

Codex 从项目根目录走到当前工作目录，加载沿途找到的 .codex/config.toml。多个文件定义同一键时，离当前目录最近的文件优先。

单体仓库可以借此为不同子项目设置档位，但层级过多会增加认知成本。建议在根目录文档中列出所有覆盖。

当前 profile 的正确结构

新版本 profile 使用独立文件，而不是把所有 profile 嵌套在用户配置中。例如：

# ~/.codex/deep-review.config.toml
model = "当前已验证的模型标识"
model_reasoning_effort = "high"
model_reasoning_summary = "detailed"

启动方式：

codex --profile deep-review

profile 文件包含顶层键，不要再写成 [profiles.deep-review] 表格。

旧 profile 写法为什么需要迁移

较早资料可能建议在 ~/.codex/config.toml 中使用：

[profiles.deep-review]
model_reasoning_effort = "high"

当前 Codex 已改为独立的 ~/.codex/deep-review.config.toml 文件。阅读旧 Wiki 或博客时，应对照当前官方 Advanced Configuration。

一次性覆盖用于试验

在写入长期配置前，可以临时测试：

codex --config 'model_reasoning_effort="high"'

命令行值按 TOML 解析。字符串应正确引用，且本次运行结束后不会写回配置文件。

用户、profile、项目如何组合

推荐结构是：

1. 用户文件保存通用模型和 medium 基线。
2. profile 只保存快速、深度审查等工作流差异。
3. 项目文件只保存仓库特有要求。
4. CLI 覆盖只用于一次性实验。

每层只定义必要差异，可以减少重复和配置漂移。

推理摘要要单独管理

model_reasoning_summary 控制摘要形式：

model_reasoning_summary = "concise"

候选值为 auto、concise、detailed 和 none。它控制可见摘要，不等同于推理强度。

原始推理显示要谨慎

show_raw_agent_reasoning 只有在活动模型实际提供相关内容时才有意义。它是显示选项，不会提高模型推理能力，也不应被当作可靠审计日志。

正常生产工作更应关注工具证据、测试结果和最终决策摘要。

输出详细度也不是推理强度

model_verbosity 控制最终回答的详细程度：

model_verbosity = "low"

可选值为 low、medium 和 high。高推理配低 verbosity 可以得到深入但简洁的结果。

日常开发 profile

# ~/.codex/daily.config.toml
model = "当前已验证的通用模型"
model_reasoning_effort = "medium"
model_reasoning_summary = "auto"
model_verbosity = "medium"

适合普通功能、调试和测试工作。

快速处理 profile

# ~/.codex/quick.config.toml
model = "当前已验证的快速模型"
model_reasoning_effort = "low"
model_reasoning_summary = "none"
model_verbosity = "low"

适合结构化提取、代码搜索和边界清楚的机械任务。

深度审查 profile

# ~/.codex/deep-review.config.toml
model = "当前已验证的强模型"
model_reasoning_effort = "high"
model_reasoning_summary = "detailed"
model_verbosity = "high"

适合复杂架构、安全和根因分析。只有模型支持并经评测时才考虑 xhigh。

为何不建议按开发、测试、生产固定档位

环境名称不能代表任务难度。生产中的字段提取可能很简单，开发阶段的并发故障可能极难。

配置应按工作流复杂度和风险管理，而不是机械规定“开发 high、测试 medium、生产 high”。

配置文件要记录模型版本

Reasoning Effort 支持范围与模型绑定。配置评审应记录：

• 精确模型标识。
• Codex CLI 版本。
• 支持的推理档位。
• 评测任务和日期。
• 选择当前默认值的依据。

如何审计配置漂移

1. 列出用户、profile、项目和 CLI 四类来源。
2. 确认每层实际定义的键。
3. 找出重复或相互冲突的设置。
4. 检查项目子目录是否有隐藏覆盖。
5. 确认旧 profile 已迁移为独立文件。
6. 用 /status 核验当前会话。
7. 删除不再需要的重复键。

如何验证配置生效

在交互式会话中使用 /status 检查当前模型和会话状态。还可以用 /statusline 把 model+reasoning 加入底部状态栏。

回答更长或响应更慢都不是可靠证据，因为输出详细度、网络和工具执行也会影响体验。

配置解析失败怎么查

• 确认键名拼写正确。
• 确认字符串使用 TOML 引号。
• 确认 model_reasoning_effort 位于顶层。
• 检查表格声明后是否误放顶层键。
• 确认数值和布尔值没有写成错误类型。
• 逐步移除最近修改以定位错误。

档位被模型拒绝怎么查

先检查精确模型的当前文档。Codex 配置参考给出客户端候选值，但最终模型可能只支持其中一部分。

尤其是 xhigh，不能因为另一个模型支持就直接复用。

第三方提供商如何处理

自定义模型提供商需要正确实现 Responses 协议和推理参数。若提供商忽略或转换字段，Codex 本地配置正确也不代表远端实际采用。

应通过提供商文档、请求日志和代表性评测验证，不要只看配置文件。

项目配置可以提交哪些内容

可以提交与仓库协作直接相关的默认值，但应避免：

• 个人绝对路径。
• 密钥和访问令牌。
• 仅对单个开发者有效的模型。
• 未经评测的高成本默认。
• 过期 profile 选择器。

变更配置的评审清单

1. 变更作用在哪个层级。
2. 是否会影响所有项目。
3. 目标模型是否支持该档位。
4. 有没有更高层覆盖。
5. 是否需要迁移旧写法。
6. 评测是否证明收益。
7. 如何回滚到旧配置。

配置文件不能替代任务级调档

配置文件适合默认行为，单个会话仍可能包含不同复杂度阶段。交互中可以使用 /reasoning 调整当前对话的推理强度。

长期默认保持平衡，困难阶段临时升档，通常比全局固定高档更稳健。

配置与安全权限相互独立

Reasoning Effort 不控制沙箱、审批和网络。即使使用高档位，也必须通过独立权限设置限制副作用。

常见错误一：照搬旧 Wiki

旧资料可能只有 low、medium、high，也可能使用已经迁移的嵌套 profile。应以当前官方配置参考为准。

常见错误二：所有配置写进一个文件

把个人默认、项目要求和特殊工作流混在用户文件里，会导致其他项目意外继承。应按作用范围分层。

常见错误三：只看文件不看当前状态

当前会话可能受到命令行或项目配置覆盖。文件内容只是输入之一，最终运行状态才是有效证据。

常见错误四：把摘要详细度当推理质量

detailed 只让摘要更详细，不会自动提高推理投入。推理强度由 model_reasoning_effort 控制。

常见问题

个人默认应该设哪个档位

从当前模型推荐默认或 medium 建立基线，再按实际评测调整。

项目配置和 profile 谁优先

当前官方优先级中，项目配置高于 profile，CLI 覆盖又高于项目配置。

修改配置后需要重启吗

重新启动会话最容易确保文件被重新读取。当前会话临时调整可使用 /reasoning。

能把 xhigh 写进所有 profile 吗

不建议。模型可能不支持，而且简单任务通常无法获得与额外延迟相匹配的收益。

总结

通过配置文件管理 Codex Reasoning Effort，应把个人默认放在 ~/.codex/config.toml，把仓库差异放在受信任项目的 .codex/config.toml，把重复工作流放在独立 profile 文件，并用 CLI 覆盖完成一次性测试。管理重点是作用范围、优先级、模型兼容性和版本迁移；旧 Wiki 中的档位和嵌套 profile 写法不能替代当前官方文档。