OpenAI Codex 系列篇二：config.toml 配置系统详解——模型、Profiles 与功能开关
上一篇〉OpenAI Codex 完全上手指南》我们跑通了安装、登录和第一次对话。但默认行为未必合你口味：想换模型、想少点审批弹窗、想让 CI 里无人值守跑 Codex——这些全都指向同一个答案：config.toml。
这是系列的第二篇，我们把 Codex 的配置系统一次讲透：配置放哪、谁优先、每个常用配置项怎么写，最后给你一份可以直接抄走的完整模板。
一、配置文件放在哪：两级结构
Codex 的配置是 TOML 格式，分两个层级：
| 级别 | 路径 | 适用场景 |
|---|---|---|
| 用户级 | ~/.codex/config.toml | 个人默认值，所有项目共用 |
| 项目级 | .codex/config.toml | 随仓库共享给团队的项目约定 |
两个细节值得注意：
- 项目级配置可以放在仓库根目录，也可以放在子目录，多级目录时就近优先；
- 项目级配置只在受信项目里才会加载。不被信任的仓库会直接跳过
.codex/层级——这个设计是防身的：别人提交进仓库的配置文件，不能替你悄悄"开权限"。
在 IDE 插件里找配置文件：点齿轮图标 → Codex Settings → Open config.toml。
二、六层优先级：配置不生效时的排查地图
同一个配置项可能同时出现在多个地方，Codex 按下面的顺序决定最终生效值（从高到低）：
- CLI 标志和
--config：命令行临时覆盖，只对本次会话生效 - Profile：通过
--profile <名称>激活的场景预设 - 项目配置：距工作目录最近的优先，仅受信项目生效
- 用户配置：
~/.codex/config.toml - 系统配置：
/etc/codex/config.toml（Unix，管理员下发） - 内置默认值：什么都没配时的出厂行为
所以排查"配置不生效"的思路就一句话：先想想它是不是被更具体、更靠上的一层覆盖了。比如你在项目里写了sandbox_mode = "read-only"，但命令行里带了--sandbox workspace-write，赢的一定是命令行。
三、模型设置：换模型、调推理强度
最常改的一组配置，五项全覆盖：
| 配置项 | 说明 |
|---|---|
model | 使用的模型，如"gpt-5-codex" |
model_provider | 模型提供商，默认openai |
model_context_window | 可用的上下文 Token 数 |
model_reasoning_effort | 推理强度，从minimal到xhigh |
model_reasoning_summary | 推理摘要详细程度：auto/concise/detailed/none |
model = "gpt-5-codex" model_context_window = 200000 # 上下文 Token 上限 model_reasoning_effort = "high" # 简单任务调低，复杂任务拉满 model_reasoning_summary = "concise" # 想看详细推理过程改 detailed四、沙箱与审批：安全的三道闸门
Codex 的安全模型由两个维度组成。
沙箱模式sandbox_mode，决定文件系统能碰什么：
read-only：只读，最安全workspace-write：可写工作区，日常推荐danger-full-access：完全放开，慎用
审批策略approval_policy，决定什么事要问你：
untrusted：不可信操作都要审批on-request：模型按需请求审批never：从不询问（配 CI 用）
沙箱还能继续微调：
sandbox_mode = "workspace-write" [sandbox_workspace_write] writable_roots = ["/tmp/build-output"] # 额外允许写入的目录 network_access = true # 是否允许出站网络访问我的建议：平时workspace-write+on-request；跑批处理/CI 时再考虑never，且永远不要在danger-full-access下关审批。
五、功能开关 [features]：提前解锁实验能力
一些还没默认放开的能力，统一收在[features]表里：
| 功能 | 说明 |
|---|---|
shell_tool | 默认 Shell 命令工具（稳定，默认开启） |
web_search | 网络搜索：disabled/cached/live |
multi_agent | 多智能体协作工具（实验性） |
unified_exec | 带 PTY 支持的执行工具（Beta） |
apply_patch_freeform | 暴露自由格式 Patch 工具 |
[features] web_search = "live" # 让 Codex 能联网查资料 multi_agent = true # 复杂任务拆给多个子智能体六、MCP 服务器：给 Codex 接外部工具
MCP 是 Codex 连接外部工具的标准协议（系列第四篇会专门展开），配置写法分两类。
STDIO 服务器（本地进程，最常见）：
[mcp_servers.my-server] command = "npx" args = ["-y", "@modelcontextprotocol/server-filesystem", "/path"] env = { API_KEY = "..." } cwd = "/working/dir" startup_timeout_sec = 30HTTP 服务器（远程）：
[mcp_servers.my-http-server] url = "https://mcp.example.com/server" bearer_token_env_var = "MY_TOKEN_ENV"每个服务器还有通用选项：enabled（总开关）、required（启动失败是否终止 Codex）、enabled_tools/disabled_tools（工具黑白名单）、tool_timeout_sec（单次调用超时）。
七、Shell 环境与界面细节
环境变量隔离是很多人忽略的安全点，默认继承给 Shell 命令的变量集可以精细控制：
[shell_environment_policy] inherit = "core" # all 全继承 | core 核心变量 | none 不继承 set = { MY_VAR = "value" }机器上有 API Key、云凭证这类敏感变量时，别用inherit = "all"。
界面行为也有一些可调项：
| 配置项 | 说明 |
|---|---|
personality | 沟通风格：none/friendly/pragmatic |
tui.animations | 终端界面动画开关 |
tui.notifications | 通知行为控制 |
| `file_opener | 引用跳转用的编辑器：vscode/cursor/windsurf等 |
allow_login_shell | 开启 login-shell 语义 |
八、历史记录与上下文压缩
长会话必看的三项：
| 配置项 | 说明 |
|---|---|
history.persistence | 对话记录：save-all（全部保存）或none（不保存） |
model_auto_compact_token_limit | 上下文自动压缩的触发阈值 |
compact_prompt | 覆盖默认的压缩提示词 |
history.persistence = "save-all" model_auto_compact_token_limit = 100000 # 快到上下文上限前自动压缩九、Profile：一套配置多个场景
Profile 解决的是"日常一套配置、CI 另一套配置"的切换问题。在配置文件里定义多个命名 Profile，运行时指名调用：
[profiles.ci] approval_policy = "never" sandbox_mode = "workspace-write" model = "gpt-5.1-codex"codex--profileci"执行代码审查"关键特性：Profile 中写了的项覆盖默认值，没写的项继续用全局配置——所以只写差异部分就行。你可以为"日常开发"“CI 无人值守”"只读审计"各准备一个 Profile，一条命令切换。
十、企业管控：requirements.toml 只能收紧不能放宽
团队/企业管理员可以用requirements.toml（/etc/codex/requirements.toml或组织级分发）锁定安全敏感设置：
allowed_approval_policies = ["on-request", "untrusted"] allowed_sandbox_modes = ["read-only", "workspace-write"] allowed_web_search_modes = ["disabled", "cached"]注意它的方向性：只能收紧权限，不能放宽——管理员无法用它给你多开权限，只能限制。个人config.toml再怎么写也越不过这条线。
十一、拿来即用：一份完整配置模板
把上面所有内容拼起来，这是一份可直接抄走再改的模板：
# ~/.codex/config.toml # ── 顶层键（必须写在所有 [表] 之前）── model = "gpt-5-codex" model_reasoning_effort = "high" model_reasoning_summary = "concise" sandbox_mode = "workspace-write" approval_policy = "on-request" history.persistence = "save-all" file_opener = "vscode" personality = "pragmatic" # ── 各个配置表 ── [sandbox_workspace_write] network_access = true [features] web_search = "live" [shell_environment_policy] inherit = "core" [profiles.ci] approval_policy = "never" sandbox_mode = "workspace-write" [profiles.audit] sandbox_mode = "read-only" approval_policy = "untrusted"一个容易踩的 TOML 坑：顶层键必须写在所有[表]头之前。TOML 规定表头之后的裸键都属于那个表——把model = "..."写到[features]下面，它就不是模型配置了，轻则静默失效，重则启动报错。
十二、写在最后
配置系统是 Codex 从"能用"到"好用"的分水岭，三个最值得先做的动作：
- 把个人默认值写进
~/.codex/config.toml（模型 + 审批策略）； - 给 CI 准备一个
approval_policy = "never"的 Profile； - 在敏感机器上把
shell_environment_policy.inherit改成core。
下一篇我们讲AGENTS.md 记忆工程——怎么让 Codex 记住你的项目约定，不用每次重复交代。
系列目录：
- 篇一：OpenAI Codex 完全上手指南
- 篇二：config.toml 配置系统详解（本篇）
- 篇三：AGENTS.md 记忆工程——让 AI 记住你的项目
- 篇四：MCP 与 Skills——给 Codex 装上工具箱
- 篇五：CI/CD 深度——无人值守的自动化工作流
- 篇六：Codex App 体验——桌面端能打吗
/LALR原理、冲突消解与错误恢复)
查询的奥秘)
