Codex CLI config.toml 完全指南：模型、审批、MCP 与分层配置
Codex CLI 的行为中心是 ~/.codex/config.toml：model 选模型、approval_policy 管审批、sandbox_mode 管边界、mcp_servers 接工具、profiles 做场景切换。本文按 codex 源码的 ConfigToml 结构把核心键位与分层机制讲清楚。
操作步骤
建文件
创建或编辑 ~/.codex/config.toml；项目级覆盖放 <repo>/.codex/config.toml。
选模型与行为
写 model = "gpt-6-astra"，按需加 model_reasoning_effort 与 model_verbosity。
定安全边界
写 sandbox_mode = "workspace-write" 与 approval_policy = "on-request"（无人值守用 "never"）。
接 MCP（可选）
加 [mcp_servers.<name>] 表配 command/args 或 url——详见本站 MCP 配置篇。
Codex CLI 的行为中心是 ~/.codex/config.toml——一个 TOML 文件，决定它用哪个模型、能碰哪些文件、接哪些工具、何时停下来问你。官方文档站把配置拆成 basic/advanced/reference 三页，本文按 codex-rs 源码里 ConfigToml 结构的字段给出一张可信的键位地图。
1. 文件位置与分层
- 用户级：
~/.codex/config.toml——全局默认 - 项目级：仓库根的
.codex/config.toml——同名键覆盖用户级 - 管理员级：
requirements.toml——托管/强制约束层（如allow_managed_hooks_only = true让用户与项目级 hooks 失效、只保留托管 hooks）
这个分层结构意味着：个人偏好放用户级，项目规则放项目级（会进 git），企业策略放 requirements.toml。
2. 模型与推理键位
model = "gpt-6-astra"
model_provider = "openai"
model_reasoning_effort = "high"
model_verbosity = "medium"
model：模型名model_provider：指向[model_providers]表里的 provider 键——可以注册自定义 provider 走别的通道model_reasoning_effort：推理深度档位model_reasoning_summary/model_verbosity：推理摘要与输出冗长度model_context_window/model_auto_compact_token_limit：上下文窗口与自动压缩阈值（一般不用动）
3. 安全双轴
sandbox_mode = "workspace-write"
approval_policy = "on-request"
sandbox_mode 管文件与网络边界（read-only / workspace-write / external-sandbox / danger-full-access），approval_policy 管何时停下来问你（on-request / on-failure / granular / never）。两个键的完整语义见本站沙箱篇——这里只提醒一点：它们互相独立，组合使用，不存在"一个开关全管"。
4. MCP 与 profiles
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
[profiles.ci]
model = "gpt-6-astra"
approval_policy = "never"
sandbox_mode = "workspace-write"
[mcp_servers.<name>]：声明 MCP 服务器（完整字段见本站 MCP 篇）[profiles.<name>]：命名配置档，把一组键打包成场景；用profile = "ci"或 CLI--profile切换
profiles 是 config.toml 里最被低估的机制——把"写代码"、"CI 批跑"、"只读审查"做成三个档，比每次改文件优雅得多。
5. 常见错误
- 把 requirements.toml 的键写进 config.toml：
allow_managed_hooks_only只在管理员层生效，写错位置静默无效 - profiles 忘了切换：定义了
[profiles.ci]但从不传--profile ci，等于没配 - 秘密明文落盘：API key 类值优先走
*_env_var形态，项目级文件会进 git - 以为 model_provider 是 URL：它是 provider 键名，自定义通道要在
[model_providers]里先注册
6. 下一步
关键要点
- 主文件 ~/.codex/config.toml；项目级 .codex/config.toml 覆盖同名键
- model / model_provider 选模型与提供方；model_reasoning_effort 与 model_verbosity 调推理与输出长度
- approval_policy + sandbox_mode 是安全双轴（详见沙箱篇）
- [mcp_servers.<name>] 声明 MCP 服务器；[profiles.<name>] 定义命名配置档
- requirements.toml 是管理员分层：allow_managed_hooks_only = true 只放行托管 hooks
常见问题
官方参考
相关文章
Codex 预览线从 0.167 直接跳到 0.168：四天四版、无稳定版收尾（2026）
Codex 的 0.167 预览线在 GitHub 上走到 alpha.5 后没有等来稳定版——npm 的 alpha dist-tag 已于 11 月 4 日指向 0.168.0-alpha.1，而 PyPI 的 openai-codex 仍停在 0.163.0，渠道差距进一步拉大。
阅读全文Codex CLI 0.166.0 稳定版发布：GPT-6.1 Terra 扩至 Vertex AI 与 Bedrock 目录、transcript 键盘选择与 doctor --network-only
0.166.0 于 2026-10-29T19:47 UTC 转stable：GPT-6.1 Terra 目录覆盖扩至 bundled、Vertex AI 与 Bedrock 三目录，新增 transcript 键盘选择与集成搜索、codex queue --resume、codex doctor --network-only。PyPI 缺口扩至三版。
阅读全文Codex CLI 0.164–0.165 发布线解读：GPT-6.1 Terra 进目录、Vertex AI provider、/presets 与 memory v2
0.163 之后的两个稳定版一起补齐：0.164.0（10-23）带来 /presets、内联 /model 与 /permissions；0.165.0（10-27）加入内置 Vertex AI provider，并把 GPT-6.1 Terra 写进模型目录。逐项对照官方 release notes。
阅读全文订阅 GPTMap Weekly
每周一封邮件，精选 OpenAI 重要更新、深度解读与最佳实践。无广告，可随时退订。
提交后将在新标签页打开 Buttondown 完成订阅确认。