自学教程

Codex CLI 模型选择

Codex 教程

Codex CLI 支持多模型切换，可在全局配置、项目配置、单次任务命令行三个层面指定模型。不同模型在上下文长度、工具调用能力、推理速度、成本、自动化适配性上存在差异。合理选择模型，兼顾任务效果、执行速度与资源开销，是CLI自动化、批处理任务调优的关键。本文讲解模型指定方式、模型选型参考、参数配置、优先级、非交互模式用法以及常见问题。

一、模型选择基础概念

Codex CLI 支持调用官方系列模型，部分版本支持接入第三方模型（通过MCP网关）。
模型能力差异主要体现在：

  1. 工具调用：MCP、子代理、钩子、文件读写、bash命令支持程度。
  2. 上下文窗口：长代码库、大文件、多轮任务需要更大上下文。
  3. 推理速度：简单任务选择轻量模型，复杂重构、架构分析选用强能力模型。
  4. 成本消耗：大模型单价更高，大批量CI流水线任务优先轻量模型。

重要：并非所有模型都完整支持全部Codex能力。Computer Use、子代理、复杂MCP多工具调用，需要选用支持Agent原生能力的模型；轻量模型适合简单文档生成、代码评审。

二、模型配置的三种方式

方式1：命令行临时指定（单次任务，优先级最高）

交互模式启动时指定模型：

codex --model gpt-5-codex

非交互模式 codex exec，适合流水线脚本：

codex exec --model gpt-5-codex "重构utils工具函数"

方式2：项目级配置（.codex/config.toml，仓库共享）

项目内固定模型，团队所有成员、CI流水线默认复用。

[model]
default = "gpt-5-codex"
# 可选：为不同任务类型绑定不同模型
model_override.code_review = "gpt-5-mini"
model_override.architecture_design = "gpt-5-codex"

model_override 可以按任务类型自动切换模型。

方式3：用户全局配置（~/.codex/config.toml）

本机全局默认模型，优先级低于项目配置，仅本机生效。

[model]
default = "gpt-5-mini"

优先级排序：命令行 --model 参数 > 项目config.toml > 用户全局config.toml。

三、模型选型参考表

模型适用场景优势限制
gpt-5-codex复杂代码重构、架构分析、多工具调用、子代理、MCP复杂工作流完整Agent能力，长上下文，支持Computer Use推理耗时较长，token成本更高
gpt-5-mini代码评审、生成单元测试、文档编写、简单bug修复、CI批量任务速度快，成本低，基础工具调用稳定复杂架构推理能力弱，不推荐大规模重构
第三方模型（MCP网关接入）私有化部署、自定义大模型自主可控部分高级Codex Agent能力不支持，需要测试验证

选型建议

  • 架构设计、大规模代码重构、多MCP协同、子代理任务：选择 gpt-5-codex。
  • PR评审、lint修复、生成注释、简单脚本生成、CI流水线批量任务：选择 gpt-5-mini。
  • 大批量自动化任务：优先轻量模型，降低开销；复杂任务单独指定强模型。

四、模型相关参数配置

在 config.toml 的 [model] 节点，除模型名称外，还可以调整推理参数：

[model]
default = "gpt-5-codex"
temperature = 0.1
max_tokens = 8192
top_p = 0.9
  • temperature：随机性，代码类任务推荐 0 ~ 0.2，越低输出越稳定，适合自动化。文档创意写作可适度调高。
  • max_tokens：单次输出最大token，长代码生成任务适当放大。
  • top_p：采样参数，代码场景推荐0.8~0.9。

命令行也可临时覆盖参数：

codex exec --model gpt-5-mini --temperature 0.1 "评审代码变更"

五、会话内模型管理斜杆命令

在Codex交互会话中动态查看、切换模型，无需重启CLI：

# 查看当前会话使用的模型与参数
/model info列出当前环境可用模型列表
/model list
切换当前会话模型
/model set gpt-5-mini
重载模型配置（修改config.toml后）
/model reload

六、非交互模式模型选择要点

非交互模式常用于CI、脚本自动化，模型选择需要额外注意：

  1. 批量PR评审，推荐使用 gpt-5-mini，降低成本，提升流水线速度。
  2. 复杂自动修复任务，使用 --model gpt-5-codex。
  3. 所有参数可写在命令行，便于版本管理与审计。
    示例：
codex exec \
  --model gpt-5-mini \
  --temperature 0.1 \
  --sandbox read-only \
  --skills code-review \
  "评审本次git diff，输出markdown评审报告"

非交互模式下，模型切换不会改变AGENTS.md、rules、MCP、沙箱配置，仅更换推理后端。

七、模型与能力兼容性

  1. 子代理、MCP多工具调用：优先选用codex专用模型；轻量模型可能出现工具调用失败。
  2. Computer Use电脑操控：仅codex主模型支持，mini模型不具备该能力。
  3. 长上下文项目分析：选择具备更大上下文窗口的模型，避免代码截断。
  4. 第三方模型接入：通过MCP模型网关接入，仅基础代码能力可用，高级Agent能力可能缺失。

八、最佳实践

  1. 项目固定默认模型，写入项目config.toml，保证团队本地、CI环境模型一致。
  2. 简单批量任务使用轻量模型，复杂重构任务使用高级模型，通过model_override自动区分。
  3. 代码自动化任务temperature保持低数值，减少随机输出，保证每次结果稳定可复现。
  4. CI流水线尽量避免动态切换模型，固定模型便于评估耗时与成本。
  5. 第三方模型接入前，提前测试MCP调用、钩子联动能力，确认兼容性。
  6. 监控token消耗，大批量自动化任务定期评估模型选型，优化成本。

九、常见问题

Q：切换模型之后，AGENTS.md、MCP配置是否需要重新加载？
A：不需要。模型只是推理后端，项目规则、MCP、沙箱配置保持不变。

Q：model_override 是自动触发的吗？
A：是的，当任务匹配预设任务类型，自动替换为指定模型；命令行–model优先级更高，会覆盖自动覆盖。

Q：gpt-5-mini 是否支持子代理？
A：支持基础子代理，但复杂多工具链式调用稳定性弱于codex主模型，不建议重度复杂工作流。

Q：能否在子代理配置中单独指定模型？
A：可以。子代理 .codex/agents/xxx.toml 中可以设置 model = "gpt-5-mini"，子代理使用独立模型，不和主代理共用。

十、总结

Codex CLI支持在命令行、项目配置、全局配置三层设置模型，优先级由高到低依次为命令行参数、项目配置、全局配置。

模型选型需要结合任务复杂度：轻量模型适合代码评审、文档生成等简单自动化任务；Codex主模型适合架构分析、大规模重构、多MCP、子代理、Computer Use等复杂Agent工作流。配合temperature、max_tokens等推理参数调优，在CLI交互与非交互流水线中平衡执行效果、速度与成本。

标签：

0 条笔记