Codex 配置别再瞎改了：config.toml 一文搞清楚哪些配置真的有用

如果你也在用 Codex CLI，大概率遇到过这些情况：换了一个 API 节点，之前好不容易配好的 MCP 直接消失了；面对 config.toml 里密密麻麻的字段，根本不知道哪些是官方真正支持的，哪些只是网上流传的旧写法；想把自己的工作环境固定下来，结果越配越乱。

明明代码能跑，但你始终不知道：当前到底哪些配置真正生效。

最近，我专门花了一整天时间，把这件事从头到尾梳理了一遍。结论先说：

Codex 的 config.toml 不是“字段越多越高级”，而是“把真正稳定、长期有价值的配置固定下来”。

如果你也在 Windows 上用 Codex，而且还在被 MCP 配置和第三方 API 渠道切换折磨，这篇文章会比较有参考价值。

一、核心误区：`config.toml` 真的不是只管 MCP

很多人一看到 config.toml，第一反应就是“往里面塞 MCP 配置”。这其实是个误区。

根据官方文档，config.toml 管理的范围很广，至少覆盖以下几类：

模型与 provider
审批策略
沙箱权限
网页搜索
MCP 服务
项目 trust 配置
日志与历史
Windows 平台相关行为
Profile、Agent、Skill 等扩展能力

也就是说，MCP 只是其中一部分。真正麻烦的，不是“能配多少”，而是：

哪些配置应该跟着渠道变化，哪些配置应该稳定保留。

如果不把这两类分开，配置文件迟早会变成一团乱麻。

二、拨云见日：最核心的 3 个底层字段

在网上抄模板最大的风险，就是把“工具自动生成的临时字段”当成了“官方核心字段”。我后来把字段分成“官方确认”“实践推荐”“不建议依赖”三类后，得出了最应该优先理解的 3 个基础字段：

model = "gpt-5.4"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

为什么是它们？因为这三个字段决定了你使用 Codex 的核心体验：

默认用什么模型；
什么时候需要你审批；
技术上到底拥有什么权限。

它们不是“官方必填”，但几乎是最值得优先固定的基础项。

三、API 切换避坑：不要试图保住整个配置文件

我在本地折腾时踩过最大的坑就是：第三方 API 切换工具在切换渠道时，会直接重写 C:\Users\用户名\.codex\config.toml 文件。

这会导致什么后果？

MCP 没了；
trusted project 没了；
自己加的行为项也丢了；
Windows 下的一些固定设置被覆盖了。

后来我把思路彻底改了：

不再试图“保住整个 `config.toml`”

而是改成两层：

让切换工具负责切换渠道
比如 provider、base_url、当前模型、渠道名。
让 overlay 负责补回固定配置
比如 MCP、Windows 沙箱、日志目录、历史记录、固定行为项。

理清这个边界之后，配置文件才真正变得可维护。

四、抄作业时间：哪些配置值得长期固定？

基于 overlay 思路，我最后把固定配置分成几组来看。

1. 渠道基础配置

这一组主要决定你当前默认走哪个 provider、哪个模型、以及连接地址是什么：

model_provider = "ccs"
model = "gpt-5.4"
preferred_auth_method = "apikey"
disable_response_storage = true
network_access = "enabled"
model_reasoning_effort = "medium"

[model_providers.ccs]
name = "替换成站点名称"
base_url = "替换成站点地址"
wire_api = "responses"
requires_openai_auth = true

这部分通常会随着 API 渠道切换而变化，所以更适合让切换工具接管。

2. 行为与体验配置

这组配置的目标是减少打扰、统一工作流风格：

web_search = "disabled"              # 禁用内置搜索，避免行为漂移
approval_policy = "never"            # 不再频繁弹窗审批
sandbox_mode = "danger-full-access"  # 高权限沙箱
allow_login_shell = true              # shell 环境更贴近日常终端
log_dir = "E:\\WorkCodex\\logs\\codex" # 集中收口日志（替换成你电脑上的地址）
model_reasoning_summary = "auto"
model_verbosity = "medium"
hide_agent_reasoning = false
personality = "pragmatic"            # 偏务实的回复风格

这部分适合长期固定，因为它定义的是 Codex 的默认行为方式，而不是某一个 API 渠道的信息。

3. 历史记录配置

如果你希望历史尽量保留，而不是很快被滚动淘汰，可以这样设置：

[history]
persistence = "save-all"
max_bytes = 52428800

我最后给自己设的是 50MB。原因很简单：

我经常多项目切换；
经常排查配置；
经常调 MCP；
对话长度也比较长。

10MB 不是不能用，但滚动淘汰会更快。50MB 对本地环境来说更稳。

4. MCP 与项目配置

这一组是我认为最不能丢的：

[projects.'E:\WorkCodex']   # 根据你自己的实际工作文件夹进行调整
trust_level = "trusted"

[projects.'E:\WorkCherry']   # 根据你自己的实际工作文件夹进行调整
trust_level = "trusted"

[notice.model_migrations]
"gpt-5.1-codex" = "gpt-5.3-codex"
"gpt-5.3-codex" = "gpt-5.4"

[windows]
sandbox = "elevated"

我的固定 MCP 目前有 4 个：

context7
brave-search
chrome-devtools
memory

如果你经常在固定项目下工作，trust_level = "trusted"`` 这类配置非常值得保留，因为它会直接影响项目级 .codex/` 配置是否生效。

而 windows.sandbox = "elevated" 这类配置，对依赖 PowerShell、本地脚本和 MCP 工具链的人也很实用。

五、避坑指南：这些别一上来就写死

1. 别把 `[features]` 全写满

很多人看到 feature 就忍不住想“配全”。但这里面混着 stable、experimental 和 deprecated 项。

如果你不了解每一项的语义，直接全写死，升级时很容易出问题。更稳妥的做法是：只覆盖你明确需要改动的项。

2. 拒绝明文硬编码密钥

MCP 配置里最该稳定的是命令、参数、超时和环境变量读取方式，而不是把 key 直接写进 config.toml。

3. 不要把工具生成字段误当成官方核心字段

有些字段当前环境里确实存在、也确实有效，但未必适合作为长期模板的核心结构。这个边界最好提前分清。

六、终极考验：如何验证配置真的生效了？

当前版本的 Codex CLI 有个现实问题：它没有类似 show-config 这样直接打印最终生效配置的命令。

所以我最后采用的是两层验证：

第一层：看 live config

直接检查：

C:\Users\用户名\.codex\config.toml

确认这些配置确实被写进去了。

第二层：做“配置体检”

我后来给自己的切换工具加了一个“配置体检”入口，每次切完直接检查：

当前渠道；
固定行为配置；
4 个 MCP；
trusted projects；
notice.model_migrations；
windows.sandbox。

这样做的好处是：不用再用肉眼翻半天配置文件。

七、如果你也想把自己的 Codex 配明白，我建议按这个顺序来

第一步：先别追求“全字段模板”

先把最关键的几项定住：

model
approval_policy
sandbox_mode

第二步：把 MCP 固定下来

你真正长期要用的 MCP，不要让它跟着 API 切换一起丢失。

第三步：把“会变的”和“不会变的”分开

渠道基础配置 → 交给 API 切换工具
固定环境配置 → 交给 overlay

第四步：给自己留一个验证入口

不要只相信“我记得刚才配过”。最好给自己留一个固定清单，或者干脆做一个配置体检脚本。

总结

配置管理本质上不是“多写”，而是“分层”。

什么时候该用默认值，什么时候交给切换工具，什么时候放进 overlay 固定保留，这几个边界只要理顺了，Codex 才会从“勉强能用”进化为“稳定好用”。

如果你最近也在折腾 Codex CLI、MCP、第三方 API 切换，或者正在整理自己的本地工具链，希望这篇文章能帮你把 config.toml 这件事彻底想明白。

好了，今天的分享就到这里。
如果你还有疑问，欢迎在评论区留言。

关注 AI杨侦探，带你用更简单的方式，搞懂更复杂的技术。