Codex 的 Max 与 Ultra 是否属于通用 Reasoning Effort 等级？
Max 与 Ultra 都不能被视为所有 Codex 模型通用的 Reasoning Effort 等级。max 已经是部分新模型正式支持的模型级推理强度，但许多模型仍只支持到 xhigh；ultra 则主要是 Codex 产品和客户端中的高级任务模式，除了推理投入，还可能改变代理编排行为。判断一个值能否使用，必须同时检查 Codex 客户端、当前模型和实际后端，而不能只看某个界面曾经出现过该选项。
这一区分很重要。把 ultra 原样作为通用 API 的 reasoning.effort 发送，后端可能拒绝；把 max 写入不支持它的旧模型配置，也会收到无效参数错误。另一方面，因为某篇旧文档只列出 low、medium、high 和 xhigh，就断言 max 永远不存在，同样已经不准确。
先区分三个层级
模型级 Reasoning Effort
这是模型接口真正接受的推理投入值。常见值包括 none、minimal、low、medium、high、xhigh 和部分模型支持的 max。具体集合由模型决定，不存在一张适用于所有模型和所有时间的固定列表。
Codex 客户端配置
Codex CLI 使用 model_reasoning_effort 保存当前选择：
model = "<model-id>"
model_reasoning_effort = "high"客户端可以识别多个已知值，也可能允许未来扩展值通过配置解析。但“客户端能解析”不等于“当前模型会接受”。最终请求仍需经过模型能力校验和服务端验证。
Codex 产品编排模式
Ultra 位于这一层更容易理解。当前 Codex 协议将 Ultra 与更主动的多代理协作行为联系起来。它不只是“比 max 再多一点模型推理 token”的简单刻度，而可能让 Codex 主动拆分任务、创建并行工作单元、综合多个结果。它产生的总消耗还包括多个代理会话、工具调用和重复上下文。
Max 到底是什么
max 可以是一个真实的模型级 reasoning effort。部分当前模型的能力表会明确列出 low、medium、high、xhigh 和 max，另一些模型会包含 none，或者只支持其中一部分。如果模型文档列出了 max，就可以把它当作该模型的最高推理投入选项之一。
但 max 不是向后兼容的通用常量。较早模型、专用模型或第三方兼容服务可能只接受到 high 或 xhigh。即使模型名称相似，不同快照、接入渠道和组织部署也可能暴露不同能力。迁移配置时必须重新核验。
因此，下面的配置只有在所选模型明确支持 max 时才可靠：
model = "<supports-max-model>"
model_reasoning_effort = "max"不要为了追求“最高档”省略模型 ID。若默认模型随后改变，原本有效的 max 可能变成无效配置，或者被客户端回退到另一个档位而没有得到预期行为。
Ultra 到底是什么
Ultra 是 Codex 侧的高级 effort 表示。Codex 的协议类型能够表示 ultra，当前产品设计还将它作为主动多代理行为的入口。这意味着 Ultra 的资源影响不应只用单次模型调用的 reasoning token 衡量。
在某些实现路径中，客户端可能把 Ultra 转换为后端能理解的模型推理值，同时在本地启用额外编排行为。转换细节可能随客户端版本、模型和服务端能力变化。用户不应假定线上的原始 API 请求一定包含字符串 ultra，更不应在普通 Responses API 调用中机械照搬。
Ultra 也不等于某个名为 Max 的模型。模型名称中的 Max 可能表示一个面向长时代理任务优化的独立模型变体；reasoning effort 的 max 是请求参数；Codex 的 Ultra 又是产品级模式。这三者只是名称接近，不能互换。
为什么界面有选项，后端仍可能报错
Codex 客户端、模型目录和后端服务可能不是同一时间发布。客户端先展示了新档位，而账户所在区域或组织后端尚未支持；远程主机运行的 CLI 版本与桌面应用内置版本不同；第三方 provider 声明的能力不准确；这些情况都会导致界面与实际请求不一致。
典型错误是服务端提示 effort 值无效，并返回当前接受的列表。此时应以错误中的支持值和模型官方能力表为准，而不是反复提交相同请求。将配置降回列表中的最高有效档位，通常比猜测别名更可靠。
model_reasoning_effort = "xhigh"如果 xhigh 仍不在支持列表中，继续降到 high 或 medium。不要用字符串大小写变化、额外空格或自创名称规避校验。
如何验证当前环境支持什么
第一步：确认精确模型
先查看当前会话状态或模型选择界面，记录完整模型 ID。不能只写“GPT-5”或“Codex 模型”，因为同一系列的不同模型可能有不同的 effort 集合。
第二步：查看当前客户端提供的档位
在 Codex 的模型选择或 reasoning 设置中查看该模型公布的可选项。客户端通常会根据模型目录过滤选项。若 max 或 ultra 没有出现，不要仅靠手改配置强行启用。
第三步：确认有效配置
用户配置、项目配置、profile 和命令行覆盖可能改变最终值。排查时应检查：
- 用户级
~/.codex/config.toml； - 受信任项目中的
.codex/config.toml； - 启动时选择的 profile；
-c或--config临时覆盖；- 当前会话中临时修改的模型与 effort。
第四步：用一个低风险任务试运行
先运行边界明确、可快速验证的任务。若服务端明确拒绝该值，应立即回退并记录模型、客户端版本、接入方式和错误支持列表。若运行成功，还要通过状态或日志确认没有静默降级。
CLI 配置应该怎么写
稳定的团队默认值通常选择当前模型广泛支持的档位：
# ~/.codex/config.toml
model = "<model-id>"
model_reasoning_effort = "medium"复杂任务可以一次性提升：
codex --config 'model_reasoning_effort="high"'只有模型目录明确支持 max，并且任务确实需要最高推理投入时，才使用：
codex --config 'model_reasoning_effort="max"'Ultra 更适合从 Codex 产品提供的相应控制入口启用，因为该入口能够同时设置客户端编排行为。除非当前版本文档明确说明可持久化及其作用域，否则不要把 model_reasoning_effort = "ultra" 当作跨版本、跨 provider 的可移植配置。
Max 与 Ultra 的资源差异
Max 主要提高单个模型调用允许的推理投入，通常会增加 reasoning token 和延迟。Ultra 可能在此基础上改变整个代理执行图：更多子任务、并行代理、工具调用和综合步骤都会增加总 token、总执行时间或产品额度消耗。
因此，比较二者时至少记录：
- 主会话的输入、输出与 reasoning token；
- 所有子代理的 token 和调用次数；
- 工具执行次数与外部等待时间；
- 从开始到通过验收的总时长；
- 最终改动质量、漏项和返工次数。
只查看主线程最后一条回答的长度，会严重低估 Ultra 的总资源投入。对于可以并行拆分的大型研究、跨模块审计或多方案实现，额外编排可能有价值；对于单文件修改或简短问答，Ultra 往往没有必要。
哪些任务值得用更高档位
Max 适合单个模型就能完成、但需要很深推理的任务，例如复杂算法证明、难以复现的并发问题、跨层架构权衡或严格约束下的迁移方案。任务仍然主要是一条推理链，只是需要更大推理预算。
Ultra 更适合天然可以拆成多个独立调查面的任务，例如大型代码库安全审计、多个平台的兼容性验证、资料核验与实现并行推进。它的价值来自编排能力，而不仅是更长思考。
如果任务不能安全并行、验收标准模糊，或多个代理会同时修改同一文件，Ultra 反而可能增加冲突和综合成本。此时 high、xhigh 或模型支持的 max 往往更可控。
兼容配置的推荐策略
- 把模型 ID 与 effort 一起固定，不单独复制 effort。
- 团队默认使用经过验证的 medium 或 high。
- 将 xhigh 和 max 作为按任务临时升级，而非无条件全局默认。
- 从 Codex 产品入口启用 Ultra，并明确它只用于适合多代理的任务。
- 升级客户端、模型或 provider 后重新读取能力列表。
- 遇到无效值错误时按服务端支持列表回退，不猜测别名。
如果团队需要在多台机器复用配置，可以为不同模型维护独立 profile。每个 profile 固定模型和已验证的 effort，避免同一个 max 配置被错误地应用到不支持它的模型。
常见概念混淆
模型名里的 Max
某些模型名称带有 Max，表示模型变体或产品定位，不代表请求自动使用 reasoning.effort=max。仍应查看该模型自己的参数说明。
界面显示 Ultra
界面显示 Ultra 只证明当前 Codex 产品愿意提供该模式，不证明所有 OpenAI API 模型都接受 ultra 字符串，也不证明第三方兼容接口支持它。
客户端枚举包含某个值
客户端代码能解析 max、ultra 或未来自定义值，是为了兼容能力扩展。它不是服务端能力承诺。模型公布的 supported reasoning efforts 才是选择依据。
最高档一定最好
更高档位可能增加推理、搜索和编排，但不会修复错误需求或缺失的验收条件。应通过真实任务成功率、延迟和资源消耗证明收益。
排错清单
当 max 或 ultra 不按预期工作时，按以下顺序排查：
- 记录 Codex CLI 或桌面应用版本。
- 记录精确模型 ID、provider 和登录方式。
- 检查当前模型公布的 supported reasoning efforts。
- 确认没有项目配置、profile 或命令行参数覆盖。
- 查看服务端错误返回的允许值集合。
- 回退到 xhigh、high 或 medium，确认基本链路正常。
- 若 Ultra 涉及多代理，检查子任务数量和总资源消耗。
提交问题报告时应附上脱敏后的有效配置、客户端版本、模型 ID、复现命令和完整错误类型。只写“Ultra 不能用”无法判断是客户端展示、模型能力、provider 转换还是服务端发布不同步。
结论
Max 与 Ultra 不属于所有 Codex 环境通用的一条固定等级链。max 已是部分新模型支持的模型级 Reasoning Effort，但必须由当前模型明确声明；Ultra 主要是 Codex 的产品级高级模式，可能把更高模型推理与主动多代理编排结合起来，不能直接等同于通用 API 参数。最可靠的做法是以当前模型的能力列表为准，固定模型与 effort 配对，先用 medium 或 high 建立基线，再按真实任务临时升级到 xhigh、max 或 Ultra，并验证实际生效值和总资源消耗。
