Codex CLI 如何分别控制 Reasoning Effort、输出详细度和 Token 预算？

Codex CLI 的推理强度、输出详细度和 Token 预算是不同控制维度。model_reasoning_effort 决定模型投入多少推理，model_verbosity 调整最终回答的详细程度，tool_output_token_limit 限制单次工具结果存入历史的 Token 数，model_auto_compact_token_limit 决定何时自动压缩会话历史。它们不能互相替代，也没有任何一个字段等同于整次任务的硬费用上限。

四个核心配置项

配置项	控制对象	不控制什么
model_reasoning_effort	模型推理投入	最终文字长度
model_verbosity	最终回答详细度	思考深度
tool_output_token_limit	单次工具输出写入历史的预算	模型总输出和总费用
model_auto_compact_token_limit	自动压缩历史的触发阈值	模型上下文窗口本身

Reasoning Effort 控制思考投入

在 config.toml 中使用：

model_reasoning_effort = "medium"

Codex 配置参考列出的常见值为 minimal、low、medium、high 和 xhigh，其中 xhigh 是否可用取决于模型。

较低档位偏向速度和较少推理用量，较高档位偏向更完整的复杂分析。实际 Token 数由模型和任务自适应决定，不是固定配额。

Verbosity 控制回答详细度

使用：

model_verbosity = "low"

可选值为 low、medium 和 high。未设置时采用所选模型或 preset 的默认值。

• low：适合自动化、结构化输出和代码优先的场景。
• medium：适合日常解释与代码混合输出。
• high：适合教程、设计说明和需要完整背景的审查。

Verbosity 影响“说多少”，Reasoning Effort 影响“想多少”。

高推理可以搭配低详细度

复杂任务需要深入分析，但自动化只需要简洁结果时，可以这样设置：

model_reasoning_effort = "high"
model_verbosity = "low"

这种组合适合安全扫描、复杂故障诊断和 CI 审查：模型保留充分推理，但最终输出只包含结论、证据和必要操作。

低推理也可以搭配高详细度

任务逻辑简单，但读者需要完整说明时，可以使用：

model_reasoning_effort = "low"
model_verbosity = "high"

例如把已有方案整理成培训材料。需要注意，长回答不会自动提升事实正确性，仍应验证内容。

推理摘要是第三个独立维度

model_reasoning_summary 控制推理摘要的呈现方式：

model_reasoning_summary = "concise"

官方配置值包括：

• auto：让模型选择摘要形式。
• concise：简短摘要。
• detailed：更详细的摘要。
• none：不显示推理摘要。

推理摘要不是模型的完整内部思维，也不代表实际推理 Token 数。关闭摘要主要改变可见输出，不等于关闭推理。

工具输出 Token 预算控制什么

终端命令、文件读取和 MCP 调用都可能产生大量文本。这些内容进入会话历史后会占用上下文。可以设置：

tool_output_token_limit = 12000

该值是单次工具或函数输出存入历史的 Token 预算。超过预算时，内容可能被截断或压缩，具体行为由运行时决定。

它不是模型回答上限

tool_output_token_limit 不限制最终回答长度，不限制推理 Token，也不直接限制整次任务总用量。它只约束工具结果进入历史的规模。

因此，把它设得很低并不能保证上限，却可能让模型看不到日志末尾或文件关键部分。

什么时候应该降低工具输出预算

• 工具经常返回重复日志。
• 命令输出包含大量构建噪声。
• MCP 响应很大但只有摘要有用。
• 长会话频繁受到上下文压力。
• 任务能通过分页或精确查询获取所需片段。

降低前应先改进命令，例如使用过滤、范围读取和结构化查询。精准获取比事后截断更可靠。

什么时候不应该设得过低

• 需要读取完整错误堆栈。
• 文件尾部包含关键配置或结果。
• 审计要求保留完整工具证据。
• 输出无法分页或重新请求。
• 截断标记不够醒目。

如果必须看完整内容，优先拆分请求，而不是无上限地扩大单次输出。

自动压缩阈值控制什么

长会话接近上下文容量时，Codex 可以压缩历史。触发阈值由：

model_auto_compact_token_limit = 140000

控制。未设置时采用模型默认。数值必须结合所选模型的上下文窗口评估，不能照搬其他模型的示例。

压缩不是删除所有上下文

自动压缩会把较长的历史整理为更紧凑的状态，以便继续工作。它能释放上下文空间，但摘要不可能无损保留每个细节。

对关键约束，应保存在仓库文档、任务文件或可重复读取的数据源中，而不是只存在于早期对话。

压缩阈值过高的风险

• 接近上下文上限才处理，剩余空间不足。
• 一次大型工具输出可能突然触发压力。
• 模型为总结和后续回答留下的空间过少。

压缩阈值过低的风险

• 会话频繁压缩。
• 早期细节更快被摘要化。
• 反复重读文件增加工具调用和延迟。
• 复杂任务的连续性下降。

合适阈值应通过长任务测试决定，而不是追求越小越安全。

配置示例：交互式开发

model_reasoning_effort = "medium"
model_verbosity = "medium"
model_reasoning_summary = "auto"
tool_output_token_limit = 12000

这组配置适合日常开发起点。自动压缩阈值可以先保持模型默认，再根据实际上下文压力调整。

配置示例：CI 自动化

model_reasoning_effort = "low"
model_verbosity = "low"
model_reasoning_summary = "none"
tool_output_token_limit = 8000

适合任务明确、输出由机器消费且有可靠测试的流水线。若任务包含复杂根因分析，可提高推理强度，但仍保留低详细度。

配置示例：架构审查

model_reasoning_effort = "high"
model_verbosity = "high"
model_reasoning_summary = "detailed"
tool_output_token_limit = 16000

适合需要解释方案、风险和权衡的工作。工具输出预算仍应限制，避免一次无关日志占满历史。

配置示例：长时间重构

model_reasoning_effort = "medium"
model_verbosity = "low"
model_reasoning_summary = "concise"
tool_output_token_limit = 10000
model_auto_compact_token_limit = 120000

示例数字只是展示字段组合，不是通用推荐。实际阈值必须按模型上下文、仓库大小和工具输出分布测试。

一次性从命令行覆盖

可以使用 -c 或 --config 调整单次运行：

codex 
  -c 'model_reasoning_effort="high"' 
  -c 'model_verbosity="low"' 
  -c 'tool_output_token_limit=10000'

值按 TOML 解析。字符串需要正确引用，数字不应加成字符串。

为什么不要用一个“省 Token”开关

Token 消耗来自多个位置：

• 输入上下文。
• 模型推理。
• 最终可见输出。
• 工具结果。
• 历史压缩与后续重读。

只降低 verbosity 可能减少可见输出，但复杂推理仍会消耗 Token；只限制工具输出可能保留空间，却不会改变模型思考投入。

如何真正控制任务成本

1. 固定模型和代表性任务。
2. 记录输入、推理、输出和工具数据规模。
3. 先减少无关上下文和重复工具输出。
4. 对简单任务测试较低 Reasoning Effort。
5. 对机器消费结果使用较低 verbosity。
6. 用分页、过滤和范围读取代替大输出。
7. 观察压缩次数和压缩后的返工。
8. 按端到端成功成本选择配置。

评测时记录哪些指标

指标	对应配置
复杂任务成功率	model_reasoning_effort
最终回答长度与可读性	model_verbosity
工具结果截断率	tool_output_token_limit
压缩次数与信息丢失	model_auto_compact_token_limit
总完成时间和总用量	全部配置共同作用

常见错误一：用 verbosity 代替 reasoning

把 model_verbosity 设为 high 只会要求更详细的最终回答，不保证模型投入更多复杂推理。需要提高分析深度时，应调整 model_reasoning_effort。

常见错误二：关闭摘要等于关闭推理

model_reasoning_summary = "none" 只是不展示摘要。模型是否推理以及投入多少，仍由模型和 Reasoning Effort 决定。

常见错误三：把工具预算当费用上限

tool_output_token_limit 只限制单次工具输出进入历史。任务仍可能调用许多工具，也可能产生大量推理和最终输出 Token。

常见错误四：照搬压缩阈值

不同模型拥有不同上下文窗口和运行默认。示例中的绝对数字不能跨模型直接复用，应保留充足输出空间并进行长会话测试。

常见错误五：同时调太多参数

一次改变四个设置后，即使结果改善，也无法判断是哪项产生作用。建议每轮只改变一个维度，并保持模型、任务和输入一致。

配置安全与可复现性

把配置纳入团队流程时，应记录 Codex 版本、模型标识、配置来源和评测日期。项目配置只在受信任仓库加载，个人路径和凭证不应提交到仓库。

Reasoning Effort 和 Token 设置都不会改变沙箱或审批规则。成本调优不能替代安全控制。

排错检查清单

1. 确认键名和 TOML 类型正确。
2. 确认配置位于正确层级。
3. 检查 CLI、项目、profile 和用户配置覆盖关系。
4. 确认模型支持目标推理和 verbosity 值。
5. 检查工具输出是否被截断。
6. 检查是否频繁发生历史压缩。
7. 使用真实用量而非主观感觉评估。

常见问题

想让回答更短应该调哪个

优先调整 model_verbosity，并在提示中明确输出格式。不要为了缩短回答直接降低推理强度。

想让复杂任务想得更充分呢

调整 model_reasoning_effort，同时确保上下文和工具证据完整。

想防止一条日志占满上下文呢

先过滤或分页获取日志，再用 tool_output_token_limit 作为保护。

想限制整个任务费用呢

这些配置不能单独提供硬费用上限。还需结合模型选择、调用次数、任务终止条件和外部用量控制。

总结

Codex CLI 中，model_reasoning_effort 控制推理投入，model_verbosity 控制最终回答详细度，model_reasoning_summary 控制摘要显示，tool_output_token_limit 限制单次工具结果进入历史，model_auto_compact_token_limit 决定自动压缩时机。把这些字段分开评测，才能在质量、可读性、上下文稳定性和实际用量之间取得可靠平衡。