Codex 配置文件 config.toml 详解

这篇适合谁、读完能做到什么

这篇适合已经装好 Codex CLI 或 IDE 扩展、想把默认行为调成自己习惯的人。读完你应该知道配置文件放在哪里，多个配置层怎么叠加，几个常用的键（模型、审批、沙箱、网页搜索）怎么写，以及功能开关怎么打开。^[1]

配置文件放在哪里

用户级配置是 ~/.codex/config.toml。^[1] 如果只想让某个项目或子目录生效，就在仓库里加一个 .codex/config.toml。^[1] 项目级的 .codex/ 配置只有在你信任这个项目时才会加载。^[1]

在 IDE 扩展里，可以点右上角的齿轮图标，再选择 Codex Settings > Open config.toml，直接打开这个文件。^[1] CLI 和 IDE 扩展共用同一套配置层，所以改动在两边都会生效。^[1]

配置的优先级

Codex 按下面的顺序取值，越靠前优先级越高：^[1]

1. 命令行参数和 --config 覆盖。
2. 项目配置 .codex/config.toml：从项目根目录往下逐级查找，离当前工作目录最近的优先，且只对受信任的项目生效。
3. 通过 --profile 选中的 profile 文件，路径是 ~/.codex/profile-name.config.toml。
4. 用户配置 ~/.codex/config.toml。
5. 登录的工作区下发的云端托管默认配置（如果有）。
6. 系统配置，Unix 上是 /etc/codex/config.toml。
7. 内置默认值。

如果把一个项目标记为不受信任，Codex 会跳过项目级的 .codex/ 配置层，包括项目本地的配置、hooks 和 rules；用户级和系统级配置仍然会加载。^[1]

一次性的临时覆盖用 -c 或 --config，例如 codex -c log_dir=./.codex-log。^[1]

常用配置项

默认模型、审批和沙箱

model 键设置默认模型，配置文件也可以设置默认的 provider。^[1]

approval_policy 控制 Codex 在运行它生成的命令之前，什么时候停下来问你。文档里的示例值是 on-request。^[1]

sandbox_mode 决定 Codex 执行命令时能访问多少文件系统和网络。文档里的示例值是 workspace-write。^[1]

权限还可以打包成命名的 profile。内置的有 :read-only、:workspace 和 :danger-full-access 三个；自定义的写在 [permissions.<name>] 表里，再用 default_permissions 选用。^[1]

旧的 approval_policy = "untrusted" 已经退役。如果配置里还在用它，需要按官方说明迁移。^[1]

网页搜索

web_search 有四个取值：^[1]

• cached：默认值，从网页搜索缓存里取结果。
• indexed：只有搜索索引放行某个请求时，才允许访问外部网页。
• live：直接获取网上最新的数据，等同于命令行的 --search。
• disabled：关闭网页搜索工具。

缓存是 OpenAI 维护的网页结果索引，返回的是预先建好索引的结果，而不是现抓的网页。文档说，这样能减少来自实时网页内容的提示注入风险。^[1] 但文档同时要求把网页结果当作不可信内容对待。^[1] 如果你用 --yolo 或其他完全访问的沙箱设置，网页搜索会默认切换到实时结果。^[1]

推理强度和沟通风格

model_reasoning_effort 调整模型在支持时使用的推理强度，文档示例值是 medium。^[1]

personality = "none" 会去掉模型内置指令里的 Personality 部分，但不会改变你显式指定的自定义基础指令。^[1] 旧的 friendly 和 pragmatic 值已经不再决定风格，/personality 命令也已经不再提供。^[1]

命令环境变量

[shell_environment_policy] 控制 Codex 传给它所启动命令的环境变量。ignore_default_excludes 默认是 true，会跳过对名字里含 KEY、SECRET 或 TOKEN 的变量的自动过滤；设成 false，才会开启这种过滤。^[1]

日志目录

log_dir 指定 Codex 写本地日志的目录。显式设置它之后，还会开启可选的纯文本 TUI 日志 codex-tui.log，写在同一目录里。^[1]

功能开关

[features] 表用来开关可选的和实验性的功能。在配置里写 feature_name = true 就能开启，命令行里运行 codex --enable feature_name 效果相同。关闭时把对应的键设成 false。^[1]

文档列出的常用开关里，hooks 和 multi_agent 默认开启，memories 默认关闭，三者都标为 Stable。^[1] 成熟度标签有 Experimental、Beta 和 Stable。表里只列了常用的、面向用户的开关，不是全部功能。^[1]

Windows 用户的情况略有不同。文档建议在设备和策略允许时优先用 MXC，同时把旧的实现设成回退项：^[1]

[windows]
sandbox = "elevated" # Legacy fallback

[features]
prefer_mxc = true

unelevated 只在提权设置不可用、并且组织策略允许时才用。^[1]

常见问题

改了配置却没生效，先看它有没有被更高优先级的命令行参数或项目配置覆盖，再看当前项目是否受信任。^[1]

限制

在托管机器上，组织可以用 requirements.toml 强制约束，例如禁止 approval_policy = "never"。这时配置值只是默认值，约束优先。^[1]

下一步

本文只覆盖基础部分。配置参考和高级配置两个页面列出了更多键，需要细节时，以那里为准。^[1]