Codex 工具接口出现 max 和 ultra 时，是否代表当前模型实际支持？
Codex 工具接口或类型定义中出现 max 和 ultra，不代表当前模型一定支持这两个值。Schema 首先描述的是客户端、协议或工具能够表达什么；模型实际接受什么，则由当前模型的能力元数据、接入后端和产品编排规则共同决定。只有当请求通过能力校验并被服务端接受，才能确认某个 effort 在当前环境中真正可用。
这类误解通常来自把“类型可以序列化”当成“服务端保证支持”。Codex 为了兼容多模型、未来模型和不同产品模式，可能在协议中保留比单个模型更宽的取值范围。一个模型只支持 low、medium、high 和 xhigh，并不妨碍客户端协议同时认识 max、ultra，甚至保留自定义字符串。
为什么工具 Schema 会比模型能力更宽
Codex 客户端需要连接多种模型和 provider。若协议把 reasoning effort 写死为某个旧模型的三档枚举，新模型增加档位时就必须同步升级所有客户端和中间服务。更宽松的协议可以减少这种耦合：客户端负责传递或展示值，模型目录与服务端负责判断当前目标是否接受。
因此，Schema 可能承担以下职责：
- 描述 Codex 当前已知的所有 effort 名称；
- 允许模型目录返回未来扩展值；
- 支持 Codex 产品自身的高级编排模式；
- 让不同 provider 使用各自声明的能力；
- 在任务创建、恢复和切换模型时保存用户选择。
这些职责都不要求每个模型支持 Schema 中的每个候选值。
四种“支持”必须分开
语法支持
配置解析器或协议类型能读取并保存某个字符串。例如客户端可以解析：
model_reasoning_effort = "max"这只能证明配置语法有效，不能证明模型会执行 max。
界面支持
模型选择器或工具调用参数中显示 max、ultra，说明产品允许用户表达该选择。界面数据可能来自通用 Schema、缓存的模型目录或实验功能，因此仍不能单独作为后端能力证明。
模型声明支持
模型目录或官方模型页明确列出 supported reasoning efforts，这是比 Schema 更强的证据。选择 effort 时应优先使用与精确模型 ID 对应的列表，而不是另一个同系列模型的列表。
运行时支持
请求被目标后端接受，并且状态或响应能确认实际值没有被降级，才是最终证据。模型声明与运行结果通常一致，但客户端、远程主机或后端发布不同步时仍可能出现差异。
max 为什么有时能用、有时不能用
max 已经是部分新模型正式支持的模型级 reasoning effort。这些模型的能力表会明确列出 max。另一些模型仍只支持到 xhigh，或拥有不同的最低档位。不能因为某个新模型支持 max，就把它写成所有 Codex 模型的全局默认。
例如，下面的配置是否有效，取决于 <model-id> 的能力：
model = "<model-id>"
model_reasoning_effort = "max"如果后端返回无效值，并列出 none、minimal、low、medium、high、xhigh，那么当前链路就没有接受 max。正确处理是回退到支持列表中的最高合适值，而不是继续用同一个参数重试。
ultra 为什么更不能按普通枚举理解
ultra 在当前 Codex 设计中不仅表示模型推理强度，还与更主动的多代理编排相关。启用后，Codex 可能将任务拆成多个并行子任务，再汇总结果。它影响的是整个代理运行方式，而不只是单次 Responses 请求中的 reasoning effort。
因此，客户端可能在产品层接受 ultra，却在发送到底层模型时使用该模型支持的另一个 effort，并额外启用编排行为。具体映射属于 Codex 版本和 provider 的实现细节。不能看到工具参数允许 ultra，就断言任意 OpenAI API 请求都能发送 reasoning.effort=ultra。
同样，也不能把 Ultra 当成 max 的固定别名。如果客户端升级、模型能力变化或 provider 使用不同转换规则，两者的关系可能改变。自动化代码应依赖能力元数据和明确文档，不应硬编码未经验证的映射。
能力发现应该如何工作
可靠的客户端通常采用能力协商，而不是维护一张永不过期的静态表：
- 确定精确模型 ID 和 provider。
- 从模型目录读取该模型声明的 supported reasoning efforts。
- 让界面只展示或优先展示支持的档位。
- 提交请求时再次验证所选值。
- 服务端拒绝时解析错误中的允许列表。
- 向用户明确提示并选择安全回退，而不是静默伪装成功。
这里的关键是模型能力，而不是工具 Schema。Schema 解决“字段能否传递”，能力协商解决“这个目标能否执行”。
如何手动验证当前 Codex 环境
确认客户端版本
桌面应用、全局 Codex CLI 和远程主机上的 CLI 可能不是同一版本。先记录真正执行任务的版本。只查看本机安装包，而任务实际运行在远程主机上，会得出错误结论。
确认模型与 provider
记录完整模型 ID、provider 和认证方式。同名模型在官方服务、组织网关和兼容 provider 中可能暴露不同的 effort 集合。
查看模型选择器
Codex 模型选择器通常基于模型目录显示可用 effort。若当前模型只列到 xhigh，就不要因为工具 schema 还有 max 和 ultra 而强行选择。
检查有效配置
有效值可能来自用户配置、项目配置、profile、命令行覆盖或会话设置。应检查所有层级，避免以为正在测试 max，实际却被更高优先级配置覆盖成 medium。
运行最小测试
选择一个低风险、容易验收的任务，用临时配置测试：
codex --config 'model_reasoning_effort="max"'执行后查看会话状态和错误响应。成功启动并不一定等于值已生效；如果客户端会回退，还应确认记录的实际 effort。
收到 invalid value 时怎么办
服务端的无效值错误通常会列出当前允许的值。处理顺序如下：
- 保存完整错误信息，不只截取“请求失败”。
- 确认错误参数确实是 reasoning effort。
- 将配置改为允许列表中的档位，例如 xhigh 或 high。
- 重新启动会话，排除旧会话设置残留。
- 检查模型目录与后端是否发布不同步。
- 若界面仍展示无效选项，再提交包含版本信息的客户端问题。
不要在失败后自动无限重试，也不要静默改成 medium 却仍向用户显示 max。前者浪费额度，后者破坏可观测性。
怎样设计安全回退
自动化系统可以为每个模型保存一个优先列表。例如希望使用最高可用模型推理时，可以按 max、xhigh、high 的顺序与模型声明求交集，然后选择第一个匹配值。注意，Ultra 不应简单加入这条模型 effort 回退链，因为它可能代表不同的产品编排语义。
preferred_model_efforts = ["max", "xhigh", "high"]
supported = load_model_supported_efforts(model_id)
selected = first_value_present(preferred_model_efforts, supported)如果没有交集，应停止并提示，而不是发送未知值。对于 Ultra，应另设产品能力开关，例如客户端是否支持主动多代理、当前任务是否允许并发以及额度是否足够。
为什么不应只检查本地类型定义
开源客户端中的枚举能告诉你 Codex 能识别哪些名称，也能揭示产品如何建模这些概念，但它不能替代运行时模型目录。类型定义通常覆盖多个版本和未来扩展；服务器可能按账户、区域或模型逐步开放。
更进一步，某些协议会允许非空自定义字符串，以便未来模型无需立即更新客户端。若把“能反序列化任意字符串”理解成“任意字符串都是有效 effort”，显然会得到错误结论。解析成功只是第一道门。
工具作者应该怎么暴露参数
如果你在封装 Codex 任务创建或线程设置接口，参数说明不应写成“可选 max、ultra，所以所有模型都支持”。更准确的描述是：
- 该字段接受 Codex 协议可表达的 effort 值；
- 实际可用值取决于所选模型和运行环境；
- Ultra 可能启用 Codex 特有的编排行为；
- 调用前应查询模型支持列表；
- 服务端错误必须原样反馈给调用方。
工具还可以把模型和 effort 绑定成一个经过校验的选择，而不是让用户先选任意模型、再从全局枚举里选任意 effort。这样能在提交前消除大量无效组合。
测试矩阵应该覆盖什么
要验证工具接口是否正确处理 max 和 ultra，至少覆盖以下场景：
- 支持 max 的模型选择 max，运行成功且状态一致；
- 不支持 max 的模型选择 max，界面阻止或服务端错误清晰；
- 模型从支持 max 切换为不支持 max，旧值被明确处理；
- Ultra 可用时，产品编排行为按预期启用；
- Ultra 不可用时，不会被误发送为普通模型参数；
- 远程客户端与桌面版本不一致时，能力列表不会被错误缓存；
- 恢复旧会话时，已失效的 effort 会提示用户重新选择。
测试不能只断言 JSON 序列化结果。真正重要的是选项过滤、请求响应、实际会话状态和资源行为。
常见误区
Schema 是服务端合同的全部
工具 Schema 只是合同的一部分。模型特定约束通常存在于能力元数据或服务端校验中。
新模型支持，旧模型也应该支持
Reasoning Effort 是模型能力，不保证系列内向后传播。每个模型都要单独核验。
Ultra 就是比 max 更高
Ultra 可能包含多代理编排语义，不能只按一维推理刻度排序。
请求没有报错就是完全生效
客户端可能回退、转换或使用默认值。还需查看有效会话状态和运行记录。
写死当前枚举最稳定
静态枚举会随模型演进过期。应保留严格的非空与格式校验，同时从模型目录获取当前支持值。
结论
Codex 工具接口出现 max 和 ultra，只能证明协议或产品能够表达这些选择，不能证明当前模型实际支持。max 已是部分模型的真实 reasoning effort，但必须出现在该模型的支持列表中；Ultra 主要承载 Codex 的高级编排语义，不能直接当作通用 API effort。可靠流程是确认客户端、模型和 provider，读取模型能力，检查有效配置，运行最小验证，并以服务端结果和实际会话状态为最终证据。工具 Schema 是起点，不是能力证明。
