Codex CLI 如何将 GPT-5 的 Reasoning Effort 设置为 high？

在 Codex CLI 中将 GPT-5 的 Reasoning Effort 设为 high，可以临时运行 codex --config 'model_reasoning_effort="high"'，也可以在 ~/.codex/config.toml 中长期设置 model_reasoning_effort = "high"。配置是否有效还取决于当前模型是否支持该档位，以及有没有更高优先级的命令行或项目配置覆盖它。

临时设置 high

只想在一次任务中使用高推理强度，可以执行：

codex --config 'model_reasoning_effort="high"'

--config 也可以简写为 -c：

codex -c 'model_reasoning_effort="high"'

这种方式不会修改配置文件，退出本次 Codex 会话后不会成为永久默认值。

同时指定 GPT-5 模型

为了避免默认模型不明确，可以同时显式指定模型：

codex --model "实际可用的 GPT-5 模型标识" \
  --config 'model_reasoning_effort="high"'

模型标识必须来自当前账号和客户端可用的模型列表。不要直接复制示例占位文字，也不要假设所有带 GPT-5 名称的模型都支持相同推理档位。

长期设置 high

个人日常默认配置位于：

~/.codex/config.toml

加入以下内容：

model = "实际可用的 GPT-5 模型标识"
model_reasoning_effort = "high"

以后从没有其他覆盖的目录启动 Codex CLI，就会采用这组用户级默认值。

只为一个项目启用 high

如果只有某个仓库需要高推理强度，在项目中创建：

.codex/config.toml

写入：

model_reasoning_effort = "high"

项目配置只有在 Codex 信任该项目时才会加载。项目未受信任时，项目范围的 .codex 层会被跳过。

哪一种设置方式更合适

命令中的引号为什么这样写

Codex 的 --config 接收 TOML 形式的键值。high 是字符串，因此内部需要双引号；外部使用单引号，避免 shell 提前处理内容：

'model_reasoning_effort="high"'

在不同 shell 中，引用规则可能不同。若出现 TOML 解析错误，应检查命令行最终传入的字符串，而不是修改推理档位名称。

配置值必须位于顶层

在 config.toml 中，model_reasoning_effort 是顶层键。推荐放在文件开头：

model = "实际模型标识"
model_reasoning_effort = "high"

[features]
some_feature = true

如果把它写在 [features] 或其他 TOML 表格声明后面，它会被解析成该表格的子键，不能达到预期效果。

如何确认 high 生效

进入 Codex CLI 后，可以查看当前会话状态或模型信息。具体界面随版本变化，但应确认两项：

• 当前模型是预期的 GPT-5 模型。
• Reasoning Effort 显示为 high。

如果客户端支持 /status，可用它检查当前会话信息。不能只凭响应更慢或回答更长判断配置成功。

配置优先级会影响结果

Codex 的配置优先级从高到低通常是：

1. CLI 参数和 --config 覆盖。
2. 项目目录中的 .codex/config.toml。
3. 通过 --profile 选择的 profile。
4. 用户级 ~/.codex/config.toml。
5. 云端、系统和内置默认值。

因此，用户配置为 high，但启动脚本传入 low 时，本次会话仍会使用 low。

项目子目录也可能覆盖

Codex 可以读取从项目根目录到当前工作目录之间的项目配置，距离当前目录最近的配置优先。如果在单体仓库的子项目启动 Codex，应检查该路径上是否还有另一份 .codex/config.toml。

为什么设置 high 后报错

常见原因包括：

• 当前模型不支持 high。
• 模型提供商没有实现对应推理参数。
• 客户端版本过旧。
• TOML 键名或字符串引号错误。
• 模型标识不存在或账号无权访问。
• 组织管理策略限制了可选模型或配置。

先核验当前模型说明和有效配置，再判断是否需要升级客户端。

GPT-5 是一个模型家族

“GPT-5”不能代替精确模型标识。不同版本可能支持不同档位，也可能具有不同默认推理强度。团队文档应记录完整模型标识，而不是只写“使用 GPT-5 high”。

模型升级后，要重新确认 high 是否仍适用，并复跑代表性任务。

high 会带来什么变化

high 指导模型投入更充分的推理，通常更适合多步骤和高复杂度问题。相对较低档位，它可能带来更高延迟和更多推理 Token。

这不是固定倍数，也不保证任何任务都获得更好结果。实际变化取决于模型、输入、上下文和工具调用。

哪些任务值得使用 high

• 复杂 Bug 的跨模块根因定位。
• 并发、事务和一致性问题。
• 大型重构的依赖与回滚分析。
• 架构方案的多维权衡。
• 权限、安全和隐私审查。
• 多个失败证据互相冲突的诊断。

这些任务的共同点是需要维持较长推理链，且遗漏约束的成本较高。

哪些任务不需要 high

• 固定格式转换。
• 简单重命名和文案修改。
• 明确的单行修复。
• 结构化字段提取。
• 运行指定命令并返回结果。

如果这类任务有完整自动测试，使用 low 或 medium 往往更高效。

high 不能弥补上下文缺失

如果没有提供关键代码、日志、版本或业务规则，模型无法凭更高推理强度恢复事实。此时应补充证据，而不是继续增加推理投入。

同样，权限不足和网络失败属于工具问题，不属于 Reasoning Effort 问题。

high 不是输出长度设置

Reasoning Effort 控制模型的推理投入，输出长度由提示要求、verbosity 和输出上限等因素共同影响。设置 high 后得到简短答案，不代表配置无效。

high 不是安全模式

高推理强度不会自动收紧文件系统、网络或命令权限。运行高风险任务时，仍应使用沙箱、审批、最小权限和可回滚操作。

如何评估是否值得长期使用

选择一组真实开发任务，在相同模型、上下文和工具权限下比较 medium 与 high：

• 首次完成率。
• 测试和审查通过率。
• 端到端完成时间。
• 推理及总 Token 用量。
• 人工纠正次数。
• 越界修改和遗漏约束数量。

只有 high 带来的质量收益足以抵消额外延迟和用量，才适合设置为长期默认。

一种更实用的 profile 思路

如果只有审查和复杂调试需要 high，可以保留日常默认值，并建立专用 profile。启动高难度任务时选择该 profile，普通工作继续使用较低档位。

这种方式能降低误用成本，也让团队更容易知道为何启用了高推理强度。

排错检查清单

1. 确认键名为 model_reasoning_effort。
2. 确认值是带引号的 "high"。
3. 确认配置位于 TOML 顶层。
4. 确认当前模型的精确标识。
5. 确认模型支持 high。
6. 检查命令行、项目和 profile 覆盖。
7. 检查项目是否受信任。
8. 重启会话并查看状态。

常见问题

命令行和配置文件哪个优先

命令行参数和 --config 覆盖优先于项目、profile 和用户配置。

设置 high 后需要重启吗

修改文件后，重新启动 Codex 会话最容易确保新配置被读取。一次性命令则在启动时直接生效。

所有 GPT-5 模型都支持 high 吗

不能只按家族名判断，应查看所选精确模型的当前文档。

能直接指定推理 Token 数吗

Reasoning Effort 是相对投入档位，不是固定推理 Token 配额。模型会结合任务自适应使用推理量。

总结

一次性将 Codex CLI 的 GPT-5 推理强度设为 high，使用 codex --config 'model_reasoning_effort="high"'；长期使用则把 model_reasoning_effort = "high" 写入用户或受信任项目的 config.toml。设置后应确认精确模型、会话状态和配置覆盖关系，并用真实任务评估质量收益。high 适合复杂、高风险推理，不应因“更高”就用于所有日常任务。