Codex 的 ReasoningEffort 枚举为什么同时包含 none、minimal、xhigh、max 和 ultra？

Codex 的 ReasoningEffort 枚举同时包含 none、minimal、low、medium、high、xhigh、max 和 ultra，是因为它描述的是 Codex 客户端与协议可能遇到的完整值域，而不是某一个模型在某一时刻支持的档位列表。不同模型、不同 provider 和不同 Codex 产品模式需要共享同一套协议，所以枚举必须覆盖历史差异、当前能力和产品级扩展。

其中，none 与 minimal 代表较低推理投入，但并非所有模型都同时支持；xhigh 和 max 是部分模型提供的更高模型级 effort；ultra 还可能承载 Codex 主动多代理编排语义。当前协议甚至允许未知的非空自定义值，以便未来模型增加档位时，旧客户端不必立即因枚举解析失败而中断。

枚举解决的是表示问题

客户端类型首先要回答：“收到一个 reasoning effort 值时，能否解析、保存、显示和再次发送？”这属于表示层。模型能力则回答：“当前模型是否接受并执行这个值？”这属于运行层。将两者分开，是理解 ReasoningEffort 设计的关键。

如果协议枚举只包含 low、medium 和 high，当后端推出支持 xhigh 或 max 的模型时，旧客户端会在读取模型目录或恢复会话时直接反序列化失败。扩大枚举并保留自定义值，可以让协议对模型演进更耐受。

但容错解析不能替代能力校验。客户端能够把字符串 max 转成枚举值，只证明它认识这个名称，并不证明当前模型支持 max。

各档位为什么会同时存在

none

none 表示不投入额外推理或使用最低的非推理路径，适合延迟敏感、分类、简单检索等任务。某些模型支持并可能默认使用 none，另一些推理模型明确不支持。Codex 需要能够连接两类模型，所以协议中必须保留它。

minimal

minimal 表示保留少量推理能力。它常见于需要工具调用或基本计划、但希望尽量降低延迟的场景。模型可能支持 none 而不支持 minimal，也可能支持 minimal 而不支持 none；两者不能合并成同一个通用最低档。

low、medium 与 high

这三档是跨多代推理模型最常见的核心集合。low 偏向效率，medium 在质量、成本和延迟之间平衡，high 为复杂任务提供更多推理空间。即便如此，具体默认档位和行为仍由模型决定。

xhigh

xhigh 是比 high 更高的模型级投入，常用于困难的代理式任务、长链推理或高要求评测。较早模型可能没有该档位。协议保留 xhigh，使 Codex 能在支持它的模型上展示和持久化选择。

max

max 是部分新模型正式支持的最高模型级 effort。它不是 xhigh 的通用别名，也不是所有模型必然拥有的下一档。模型能力表没有列出 max 时，客户端不应仅凭枚举存在就提交。

ultra

ultra 具有明显的 Codex 产品语义。当前 Codex 将它与更主动的多代理工作方式关联：系统可能拆分任务、并行调度多个代理并汇总结果。它影响的不只是单次模型推理预算，因此不应简单画成 max 上方的又一格 API effort。

为什么还需要 Custom 值

模型能力会持续演进。如果协议只接受编译时已知的枚举成员，服务端增加一个新值后，旧客户端可能无法加载整个模型目录。支持非空自定义字符串，可以让旧客户端保留未知值，并在适当位置显示或传递。

这种设计常被称为前向兼容。它解决的是“客户端不要因为未来值崩溃”，而不是“未来值自动适用于所有模型”。未知值仍需来自可信模型目录或明确配置，并由服务端最终校验。

自定义值也不能成为绕过输入验证的后门。空字符串应被拒绝，界面不应无条件把未知值列给所有模型，自动化系统也不应凭用户拼写就认定能力存在。

ReasoningEffort 与模型目录如何配合

Codex 的模型目录会为每个模型提供元数据，其中包括可支持的 reasoning efforts 和默认 effort。协议枚举定义候选表示，模型目录则为当前模型缩小集合。

假设协议认识以下值：

none, minimal, low, medium, high, xhigh, max, ultra

某个模型的目录可能只声明：

low, medium, high, xhigh

此时模型选择器应只把后面四项作为模型级有效选项。协议里存在 none、minimal、max 和 ultra，不改变该模型的能力。

默认值为什么也不能写死

不同模型可能默认 none、medium 或其他档位。Codex 若把 medium 永久写死为所有模型的默认值，会改变某些模型原本的延迟和质量特征，也可能提交不支持的参数。

更稳妥的顺序是：

1. 用户或会话显式选择了有效 effort，就使用该值。
2. 没有显式选择时，读取模型目录提供的默认值。
3. 模型切换后重新验证旧选择。
4. 旧选择无效时明确提示，并回到新模型默认值。

这也是为什么配置文件最好同时固定模型与 effort：

model = "<model-id>"
model_reasoning_effort = "medium"

模型切换时会发生什么

用户可能从支持 max 的模型切换到只支持 xhigh 的模型。如果 Codex 原样保留 max 并提交，新模型会拒绝请求；如果静默改成 medium，用户又可能误以为仍在最高档运行。

合理处理方式是重新读取新模型支持列表，判断旧值是否仍有效。无效时，可以选择新模型默认值或最接近的有效值，但必须在状态信息中显示实际选择。对于自动化任务，最好记录切换前后模型与 effort，避免性能变化无法追踪。

Ultra 更特殊。它可能是会话级编排选择，而不是适合作为未来所有线程的通用用户默认值。客户端在持久化配置时需要区分当前会话和新会话的作用域。

为什么 Ultra 放进同一个枚举

虽然 Ultra 与普通模型 effort 的语义不同，但它仍出现在用户选择推理投入的位置，并需要随线程设置保存、恢复和传递。使用同一协议类型可以简化任务创建、线程设置更新和客户端状态同步。

这是一种工程上的统一表示，不代表语义完全同质。类似地，一个“执行模式”字段可能同时包含普通串行选项和会触发分布式执行的高级选项；它们共享入口，但底层行为不同。

因此，读取 ReasoningEffort 枚举时，不能只按声明顺序推断大小关系。尤其不能断言：

none < minimal < low < medium < high < xhigh < max < ultra

前半段大致描述模型推理投入，Ultra 则可能跨越到代理编排维度。它的成本和效果不能仅用单次 reasoning token 比较。

配置文件接受值不等于运行成功

Codex 配置解析器可以接受某个非空 effort 值，启动时仍可能在模型能力校验或服务端请求阶段失败。例如：

model = "<does-not-support-max>"
model_reasoning_effort = "max"

TOML 语法完全正确，ReasoningEffort 也能解析 max，但目标模型可能返回 invalid value。排错时要区分三类错误：

• TOML 或字符串格式错误；
• 客户端模型目录认为组合无效；
• 服务端实际支持列表与客户端不一致。

如何判断一个值是否真正可用

1. 确认执行任务的 Codex 客户端版本。
2. 确认完整模型 ID、provider 和认证方式。
3. 查看该模型声明的 supported reasoning efforts。
4. 检查用户、项目、profile、命令行和会话级覆盖。
5. 运行一个低风险测试任务。
6. 查看状态或日志中的实际 effort。
7. 若服务端拒绝，以返回的允许列表为准并回退。

这里没有任何一步是“打开源码看到枚举成员，所以直接认定支持”。源码枚举只能作为协议解释证据。

API 参数与 Codex 配置不要混用

Codex 配置使用 model_reasoning_effort，Responses API 通常在 reasoning 对象中设置 effort。两者表达相近概念，但字段结构、允许值和产品行为不完全相同。Ultra 尤其可能依赖 Codex 客户端编排，不能脱离 Codex 直接搬进普通 API 请求。

编写兼容层时，应把 Codex 用户选择先解析为产品模式，再根据目标模型映射出有效模型级 effort。不要把枚举字符串不加判断地透传给所有 provider。

工具与 SDK 应怎样建模

一个健壮的工具可以保留开放的协议类型，同时提供动态能力校验：

effort = parse_non_empty_effort(user_value)
supported = catalog.supported_efforts(model_id)

if effort.is_model_level() and effort not in supported:
    raise UnsupportedEffort(model_id, effort, supported)

if effort == "ultra" and not codex_capabilities.proactive_multi_agent:
    raise UnsupportedProductMode("ultra")

这段逻辑表达两个判断域：模型级档位与产品级模式分别验证。实际实现可以不同，但不能只做字符串解析。

枚举演进带来的测试要求

ReasoningEffort 测试不应只覆盖已知值能否序列化，还应覆盖：

• 空字符串被拒绝；
• 未知非空值可以安全往返；
• 每个模型只展示自己支持的档位；
• 切换模型后旧 effort 会重新校验；
• 无效配置不会静默冒充有效；
• Ultra 的产品行为与模型 effort 转换一致；
• 旧会话包含未来值时不会导致客户端崩溃。

这些测试同时保护向后兼容和前向兼容。只测试枚举解析，会漏掉最关键的模型组合错误。

常见误读

枚举顺序就是强度顺序

标准模型档位可以大致按投入排序，但 Ultra 可能引入编排语义，Custom 也没有天然排序。必须读取元数据而非依赖枚举位置。

none 和 minimal 可以合并

它们可能代表不同的模型行为，并且模型支持集合不同。合并会让兼容层发送错误参数。

max 永远无效

这在部分新模型上已经不成立。max 是否有效是模型特定事实，不是全局真假命题。

ultra 是标准 API 档位

Ultra 主要是 Codex 高级模式，可能与主动多代理协作绑定。不能仅凭协议枚举将其推广为通用 API 值。

Custom 意味着任意值都可用

Custom 只保证客户端可保存未来值，服务端仍会验证。它是兼容机制，不是绕过能力控制。

结论

Codex 的 ReasoningEffort 枚举之所以同时包含 none、minimal、xhigh、max 和 ultra，是因为协议需要覆盖多代模型、不同 provider、未来扩展和 Codex 自身的高级编排模式。枚举回答“客户端能否表达”，模型目录和服务端回答“当前模型能否执行”。none、minimal、xhigh 与 max 都可能是模型特定档位；Ultra 还可能包含主动多代理语义；Custom 则保证前向兼容。使用时应始终按精确模型读取支持列表，并通过实际会话状态确认生效，不能把枚举成员当作全局能力承诺。