Codex 的 Reasoning Effort 不应固定设置为最高。对于支持 low、medium、high 和 xhigh 的模型，推荐从 medium 建立质量基线，再用真实任务评测决定向下或向上调整：常规执行型编码优先测试 low，复杂跨模块推理使用 high，只有最困难、可异步运行且质量收益可测量的任务才考虑 xhigh。

Reasoning Effort 控制什么

reasoning.effort 用于引导模型在任务上投入多少推理。较低档位通常优先速度与 Token 效率，较高档位允许模型更完整地分析复杂问题，但会增加延迟和成本。

它不是传统意义上的“准确率开关”。模型还会根据任务复杂度自适应推理，同一档位下，简单任务可能使用较少推理，困难任务则投入更多。

四个档位如何理解

档位	适合场景	主要权衡
low	常规编码、搜索、数据处理、清晰的工具任务	速度与成本优先，复杂推理余量较少
medium	大多数开发任务和默认基线	质量、可靠性、延迟与成本平衡
high	复杂调试、架构权衡、跨模块 Agent 任务	推理更充分，但等待和消耗更高
xhigh	最困难的异步任务、研究和能力上限评测	最大推理预算，成本与延迟最高

具体可用值依赖模型，不能假设所有模型都支持同一组档位。

为什么从 medium 开始

OpenAI 对 GPT-5.5 的官方建议是以 medium 作为质量、可靠性和性能的平衡起点。这一档位适合建立基线，因为它既不会过早牺牲复杂任务质量，也不会直接承担最高档位的额外成本。

建立基线后，按任务族测试调整。不要把旧模型上的档位原样复制到新模型；模型家族变化后，应重新评测提示、工具和 Reasoning Effort。

什么时候选择 low

low 适合目标清楚、完成条件明确、工具链稳定的任务，例如：

• 在已知文件中做小范围机械修改。
• 根据明确错误信息定位常见问题。
• 运行测试、格式化或静态检查并总结结果。
• 生成模板化代码、文档或迁移草稿。
• 执行搜索、分类和结构化数据整理。

官方指出，许多工作负载在 low 下就能取得良好表现。若任务仍需要工具、计划或多步决策，优先尝试 low，而不是直接关闭推理。

low 不适合哪些信号

• 问题跨越多个模块，因果链尚不清楚。
• 要求在多种设计之间做长期权衡。
• 测试失败与代码位置没有直接对应关系。
• 存在大量隐含约束或兼容性要求。
• 错误修改可能产生高额外部成本。

如果 low 经常遗漏约束、过早停止或需要用户反复纠正，应先检查提示和工具结果，再考虑升档。

什么时候保留 medium

medium 是日常开发的稳妥默认值，特别适合任务复杂度不确定的交互式会话。典型场景包括：

• 实现包含若干文件的普通功能。
• 修复需要阅读调用链的 Bug。
• 编写并运行针对性测试。
• 评审中等规模的代码差异。
• 需要几轮工具调用但风险可控的任务。

如果团队还没有完整评测集，使用 medium 比凭感觉把所有任务设为 high 更容易建立可比较数据。

什么时候升级到 high

high 适用于困难推理能明显改善结果，且额外延迟可以接受的任务：

• 跨服务故障诊断与根因分析。
• 涉及并发、缓存、一致性或事务的复杂 Bug。
• 大型重构的依赖分析和迁移计划。
• 安全审查、威胁建模和失败模式分析。
• 需要多轮搜索、工具调用和证据整合的 Agent 工作。

升级前应确认瓶颈确实是推理深度，而不是缺少日志、测试、文档或工具权限。

xhigh 应该保留给什么

xhigh 适合最困难、可异步执行的 Agent 任务，或用来测试模型智能上限的评测。它不适合默认交互，因为用户等待时间和成本可能显著增加。

可以考虑的场景包括：

• 复杂仓库的长时间自主调查。
• 高难度算法或形式化推理。
• 多系统迁移的全面风险分析。
• 需要穷举多条假设并验证的根因定位。
• 离线基准中比较模型能力上限。

只有当评测证明 xhigh 相比 high 带来可衡量质量提升，才值得投入生产。

更高档位为什么可能变差

官方特别提醒，更高 Reasoning Effort 不自动意味着更高质量。如果提示存在冲突、停止条件不明确或工具权限过于开放，模型可能过度分析、进行不必要搜索，甚至偏离任务目标。

常见表现包括：

• 对简单问题提出过度复杂的方案。
• 修改超出用户要求的文件。
• 在已经获得证据后继续搜索。
• 反复重做同一验证。
• 生成更长但不更准确的回答。

这些问题应先通过清晰目标、允许副作用、完成证据和输出格式来修复。

不要用档位弥补糟糕的提示

高质量任务说明至少应包含：

1. 期望结果，而不只是操作步骤。
2. 明确完成条件和验证证据。
3. 允许修改的范围。
4. 禁止的副作用。
5. 可使用的工具与数据。
6. 最终输出格式。

如果任务本身模糊，把档位从 medium 提到 xhigh 只会让模型更久地探索模糊空间。

工具任务如何选档

工具数量不是唯一标准。关键是工具选择是否存在歧义，以及每次调用是否依赖前一步结果。

工具工作流	建议起点
固定命令、固定路径、单次执行	low
搜索后选择文件并修改	medium
多轮诊断、多个假设与回归验证	high
长时间异步研究、跨系统证据整合	xhigh

即使使用高档位，也要限制最大工具调用、时间和费用。

交互式与异步任务应分开

交互式任务重视响应速度，通常以 low 或 medium 为主。用户可以快速纠正方向，没必要每轮都承担高推理开销。

异步任务允许 Agent 长时间工作，更适合 high 或 xhigh，但必须设置检查点、超时、预算和最终证据。异步并不等于无限运行。

如何建立评测集

为每类真实任务收集固定样本，覆盖简单、中等和困难情况。每个样本要有可判定的正确结果，而不是只看回答是否“像专家”。

编码任务可记录：

• 测试通过率和隐藏测试结果。
• 人工审查发现的问题数。
• 修改文件数与越界修改。
• 任务总耗时和首个有效结果时间。
• 输入、输出及推理 Token。
• 工具调用次数和失败恢复情况。

推荐的调参流程

1. 以 medium 跑完整代表性评测，建立基线。
2. 对高频简单任务改用 low，比较质量是否持平。
3. 只对低质量的困难任务测试 high。
4. 在最困难的少数样本上比较 high 与 xhigh。
5. 用中位数和失败分布判断，不挑选单次最佳结果。
6. 模型、提示或工具发生重要变化后重新评测。

可以动态选择档位吗

可以在应用层按任务路由。例如根据文件数量、风险等级、是否需要跨系统操作和历史失败次数选择档位。路由规则应简单、可观察，并允许人工覆盖。

不要让模型仅凭自己的判断无限升档。升级应有最大值和预算，并记录触发原因。

失败后是否应该自动升档

可以作为有限重试策略，但必须先分类失败：

• 网络、权限和缺失文件问题不会因升档解决。
• 格式不符合要求应修正 Schema 或提示。
• 推理遗漏、复杂因果分析才可能从升档获益。
• 安全拒绝不应通过更高档位绕过。

建议最多升档一次，并保持相同输入证据，便于比较。

API 中如何设置

在 Responses API 中，通过 reasoning.effort 指定档位：

{
  "model": "支持该档位的模型",
  "reasoning": {
    "effort": "medium"
  },
  "input": "分析失败原因并给出可验证修复"
}

模型支持值和默认值会变化，应在部署时校验模型文档。不要依赖一个全局默认适配所有模型。

常见问题

xhigh 是否一定生成更好的代码

不一定。它提供更高推理预算，但提示冲突、上下文错误和工具问题仍可能导致质量下降。

low 是否只适合聊天

不是。官方将执行型编码、搜索、规划和多步决策列为 low 的常见适用场景。

不知道任务难度时选什么

从 medium 开始。积累评测数据后，再把稳定简单任务下调，把少数困难任务上调。

Reasoning Effort 与输出长度相同吗

不同。推理投入与最终回答的详细程度是两个维度，应分别控制。

总结

Reasoning Effort 的正确策略不是“越高越好”，而是以 medium 建立基线，用 low 优化高频常规任务，用 high 处理复杂 Agent 推理，并把 xhigh 留给最困难的异步任务和上限评测。最终选择必须由真实任务的正确率、返工、延迟、Token 和工具行为共同决定；在升档前，先修正提示、上下文和工具边界。