config.toml 保存 Codex 的持久配置。模型和沙盒在这里设，审批策略与 profiles 同样如此，MCP 服务也能写进来，它相当于 CLI 的个人驾驶舱。文件通常放在用户目录下的 .codex/config.toml。

有两处容易混。项目长期规则建议写进仓库里的 AGENTS.md，个人偏好放本机 config.toml，这样团队能共享项目规则，自己又能保留使用习惯。.codex 目录下的 .env 是另一码事，它放的是桌面端或 IDE 扩展启动时需要读的环境变量。桌面端和 VS Code 扩展可能不继承当前终端里的变量，这类值要写进 .env 再重启应用。

写 .env 之前先确认两件事。变量确实是当前入口需要的，别把所有终端变量都复制进去。文件里可能含密钥，截图和提交仓库前必须脱敏。

它管什么

用途	你要决定什么	建议
模型	速度与成本，还有推理深度的取舍	用默认配置起步，复杂任务再临时调整
沙盒	Codex 能读写哪些位置	新手先只读或工作区写入
审批	哪些命令需要你确认	涉及网络，删除，安装和发布时保留审批
profiles	不同任务使用不同组合	准备只读，编码，审查三类
MCP	接入外部工具和知识源	只接可信服务，明确权限范围
环境	传递必要变量或隔离敏感变量	凭据用最小权限，避免写进教程截图

一份最小配置

下面这份示例表达三件事：默认允许在当前工作区写文件，高风险命令仍需要审批，另外保留一个只读 profile 给新仓库分析用。

model = "gpt-5.1-codex-max"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

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

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

实际字段以官方配置参考和你手上的 CLI 版本为准。版本更新较快，抄之前对一眼。

三类常用 profile

只读学习这一档适合打开陌生仓库，生成项目地图，梳理测试命令。配好之后用命令行指定它启动，带上 profile 参数跑 codex，再让它只读分析当前仓库，不要修改文件。

日常编码的配置用来修测试、补文档和小范围实现。启动时切到编码 profile，把范围写清楚，只改某个目录和对应测试文件，改完运行指定的测试命令。

审查这一类落在只读 profile 上就够了。让它 review 当前 diff，优先指出 bug 与回归风险，还有缺失的测试。

三档的差别主要落在沙盒和审批这两行，改起来不复杂。

改完怎么验证

每次改完配置，别直接上复杂任务。先用一个短任务试探，让它说明当前工作区，还有审批策略和准备采用的验证方式，不要修改文件。

接着核对四点。Codex 能不能正确读到当前目录。执行命令前会不会先解释意图。只读或工作区写入的边界有没有被遵守。该触发审批的动作有没有真的弹出来。

配置怎么被用起来

CLI 是最适合练配置的地方，它有三种使用姿势。交互模式进到项目根目录直接跑，适合学习仓库和逐步改代码。一次性任务用 exec 子命令，适合脚本和 CI，还有批量分析。恢复会话续之前的上下文，适合长任务分段推进。

启动参数可以按用途理解。模型选择决定这次任务要更强推理还是更快响应。沙盒设置控制文件系统和网络权限。审批策略决定哪些命令要人工确认。配置覆盖用来对单次任务临时套一个 profile。输出格式用于适配脚本，比如让 exec 输出 Markdown 或 JSON。

参数名和默认值变化很快，以 codex –help 和官方文档为准。

出问题按这张表查

现象	检查方向
配置没生效	文件路径和 TOML 语法，还有 CLI 版本与启动时选的 profile
权限超出预期	sandbox_mode 和 approval_policy 写的是什么
某个命令一直被拒绝	沙盒限制，网络权限，组织策略
MCP 连不上	服务命令和环境变量，还有端口与认证方式
桌面端不继承代理变量	先验证真实代理端口，再把最小变量放进 .env 并重启
切换 provider 后旧会话不可见	先排除桌面端首屏条数限制，再看 provider 元数据
团队成员行为不一致	把项目共同规则写进 AGENTS.md

代理排障有个常见误区，不要先猜端口。先用系统代理设置和带代理参数的 curl 确认端口可用，再往 .env 里写最小变量。

收尾

config.toml 是长期配置，改一次管很久。每次只动一个字段，用一个短任务验证，比一次性抄一大段配置再回头排查省力得多。