6. config.toml 配置基础

如果你每次开 Codex 都手动 /model 切模型、/permissions 调权限、临时敲 --search 开联网，一天下来同样的动作要重复好几遍—那你该花十分钟把 config.toml 写明白了。

它不是给高手炫技的，是给所有嫌麻烦的人省事的。

config.toml 是什么

config.toml 是 Codex 的「行为旋钮总成」，用 TOML 格式管模型、审批、沙箱、MCP、功能开关这些工具行为。

它跟 AGENTS.md 是两套东西，别搞混。打个比方：AGENTS.md 像手套箱里那本驾驶手册—写的是给人看的自然语言叮嘱；config.toml 是中控台上那一排实体旋钮—一个个明确的、机器照着执行的开关。前者管记住什么，后者管怎么干活。

TOML 格式长这样：顶层是 key = value，分组用 [表名]：

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

文件放哪

config.toml 至少有两个落脚点：一份在你主目录（管全局），一份可以塞进项目里（只管这个项目）。

层级	文件位置	影响谁	该放什么
用户级	~/.codex/config.toml	你，跨所有项目	个人默认：惯用模型、默认权限、MCP
项目级	<repo>/.codex/config.toml	在这个仓库里干活时	项目专属：该用的模型、该有的沙箱档

~/.codex 目录

主目录那份的路径是固定的：~/.codex/config.toml。这个 ~/.codex 目录叫 CODEX_HOME，是 Codex 存所有本地东西的地方—配置、登录凭据、历史记录、日志。文件不存在就自己建一个，Codex 读得到。

项目级配置有个安全限制

项目级那份要放进仓库里的 .codex/ 子目录。它只在你在这个项目里干活时才叠加上来。

判断一条配置该放哪，脑子里过一个问题就够：「这条只跟我这个人有关，还是跟这个项目有关？」

• 「我所有项目都想要」-> 用户级
• 「就这个项目该这么干」-> 项目级

6 级优先级

两处都能写同一个键，那谁说了算？这就是优先级要管的事。实际不止两层，一共能叠到六层，从高到低：

优先级	来源	说人话
1（最高）	命令行参数 / --config	你这次启动临时拍的板，只管这一次
2	项目级 <repo>/.codex/config.toml	这个项目的设置（信任时才算）
3	--profile 选的预设档	你切到的那套命名配置
4	用户级 ~/.codex/config.toml	你的全局默认
5	系统级 /etc/codex/config.toml	管理员给整机定的
6（最低）	内置默认值	你啥都没写时 Codex 自带的

一句话记牢：越「具体到当下」的越大，越「全局兜底」的越小。 命令行（就这一次）压项目（就这项目），项目压预设档，预设档压用户全局，用户压系统，系统压内置兜底。

项目级配置的安全禁区

项目级虽然优先级高于用户级，但有一类键是例外—你在项目级 .codex/config.toml 里写它们，Codex 直接无视，还会打一行警告。

为啥拦？想想看：要是一个陌生仓库的 .codex/config.toml 能偷偷改你连的模型服务地址、改你的认证方式、塞个通知命令在你机器上跑—那就太危险了。

这些键只认用户级：

这类键	管什么	为啥只能写用户级
model_provider / model_providers	模型服务商、接入地址	防陌生仓库把你的请求引到别处
openai_base_url / chatgpt_base_url	内置服务的基础 URL	改 URL 等于改数据去向
notify	任务完成时跑的外部命令	防仓库在你机器上偷偷执行命令
otel	遥测 / 日志导出	防把你的运行数据外发
profile / profiles	选哪套配置预设	配置档要靠 --profile 选，不让仓库替你选

常见配置项

config.toml 支持的键有上百个，但 90% 的人日常碰的就这么几个。

model：默认用哪个模型

model = "gpt-5.6"

不指定就走 Codex 内置默认。写进去就是把你惯用的模型定成默认，不用每次 /model 临时切。

approval_policy：啥时候停下来问你

approval_policy = "on-request"

三种值：

• untrusted：不在可信集合里的命令，跑之前先问
• on-request：默认在沙箱里干，需要出圈时才停下来问（最常用）
• never：不弹审批，闷头干（自动化常用）

sandbox_mode：能动多大

sandbox_mode = "workspace-write"

三种值：

• read-only：不能改文件、不能联网
• workspace-write：仅限工作区内可写（日常最常用）
• danger-full-access：全机器可写、能联网（慎用）

web_search：联网搜索模式

web_search = "cached"

这个键有个反直觉的默认。Codex 默认开着联网搜索，但用的是 cached（缓存）模式—查的是 OpenAI 维护的一个网页索引，返回的是预先收录好的结果，不是当场去抓实时网页。

三种值：

web_search = "cached"    # 默认：走缓存索引
web_search = "live"      # 实时抓取，等价于命令行 --search
web_search = "disabled"  # 彻底关掉搜索工具

一份最小配置示例

把上面几个合在一起，这就是一份能用的最小配置：

# ~/.codex/config.toml
model = "gpt-5.6"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"

TOML 语法的一个坑

写 config.toml 最常见的语法错：所有顶层的 key = value（根键）必须写在所有 [表] 的前面。

TOML 官方明确规定：Root keys must appear before tables.

看个对错对比：

错的（根键混在表后面）：

[features]
memories = true
model = "gpt-5.6"  # 这行会报错

对的（根键全在前、表全在后）：

model = "gpt-5.6"
approval_policy = "on-request"

[features]
memories = true

记法：先写所有不带 [] 的单行键，再写所有 [表] 段。 顺序反了，TOML 解析直接报错。

验证配置生效

写完配置，进会话用 /status 确认一下：

codex

进去后敲：

/status

在弹出的状态信息里，能看到当前会话用的模型、审批策略等—和你刚写的对得上，说明 config.toml 被成功读到了。

小结

• config.toml 是什么：行为旋钮总成，管模型、审批、沙箱等功能行为，和 AGENTS.md 分工不同
• 文件放哪：用户级 ~/.codex/config.toml（管所有项目）、项目级 <repo>/.codex/config.toml（只管这个项目、信任才加载）
• 6 级优先级：命令行 > 项目 > profile > 用户 > 系统 > 内置，越具体越大
• 安全限制：model_provider、notify、otel、profile 等机器级键只认用户级
• 常见配置项：model、approval_policy、sandbox_mode、web_search（默认 cached 不是实时）
• TOML 语法：根键必须写在所有 [表] 前面

下一章讲高级配置—模型推理强度、上下文窗口、实验性功能开关这些更深层的旋钮。