Codex 的 model_reasoning_effort 有哪些可用级别？

Codex 的 model_reasoning_effort 常用可配置级别是 minimal、low、medium、high 和 xhigh。如果不设置，Codex 会采用当前模型自己的默认值。需要特别注意：可用档位由模型决定，xhigh 并非所有模型都支持；API 文档中出现的 none、max 等值，也不代表当前 Codex 模型配置一定接受。

配置项写在哪里

全局配置通常写入 Codex 配置文件：

# Codex config.toml
model_reasoning_effort = "medium"

设置后，它会作用于所选模型。不要只修改档位而忽略 model，因为不同模型对 Reasoning Effort 的支持和默认行为可能不同。

五个常见级别

级别	定位	典型任务
minimal	极少推理，优先响应速度	固定格式、简单改名、明确的单步操作
low	高效率的轻量推理	常规编码、搜索、配置修改、简单调试
medium	质量、可靠性与延迟的平衡点	大多数多文件开发任务
high	更充分的复杂推理	跨模块调试、架构分析、安全审查
xhigh	最高一档的深度推理请求	最困难的长任务和能力上限评测

这些名称描述的是相对投入，不是固定 Token 数，也不是质量百分比。

unset 是什么意思

如果配置文件不包含 model_reasoning_effort，Codex 会让模型使用自己的默认值。默认值可能随模型家族和产品版本变化。

如果团队需要可重复评测，应显式设置档位并记录模型版本。若只是日常交互，保持未设置可以获得产品当前推荐默认。

minimal 适合什么

minimal 适合几乎不需要权衡的任务，例如：

• 按既定模板生成短文本。
• 修改已知配置键。
• 执行明确命令并报告退出码。
• 对结构化输入做简单转换。
• 机械重命名且有完整测试保护。

任务一旦涉及多步工具选择、未知代码或隐含约束，minimal 可能过早给出答案。

low 适合什么

low 仍保留一定的规划与工具推理，适合高频、边界明确的开发任务。它通常比 minimal 更适合真实编码，因为读取文件、选择测试和理解错误信息都需要多步判断。

如果 low 在代表性评测中与 medium 质量接近，可以用它降低延迟和用量。

medium 为什么常作为起点

medium 是合理的通用基线。它适合复杂度不确定的交互式工作，也方便向上下两个方向比较。

典型任务包括普通功能实现、多文件 Bug 修复、测试补全和中等规模重构。没有评测数据时，从这里开始比直接使用最高档更稳妥。

high 适合什么

high 用于推理深度确实构成瓶颈的任务，例如并发错误、跨服务根因、数据库一致性、权限模型或大型迁移。

升到 high 前，应先确认模型获得了正确日志、文档和工具。如果信息缺失，更高推理档位只会更久地分析不完整证据。

xhigh 有哪些限制

xhigh 是模型相关档位。某些模型可能拒绝该值，某些模型即使接受，也会根据任务自适应使用推理量。

它适合：

• 最困难的异步 Agent 任务。
• 需要分析大量相互依赖约束的问题。
• 用于测试模型能力边界的评测。
• 失败成本高且额外延迟可以接受的任务。

不要把 xhigh 设置为所有会话的默认值。

为什么没有统一的固定默认值

模型设计会变化。某个模型可能以 medium 为默认，另一个模型可能支持更少或更多级别。Codex 配置只向模型提出推理投入要求，最终行为还受模型能力和服务端实现影响。

因此，文档或博客中关于默认值的结论必须带上模型和版本，不能永久套用。

API 的 effort 与 Codex 配置有什么关系

Responses API 使用 reasoning.effort 控制推理投入，而 Codex 配置使用 model_reasoning_effort。概念相同，但可接受值和默认值仍由具体模型、客户端和接口决定。

API 文档列出的所有潜在值不能直接复制进 config.toml。应以当前 Codex 配置参考和所选模型能力为准。

none 为什么要谨慎

某些 API 模型支持 none，用于完全不需要推理或多段工具调用的低延迟任务；另一些模型可能明确不支持并返回错误。Codex 的 model_reasoning_effort 常见值集合也不一定包含它。

若想降低成本，先测试 low 或 minimal，不要假设 none 可用。

配置错误会出现什么

常见情况包括：

• 当前模型不支持该档位，请求被拒绝。
• 第三方模型提供商忽略配置。
• 切换模型后，旧档位不再适用。
• 配置文件语法或层级错误导致设置未生效。
• 计划模式或运行时覆盖了全局配置。

遇到问题时，应检查当前模型、有效配置和客户端版本，而不是反复修改提示。

计划阶段与执行阶段可以分开吗

支持独立计划档位的版本可以通过计划模式配置，让规划阶段使用更高推理投入，执行阶段保持较低档位。这适合“先想清楚、再按步骤执行”的任务。

不过，复杂执行也可能需要持续判断。不能因为已经生成计划，就假设后续每一步都只需要最低档。

如何确认设置生效

1. 确认当前 Codex 读取的是预期配置文件。
2. 记录当前模型和客户端版本。
3. 显式设置一个受支持档位。
4. 运行固定的代表性任务。
5. 检查日志或用量记录中的模型与推理配置。
6. 比较质量、Token 和延迟，而不是只看回答长度。

输出更长不等于推理更多，输出更短也不代表配置未生效。

如何选择默认级别

工作模式	建议起点
追求极低延迟的固定任务	minimal
大量常规编码和工具执行	low
通用交互开发	medium
复杂诊断和架构任务	high
最难的异步任务	xhigh，前提是模型支持

高档位不是安全控制

Reasoning Effort 不会限制文件系统、网络或命令权限。即使使用 xhigh，Agent 仍可能因提示注入或错误上下文执行危险操作。

沙箱、审批、最小权限和真实测试必须独立配置，不能用“模型会想得更仔细”替代。

用评测而不是感觉调档

为常用任务建立小型评测集，至少记录：

• 首次任务成功率。
• 测试和审查结果。
• 推理与总 Token。
• 端到端完成时间。
• 人工纠正次数。
• 越界修改和错误工具调用。

只有更高档位产生可测量质量收益时，才应承担额外成本。

配置示例

通用开发基线：

model = "当前团队批准的模型"
model_reasoning_effort = "medium"

低延迟执行环境：

model = "当前团队批准的模型"
model_reasoning_effort = "low"

复杂任务专用配置：

model = "确认支持高推理档位的模型"
model_reasoning_effort = "high"

不要在未验证模型支持时直接使用 xhigh。

常见问题

默认值到底是什么

未设置时由模型自身决定。若需要稳定可重复的行为，应显式配置并记录模型版本。

所有模型都支持 xhigh 吗

不支持。它是模型相关能力，应查当前模型文档并实际验证。

minimal 与 none 相同吗

不同。minimal 是极低推理投入，none 表示不使用推理；支持情况也不同。

切换模型后需要改配置吗

可能需要。先确认新模型支持的值，再重新运行代表性评测。

总结

Codex 的 model_reasoning_effort 常见级别为 minimal、low、medium、high 和 xhigh，未设置时采用模型默认。档位支持并不统一，尤其是 xhigh 必须按模型核验。日常工作可从 medium 建立基线，再用评测将简单任务下调、复杂任务上调；不要把 API 中的所有候选值直接当成 Codex 配置的通用答案。