把 Codex 调成适合自己的工作方式：config.toml 配置指南
如果说 AGENTS.md 是项目工作守则，那么 config.toml 就是 Codex 的个人驾驶舱。
模型、沙盒、审批、profiles 和 MCP 等长期偏好，都可以集中保存在这里。
常见位置是：
~/.codex/config.toml
三类配置不要混在一起
项目规则：放进 AGENTS.md
适合团队共享：
- 项目结构；
- 测试命令；
- 代码规范；
- 目录边界；
- 安全和交付要求。
个人行为：放进 config.toml
适合本机保存：
- 默认模型偏好；
- 沙盒与审批组合；
- 常用 profiles；
- 个人 MCP 服务；
- 本地工具配置。
启动变量：放进环境或 ~/.codex/.env
Desktop 或 IDE 有时不会继承当前 shell 环境。经过确认的代理、区域和 provider 变量，可以放入专用环境文件。
但环境文件可能包含 secret，不能截图、提交仓库或复制到公开日志。
从最小配置开始
一份简单配置可以只表达三件事：
approval_policy = "on-request"
sandbox_mode = "workspace-write"
[profiles.readonly]
approval_policy = "on-request"
sandbox_mode = "read-only"
[profiles.review]
approval_policy = "on-request"
sandbox_mode = "read-only"
它表示：
- 默认允许在当前项目里完成修改；
- 越过边界时需要审批；
- 额外保留只读和审查模式。
字段会随版本变化，复杂配置应以当前官方 reference 为准。
最值得准备的三个 Profile
1. Readonly：陌生仓库分析
[profiles.readonly]
sandbox_mode = "read-only"
approval_policy = "on-request"
适合：
- 生成项目地图；
- 找测试命令；
- 分析架构；
- 做安全或代码审查；
- 在实施前确认影响面。
2. Coding：日常小范围修改
[profiles.coding]
sandbox_mode = "workspace-write"
approval_policy = "on-request"
适合修测试、补文档和实现小功能。任务说明仍应限制修改范围，并给出验证命令。
3. Review：发布前检查
[profiles.review]
sandbox_mode = "read-only"
approval_policy = "on-request"
让 Codex 优先指出 bug、回归风险和缺失测试，不主动修改代码。
配置变化后怎样验证
不要改完配置就直接执行部署或迁移。
先运行一个最小任务：
请说明当前工作区、沙盒模式、审批策略和准备采用的验证方式。不要修改文件。
再确认：
- 是否读取了正确目录；
- 是否遵守只读或工作区写入边界；
- 越界时是否按预期触发审批；
- profile 是否真的被选中；
- 网络和外部工具是否仍受限制。
配置越复杂，越容易出现什么问题
文件路径或 TOML 语法错误
配置没有被加载，或者部分字段被忽略。
新旧权限机制混用
旧式 sandbox_mode 与新版 permission profiles 混在多个配置层里，实际生效结果可能和预期不同。
把团队规则放进个人配置
其他成员无法共享，最终每台机器行为不同。
把凭据写进可展示文件
截图和 issue 很容易泄露 token、私有服务地址和本机信息。
切换 Provider 后误以为会话丢失
有时会话文件仍在，只是 metadata、SQLite 状态或项目可见性仍指向旧 provider。应先检查会话文件和不同入口的可见性，再考虑使用第三方同步工具。
任何会修改 ~/.codex 状态的社区工具，都应该先备份并理解能力边界。
团队应该共享什么
适合进入仓库：
AGENTS.md；- 项目级规则；
- 推荐测试命令；
- PR 模板；
- 文档和截图规范。
适合留在个人机器：
- 默认模型；
- 本地路径；
- 私有 MCP；
- token 和密钥；
- 个人自动化；
- 代理和 provider 私有配置。
写在最后
好的 config.toml 不应该是一份从网上复制来的“最强配置”，而应该是对真实工作习惯的最小表达。
先从默认权限和三个 profile 开始，验证每个字段确实生效，再逐步增加网络域名、工具和自定义权限。
配置的目标不是让 Codex 拥有更多能力，而是让它每次启动时都进入一个可预期的工作状态。