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

作者：袖梨 2026-09-13

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；只限制工具输出可能保留空间，却不会改变模型思考投入。

如何真正控制任务成本

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

评测时记录哪些指标

指标	对应配置
复杂任务成功率	`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 设置都不会改变沙箱或审批规则。成本调优不能替代安全控制。

排错检查清单

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

常见问题

想让回答更短应该调哪个

优先调整 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 决定自动压缩时机。把这些字段分开评测，才能在质量、可读性、上下文稳定性和实际用量之间取得可靠平衡。