参考配置样例

config.toml 是 Codex 的长期偏好文件。它适合放模型默认值、沙箱、审批、MCP、profile 和少量 UI 行为。

配置样例不是推荐你照抄。模型名、provider、feature flags 和权限策略都应按当前官方文档、组织要求和项目风险决定。

Config basics

先理解配置加载位置、优先级和 trust 边界。

Config reference

完整 key 去参考页查，不要复制巨型配置。

Sandbox boundaries

配置最重要的是权限边界，而不是功能堆叠。

解决什么

flowchart LR
    Need["repeated behavior"] --> Config["config.toml"]
    Config --> Session["consistent sessions"]
    Session --> Verify["status / small task"]

配置文件解决的是“每次打开 Codex 都希望行为一致”的问题：

默认用哪个模型。
默认是否能改文件。
什么时候需要批准命令。
项目级规则和个人习惯如何分开。
哪些 MCP 或工具默认可用。

不要把配置文件当成“功能大全”。配置越多，排查越难。

最小起点

先从最小可解释配置开始：

model = "your-current-codex-model"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

含义：

model：默认模型。写入前查官方 Models 或组织模型策略。
approval_policy = "on-request"：越过边界时询问。
sandbox_mode = "workspace-write"：允许在工作区内读写，仍保留边界。

这比 danger-full-access 更适合真实项目，也比纯 read-only 更适合日常开发。

配置放哪里

用户级 ~/.codex/config.toml：

个人默认模型。
个人 UI 偏好。
个人常用 MCP。
不依赖某个仓库的习惯。

项目级 .codex/config.toml：

当前仓库的默认 sandbox。
当前仓库需要的 MCP。
当前仓库特定 profile。
团队希望共享的行为。

命令行参数和 --config 只适合一次性覆盖，不适合长期偏好。

先管安全边界

配置里最重要的是两类：

sandbox_mode：Codex 能访问和修改哪里。
approval_policy：Codex 什么时候停下来问你。

常见组合：

保守分析：read-only + on-request。
日常开发：workspace-write + on-request。
高风险全开：danger-full-access + never。

新手不要把高风险全开写进默认配置。只有在一次性、可信、可回滚的自动化环境中，才考虑这种组合。

Profile 切场景

如果有多个固定场景，用 profile，不要反复改同一份配置。

[profiles.review]
sandbox_mode = "read-only"
approval_policy = "on-request"

[profiles.build]
sandbox_mode = "workspace-write"
approval_policy = "on-request"

这样可以把只读审查和动手开发分开。最常见的问题就是在该只读的时候用了动手模式。

不急着配置的项

这些配置官方支持，但新手不必急着写：

自定义 model provider。
复杂网络权限 profile。
OTEL / telemetry。
hooks。
自动审批 reviewer。
大量 MCP server。
自定义 compaction prompt。

等遇到真实问题，再加对应配置。配置应该来自痛点，不应该来自“看起来专业”。

怎么判断生效

改完配置后，用 /status 或启动后的状态信息确认：

当前模型是否符合预期。
sandbox 是否是你想要的模式。
approval policy 是否生效。
项目级配置是否被加载。

再用小任务验证：读文件、改一个测试文件、运行 git status。看它是否在该问你的时候问你，在不该越界时保持边界。

常见坑

整份复制配置样例，结果不知道哪个键影响行为。
把个人偏好写进项目级配置，污染团队仓库。
项目级配置写好后忘记 trust project，导致它没加载。
默认使用 danger-full-access。
配了 MCP 或 provider，却没有配置凭据来源。
把密钥、token 或 auth 文件路径写进可提交配置。