Codex CLI 如何按任务复杂度选择模型和 Reasoning Effort？

Codex CLI 选择模型和 Reasoning Effort 时，应先判断任务需要什么能力，再决定模型要投入多少推理。模型选择决定能力、速度、上下文和工具支持的基础边界，Reasoning Effort 则在该模型支持范围内调节推理投入。简单任务通常适合快速模型配低档位，日常开发使用通用模型配中档位，复杂诊断和高风险设计再使用强模型配高档位。

模型和推理档位不是同一个开关

维度	主要影响	典型问题
模型	基础能力、速度、上下文、工具和模态支持	这个模型能否可靠完成任务
Reasoning Effort	当前模型在任务上的推理投入	要让它为这次任务想多深

弱模型使用最高档位不一定超过强模型的中档位，强模型使用高档位也不一定值得额外延迟。两者必须组合评测。

先把任务分成四级

复杂度	任务特征	初始策略
一级	机械、单步、结果唯一	快速模型 + low 或更低支持档
二级	常规开发、边界明确	通用模型 + medium
三级	多模块、根因未知、需权衡	强模型 + high
四级	长周期、高风险、极难推理	最强适用模型 + high 或经验证的 xhigh

复杂度不是由代码行数决定，而是由相互依赖的判断数量、未知信息、失败成本和验证难度共同决定。

一级任务：机械执行

典型任务包括：

• 从文本中提取固定字段。
• 按规则修改格式。
• 重命名已知符号。
• 运行指定命令并汇总退出码。
• 生成严格 schema 的结构化结果。

这类任务优先选择响应快、资源消耗低的模型，并从 low 开始。若模型支持更低档位且评测仍稳定，可以继续下调。

二级任务：日常开发

典型任务包括常规接口实现、多文件小功能、测试补全、已知类型 Bug 修复和普通代码审查。

选择工具能力完整的通用模型，配合 medium 作为基线。若项目模式高度统一、测试覆盖充分，可尝试更快模型或 low。

三级任务：复杂工程判断

这类任务常见特征是：

• 根因跨越多个模块或服务。
• 证据相互冲突。
• 需要分析并发、事务或缓存一致性。
• 设计方案涉及多个长期权衡。
• 失败难以快速撤销。

此时应选择推理和工具使用能力更强的模型，并从 high 评测。若信息不完整，先补齐日志、代码和约束，而不是继续升档。

四级任务：长周期高风险工作

大型迁移、深度安全审计、长时间自治重构和困难算法问题属于这一层。模型不仅要推理，还要稳定维护约束、使用工具并验证阶段结果。

优先选择当前可用且适合 Agent 工程任务的最强模型，从 high 开始。只有 xhigh 得到模型支持，并在评测中显著提高成功率时才使用。

模型能力要检查哪些项目

1. 是否针对代码和 Agent 工作优化。
2. 是否支持需要的工具调用。
3. 上下文窗口是否覆盖任务规模。
4. 是否支持图像、文件或其他输入。
5. 支持哪些 Reasoning Effort 档位。
6. 当前账号和执行环境是否可用。
7. 延迟和用量是否符合工作流要求。

型号和可用性变化较快，应查询当前模型列表，不要永久依赖旧文章中的清单。

Reasoning Effort 如何选择

Codex 配置中常见值包括 minimal、low、medium、high 和 xhigh。具体模型可能只支持其中一部分。

• minimal：极明确、几乎不需权衡的任务。
• low：轻量推理和高频执行。
• medium：日常开发的平衡基线。
• high：复杂分析和高风险判断。
• xhigh：最困难、对延迟不敏感的任务。

默认值由模型和 preset 决定。需要可重复测试时应显式记录。

一个实用的选择矩阵

任务	模型类型	推理起点
搜索与提取	快速、低成本模型	low
常规功能开发	通用或代码模型	medium
普通 PR 审查	通用或代码模型	medium
复杂 Bug 定位	强推理代码模型	high
架构与迁移规划	强通用模型	high
大型自治重构	长周期 Agent 模型	high
能力上限评测	最强支持模型	xhigh，若支持

为什么模型选择优先于调档

如果模型缺少必要工具、上下文或领域能力，提高 Reasoning Effort 无法补上这些基础缺口。例如模型不支持目标档位时，配置甚至会直接失败。

先选满足能力要求的模型，再寻找它的最低稳定档位，决策顺序更清楚。

快速模型适合什么

快速模型适合边界清楚、可并行和可自动验证的任务，例如代码搜索、文档分类、单文件机械修改和独立测试生成。

如果任务需要最终架构判断或处理模糊冲突，可以让快速模型收集证据，再交给更强模型决策。

强模型适合什么

强模型适合任务定义不完整、方案空间较大或失败成本高的工作。它更适合作为规划者、协调者和最终审查者。

但强模型并不意味着所有调用都要使用高档位。对于明确的后续执行，仍可保留强模型并降低 Reasoning Effort。

代码专用模型和通用模型如何选

纯软件工程任务可以优先评测代码专用模型；需要结合产品、业务、视觉或跨领域材料时，通用模型可能更合适。

不能仅根据名称判断。应使用相同任务、相同工具权限和相同验收标准做对照。

先规划再执行时如何组合

复杂任务可以把阶段拆开：

1. 强模型配 high，明确约束、风险和验收。
2. 将计划拆成边界清楚的执行单元。
3. 执行阶段使用通用或快速模型配 low/medium。
4. 强模型重新审查冲突、边界和最终结果。

如果执行过程中发现新约束，应升级而不是僵化遵循旧计划。

多 Agent 如何分配模型

多 Agent 工作流可以按角色分配：

• 协调者：强模型，负责拆分、冲突处理和最终判断。
• 探索者：快速模型，负责搜索文件和收集证据。
• 实现者：按子任务复杂度选择模型。
• 审查者：与实现者独立，使用足以发现边界问题的模型和档位。

不要规定所有子 Agent 永远低档。安全审查或复杂实现即使是子任务，也可能需要 high。

在 config.toml 中保存默认组合

model = "当前已验证的模型标识"
model_reasoning_effort = "medium"

个人默认写入 ~/.codex/config.toml，项目特殊要求可写入受信任仓库的 .codex/config.toml。

一次性从命令行覆盖

codex --model "当前可用模型标识" 
  --config 'model_reasoning_effort="high"'

--model 也可简写为 -m，--config 可简写为 -c。字符串值按 TOML 规则引用。

会话中如何切换

交互式 Codex CLI 可以使用 /model 选择当前模型，使用 /reasoning 选择当前对话的推理档位。切换模型后应重新确认 Reasoning Effort，因为新模型的支持范围可能不同。

使用 /status 检查当前会话信息，不要仅凭回答长度推断设置。

用 profile 保存常见组合

团队可以维护快速、日常和深度审查等 profile。每个 profile 文件只保存与基础配置不同的项：

# ~/.codex/deep-review.config.toml
model = "当前已验证的强模型标识"
model_reasoning_effort = "high"

启动时使用：

codex --profile deep-review

模型变更后，应更新并重新评测 profile，而不是保留失效标识。

如何建立模型与档位评测

1. 从实际工作中抽取代表性任务。
2. 固定提示、仓库状态、工具权限和验收标准。
3. 分别运行候选模型的中等档位。
4. 淘汰能力不足或工具不兼容的模型。
5. 对保留模型逐级降低或提高档位。
6. 重复运行以减少偶然结果。
7. 记录模型版本和测试日期。

应记录哪些指标

指标	意义
首次通过率	衡量一次完成能力
测试通过率	验证产物正确性
总完成时间	包括重试和人工等待
Token 与额度消耗	衡量实际资源成本
人工纠正次数	发现低价方案的隐性成本
越界修改数量	衡量约束遵循

使用升级策略降低平均成本

可自动验证的任务可以从较经济组合开始：

1. 快速模型配 low。
2. 运行测试或规则验证。
3. 失败后把证据交给通用模型配 medium。
4. 复杂失败再升级到强模型配 high。

验证器必须可靠。无法自动判断正确性的高风险任务，不适合从过低配置开始。

何时只提高 Reasoning Effort

当前模型具备所需能力，但在完整证据下仍遗漏多步依赖、边界条件或权衡时，先提高推理档位。

这样保留模型能力和工具行为，便于判断问题是否只是推理投入不足。

何时应该换模型

出现以下情况时，应考虑换模型：

• 缺少需要的工具或输入模态。
• 上下文容量不适合任务。
• 最高支持档位仍无法稳定通过。
• 任务更适合另一类专用能力。
• 当前延迟或用量无法满足工作流。

何时应该降低配置

同类任务连续稳定通过，且较低模型或档位没有降低质量时，应降级。节省的资源可以留给真正复杂的任务。

降级必须以端到端成本为依据。如果低配置导致重试和人工纠正，总成本可能更高。

常见错误一：所有任务用最强组合

这会增加日常机械工作的延迟和用量，也可能产生过度探索。最强组合应保留给评测证明需要它的任务。

常见错误二：最快模型处理最终决策

快速模型适合收集证据和执行明确步骤，但涉及架构、安全和数据风险的最终判断需要足够能力与独立验证。

常见错误三：把 xhigh 当作万能修复

xhigh 不能补齐缺失信息、工具权限或矛盾需求，也不是所有模型都支持。先修复上下文和流程问题。

常见错误四：引用过时型号

模型目录、可用范围和默认选择会变化。团队规范应描述选择原则，并将具体型号放在可更新的配置或评测记录中。

常见错误五：只看单次速度

快速返回但需要三次返工的组合，可能比一次正确的较强配置更慢。必须统计完整任务周期。

安全与权限独立于模型选择

更强模型或更高 Reasoning Effort 不会自动改变沙箱、网络和审批权限。高风险任务必须继续使用最小权限、明确审批和可回滚操作。

决策检查清单

1. 任务需要哪些工具、模态和上下文。
2. 推理链是否跨越多个依赖。
3. 失败成本和回滚难度如何。
4. 结果能否自动验证。
5. 候选模型是否支持目标档位。
6. 更高配置是否带来可测量收益。
7. 型号和评测结果是否仍然新鲜。

常见问题

不知道任务复杂度时怎么选

从当前推荐的通用模型和中等档位建立基线，根据实际失败原因再升级或降级。

换模型还是升档哪个优先

若模型能力和工具足够，先升档；若缺少基础能力、上下文或支持值，则换模型。

低档位一定更便宜吗

单次推理通常更少，但端到端成本还包含重试、工具调用和人工纠正，应以完整评测为准。

模型升级后旧 profile 能继续用吗

配置可能仍可解析，但质量、默认值和支持档位可能变化，必须重新验证。

总结

按任务复杂度选择 Codex 模型和 Reasoning Effort，应先确保模型具备所需代码能力、工具、上下文和输入支持，再用最低可稳定通过的推理档位运行。机械任务采用快速模型与低档位，日常开发采用通用模型与中档位，复杂诊断和高风险设计采用强模型与高档位，xhigh 只用于支持它且评测证明有收益的极难任务。型号会变化，但“能力先于档位、评测先于默认”的原则长期有效。