参考配置样例

用少量 config.toml 配置让 Codex 行为稳定，而不是复制一整份巨型配置。

config.toml 是 Codex 的长期偏好文件。它适合放模型默认值、沙箱、审批、MCP、profile 和少量 UI 行为。新手不应该复制一整份完整配置表；真正有价值的是先理解哪些配置会影响安全、稳定性和日常体验。

官方配置参考说明：用户级配置在 `~/.codex/config.toml`，项目级覆盖可以放在 `.codex/config.toml`；项目级配置只会在你信任该项目时加载。

先理解它解决什么问题

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

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

不要把配置文件当成“功能大全”。配置越多，排查越难。新手先写最小可解释配置。

新手推荐起点

先从这份很小的配置开始：

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

含义：

model：默认使用的模型。
approval_policy = "on-request"：Codex 在需要越过边界时问你。
sandbox_mode = "workspace-write"：允许在工作区内读写，仍保留边界。

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

配置放哪里

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

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

项目级 .codex/config.toml：

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

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

先管住安全边界

配置里最重要的是两类：

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 是否生效。
项目级配置是否被加载。

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

新手常见坑

整份复制配置样例，结果不知道哪个键影响了行为。
把个人偏好写进项目级配置，污染团队仓库。
把项目级配置写好后忘记信任项目，导致它没加载。
默认使用 danger-full-access，后续误操作成本很高。
配了 MCP 或 provider，却没有配置凭据来源。

参考官方文档：

最近更新：2026年5月4日

On this page