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 Cloud 设置指南：环境配置、云端任务与 codex cloud 命令
Codex Cloud（官方称 Codex Web）是跑在云端的 Codex 形态：任务在按 GitHub 仓库组织的云端环境里执行，本地 CLI 可以用 codex cloud 子命令提交、查看并把 diff 拉回本地。本文按 openai/codex 仓库 rust-v0.156.1 源码把设置路径与命令面讲清。
阅读全文Codex CLI 沙箱模式详解：sandbox_mode 与 approval_policy 怎么配
Codex CLI 的沙箱不是开关而是四个档位：read-only、workspace-write、danger-full-access、external-sandbox，配上独立的 approval_policy 轴。本文按 Codex 源码里的枚举定义逐项讲清每个取值、子选项和组合建议。
阅读全文Codex CLI 0.155 发布解读：/voice 实验性语音、Touch ID 验证 MCP 请求与 0.155.1 回退
Codex CLI 0.155.0/0.155.1 连发：实验性 /voice 语音对话（/experimental 开启）、TUI 流式 reasoning summaries、Touch ID 验证 MCP 请求、daemon 更新计划、Bedrock 凭据命令；0.155.1 把 reasoning summary 默认值恢复为 none。逐项对照 release notes 拆解。
阅读全文订阅 GPTMap Weekly
每周一封邮件，精选 OpenAI 重要更新、深度解读与最佳实践。无广告，可随时退订。
提交后将在新标签页打开 Buttondown 完成订阅确认。