Codex CLI常用配置实战：模型、推理强度与Web Search配置和验证

2026-07-29 09:29:22 阿沐沐，

Codex CLI 常用配置实战：模型、推理强度与 Web Search 配置和验证

本文面向已经能正常使用 Codex CLI、希望固定日常开发行为的读者，适用版本为 Codex CLI 0.145.0，最后核验日期为 2026-07-28。重点解决模型选择、推理强度、Personality 和 Web Search 四类常用配置，不重复首次连接流程。

完成后，你会得到一份可回退、保留安全边界的 config.toml。示例中的 medium 只面向本文核验的 GPT-5.5 与 GPT-5.6 Sol、Terra、Luna 目录项，不是所有模型的通用值。字段事实来自官方配置文档；具体档位、默认值和 Personality 模板来自 OpenAI rust-v0.145.0 标签中的内置 models.json，并通过 codex debug models --bundled 交叉验证。本文不使用模型回答作为配置事实依据，Web Search 运行结果仍需读者在自己的可用环境中验证。

修改前先备份

配置已经能工作时，先备份再调整。若新配置不符合预期，可以直接恢复原文件。

PowerShell

$codexHome = if ($env:CODEX_HOME) { $env:CODEX_HOME } else { Join-Path $HOME ".codex" }
Copy-Item (Join-Path $codexHome "config.toml") (Join-Path $codexHome "config.toml.daily-config.bak")

恢复命令：

$codexHome = if ($env:CODEX_HOME) { $env:CODEX_HOME } else { Join-Path $HOME ".codex" }
Copy-Item (Join-Path $codexHome "config.toml.daily-config.bak") (Join-Path $codexHome "config.toml") -Force

Bash 或 Zsh

codex_home="${CODEX_HOME:-$HOME/.codex}"
cp "$codex_home/config.toml" "$codex_home/config.toml.daily-config.bak"

恢复命令：

codex_home="${CODEX_HOME:-$HOME/.codex}"
cp "$codex_home/config.toml.daily-config.bak" "$codex_home/config.toml"

如果源文件还不存在，应先完成首次配置，不要把备份命令的报错当成 Codex 配置错误。

合并这份日常配置

把下面的顶层字段合并到当前实际生效的 config.toml。不要覆盖文件中已经工作的其他字段或配置表。

model = "YOUR_MODEL_ID"
model_reasoning_effort = "medium"
web_search = "cached"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
# 仅当当前模型确实支持该 Personality 选项时启用：
# personality = "pragmatic"

把 YOUR_MODEL_ID 替换为当前环境实际可选的模型 ID。本文核验的四个目录项都列出 medium；如果 /model 没有为你的模型列出该档位，必须改成界面实际提供的值。主块不默认开启 Personality。

这份配置保留了两项日常安全基线：on-request 让越过既有边界的操作仍有批准机会，workspace-write 将默认文件写入限制在工作区内。完整权限组合不在本文展开。

为什么不能只看通用参数表

Codex 配置存在三个不同的事实层级：

证据	适合判断	不适合判断
官方通用配置参考	字段名称、类型和通用说明	某个具体模型当前有哪些档位
Codex CLI 0.145.0 固定 Schema	TOML 结构能否被该版本接受	当前模型一定接受某个推理值
官方内置模型目录或 `codex debug models --bundled`	当前二进制附带的 0.145.0 模型快照与档位	当前账号、Provider 或会话实际可选择哪些模型
当前会话的 `/model`	当前环境实际提供的模型和推理强度选项	未来版本是否保持不变

0.145.0 Schema 将推理强度定义为模型公布的非空字符串。也就是说，字符串通过 Schema 校验，不代表当前模型一定支持；当前 CLI 应通过 /model 同时确认模型与推理强度。

0.145.0 模型目录对照

OpenAI rust-v0.145.0 标签中的 codex-rs/models-manager/models.json 列出以下内置模型能力；本机 codex debug models --bundled 返回相同结果：

模型	当前推理强度	默认值
GPT-5.5	`low`、`medium`、`high`、`xhigh`	`medium`
GPT-5.6 Sol	`low`、`medium`、`high`、`xhigh`、`max`、`ultra`	`low`
GPT-5.6 Terra	`low`、`medium`、`high`、`xhigh`、`max`、`ultra`	`medium`
GPT-5.6 Luna	`low`、`medium`、`high`、`xhigh`、`max`	`medium`

这张表只是 Codex CLI 0.145.0 的内置模型快照，不是所有 OpenAI API 模型的永久枚举。通用配置参考、API 模型指南和 CLI 内置目录属于不同产品层，不能互相覆盖。

截至 2026-07-28，在线通用配置参考的 model_reasoning_effort 类型仍包含 minimal，且未列出 max、ultra；0.145.0 的上述四个内置目录项则都没有 minimal，部分 GPT-5.6 目录项提供 max 或 ultra。这说明通用字段说明不能替代固定版本的模型目录。

codex debug models --bundled 只用于核对当前二进制自带的快照，不能证明账号、第三方 Provider 或当前会话实际开放这些模型。判断当前实际可选项必须以交互界面的 /model 为准。

ultra 也不是单纯比 max 更高。0.145.0 目录说明它在最大推理之外还包含自动任务委派，当前只有 Sol 和 Terra 列出。任务不适合拆分或需要更可预测的单线程过程时，名称更高不代表更合适。

medium 是候选起点，不是统一默认值

主配置采用：

model_reasoning_effort = "medium"

原因是本次核验的四个目录项都提供 medium，而 GPT-5.6 官方 API 指南把 medium 作为平衡质量与速度的起点。但它不是所有模型的默认值：0.145.0 中 Sol 默认 low，GPT-5.5、Terra 和 Luna 默认 medium。实际使用时可以这样调整：

延迟敏感或边界清晰的小任务可以比较 low 与 medium。
只有代表性任务显示质量确有提升时，再选择 high 或 xhigh。
max 留给最困难的质量优先任务；ultra 还包含自动任务委派，不能只理解为更高一级思考量。
minimal、max、ultra 等值仅在 /model 为当前模型真实列出时使用。
比较效果时一次只改模型或推理强度中的一项。

在交互界面输入：

/model

/model 同时用于选择模型和推理强度。界面列出的才是当前 CLI 可选值，不要让模型通过回答文字“自报档位”。

固定到 Codex CLI 0.145.0 时，不要使用 /reasoning：该标签的 CLI 斜杠命令源码没有这个命令，模型和推理强度都通过 /model 选择。通用斜杠命令页面列出的 /reasoning 可能对应其他 Codex 界面或更新版本，不能反推到本文固定版本。

Personality 改为条件配置

固定 Schema 对 personality 只允许三种值：

none | friendly | pragmatic

它不是可以任意填写的风格名称。本机 0.145.0 模型目录显示：

GPT-5.5 的指令模板包含 Personality 占位符，friendly 与 pragmatic 变量均为非空。
GPT-5.6 Sol、Terra、Luna 的指令模板没有该占位符，相应变量也为空。

这个结论只适用于本次版本和目录，不代表 GPT-5.6 永久不支持 Personality。正因为三个 5.6 目录项当前没有对应模板，personality = "pragmatic" 不应成为 GPT-5.6 的通用起步默认。

当前模型支持时，可以取消主配置中的注释，并通过：

/personality

确认可选风格。需要自定义项目回答方式时，把明确规则写进项目 AGENTS.md；需要用户级开发者指令时，使用官方支持的 developer_instructions。不要发明第四种 Personality 值。

Web Search 显式使用 cached

web_search = "cached"

当前官方配置提供四种模式：

模式	行为
`cached`	使用 OpenAI 维护的搜索索引，是普通本地会话的默认模式
`indexed`	仅在搜索索引门控允许时访问外部网页
`live`	获取近期网页内容，与 `--search` 对应
`disabled`	移除 Web Search 工具

普通本地会话默认使用 cached；如果启用 --yolo 或其他 full-access 沙箱设置，官方文档说明默认值可能转为 live。本文显式写入 web_search = "cached"，因此不依赖这一默认差异。确实需要刚发布的版本说明或近期故障信息时，再临时切换 live。无论哪种模式，网页内容都属于不可信外部输入，关键结论仍需核对官方来源。

Web Search 模式不等于 Shell 命令的网络权限。两者属于不同配置边界，不能用搜索成功与否推断子进程是否能联网。

检查实际生效值

保存配置并重启 Codex。以下斜杠命令在 Codex 交互界面中输入，不属于 PowerShell、CMD、Bash 或 Zsh 命令：

/model
/personality

通过 /model 检查当前模型与推理强度，再检查可用 Personality。若界面与文件不同，优先排查启动参数、Profile 或会话内临时覆盖。

需要验证 Web Search 时，可以在自己的可用环境中提出一个必须查询近期官方资料的任务，观察客户端是否出现搜索工具活动以及可访问的来源链接。模型只说“已经联网”不能作为证据。

如果希望在非交互运行中观察结构化事件，下面这条 Codex CLI 命令可在 PowerShell、CMD、Bash 和 Zsh 中使用：

codex exec --ephemeral --json "使用 Web Search 查询当前 Codex CLI 的官方变更记录，给出来源链接"

本文只核对了 0.145.0 帮助中 --ephemeral 和 --json 选项存在，没有实际执行模型或 Web Search 请求。

完成后的检查清单

修改前已备份 config.toml，并知道恢复命令。
model 已替换为当前环境真实可选的 ID。
/model 中当前模型存在配置的 medium，或已改成实际列出的值。
Personality 只在当前模型提供模板时启用。
已显式设置 cached；需要实时内容时才临时切换 live。
保留 on-request + workspace-write 安全基线。

总结

日常配置的关键不是参数多，而是证据层级正确：字段能被 Schema 解析、模型目录公布能力、当前会话实际选择，三者需要分别确认。本文主块以本次四个目录项共同提供的 medium 作为候选起点，显式固定 cached，保留安全基线，并把 Personality 降为条件配置；最终仍以当前模型的 /model 选项和代表性任务结果为准。

FAQ

为什么配置了 medium，界面却没有按预期显示？

先用 /model 查看当前模型实际提供的推理档位，再检查启动参数、Profile 或会话内临时覆盖。Schema 能解析字符串，不代表具体模型一定接受该值。

GPT-5.6 可以直接设置 personality = “pragmatic” 吗？

0.145.0 的三个 GPT-5.6 目录项对应模板为空，因此本文不把它作为通用默认。未来版本可能变化，应以当时的 /personality 和模型目录为准。

ultra 是否就是比 max 更强？

不是简单的强度加一。当前目录说明 ultra 包含自动任务委派，且只有 Sol 和 Terra 列出；是否适合取决于任务能否安全、有效地拆分。

cached 和 live 应该怎样选择？

普通本地会话可显式使用 cached；只有任务明确依赖近期网页信息时再使用 live。full-access 模式可能默认 live，但显式配置不受该差异影响。两种模式的结果都要视为不可信外部输入，并回到官方来源复核。

以上就是Codex CLI常用配置实战：模型、推理强度与Web Search配置和验证的详细内容，更多关于Codex CLI常用配置实战的资料请关注脚本之家其它相关文章！