Codex 配置基础：config.toml、项目配置与 profiles

适用场景

这篇手册适合已经开始稳定使用 Codex，并希望把常用设置沉淀下来的用户。比如：某些项目默认使用更严格的审批模式，某些仓库需要固定 MCP server，或者你想为“快速问答”和“高风险改动”准备不同配置。

OpenAI 官方文档说明，Codex 可以通过 config.toml 管理配置。配置文件能减少重复提示，让 Codex 在不同项目和任务中保持一致的运行方式。

步骤 1：先区分三类信息

适合放进 config.toml：

• 默认模型或推理强度。
• 沙箱和审批相关设置。
• MCP server 配置。
• profiles 这类可切换运行场景。
• 个人或项目级 Codex 行为配置。

适合放进 AGENTS.md：

• 项目介绍和目录约定。
• 运行、测试、构建命令。
• 代码风格和内容规范。
• 不要修改的文件或目录。
• 团队协作边界。

适合放进一次性提示词：

• 当前任务的具体目标。
• 本次要改的文件范围。
• 本次输出格式和验收要求。
• 临时限制，比如“这次先不要修改代码”。

步骤 2：了解常见配置位置

Codex 常见配置位置有两类：

~/.codex/config.toml
your-project/.codex/config.toml

全局配置适合放个人偏好，例如默认模型、常用审批习惯或个人 MCP 工具。项目级配置适合放团队共享设置，例如这个项目必须使用的 MCP server、固定的工作方式或仓库专属 profile。

如果项目配置要提交到 Git，建议先检查里面是否包含本机路径、用户名、密钥、token 或内部地址。

步骤 3：从最小配置开始

不要一开始就写一大段配置。先从真正会反复使用的设置开始。

示例结构：

model = "gpt-5-codex"

[approval]
mode = "on-request"

实际可用字段以官方文档和当前 Codex 版本为准。写配置时建议一次只改一类设置，改完后用一个小任务验证行为是否符合预期。

步骤 4：用 profiles 管理不同任务场景

当你有多套常用工作方式时，可以用 profile 来切换。

概念示例：

[profiles.fast]
model = "gpt-5-codex"

[profiles.careful]
model = "gpt-5-codex"

常见 profile 设计：

• fast：适合阅读代码、回答问题、小范围修改。
• careful：适合跨模块重构、发布前检查、安全敏感任务。
• docs：适合文档、教程和内容站维护。
• review：适合只读审查，不主动改文件。

profile 的价值不是“配置越多越好”，而是让高频场景一键进入稳定状态。

步骤 5：项目配置要写得可维护

项目级 .codex/config.toml 应该服务整个团队，因此要保持克制。

建议写进去：

• 团队确认过的 MCP server。
• 项目固定需要的运行环境配置。
• 与仓库强相关的 profile。
• 不包含秘密信息的默认行为。

不建议写进去：

• 个人账号、token、API key。
• 本机绝对路径。
• 只适合某个开发者习惯的设置。
• 过期的临时兼容配置。

如果某个设置只是你个人偏好，放在全局配置更合适。

步骤 6：修改配置后做一个小验证

每次改完配置，都建议用低风险任务验证。

可以这样提示 Codex：

请只读取当前项目配置，说明你能看到哪些与模型、审批、沙箱或 MCP 相关的设置。
不要修改文件。

确认输出符合预期后，再交给 Codex 执行真实任务。这样能更早发现 profile 没生效、MCP 未加载或审批模式不符合预期的问题。

常见错误

不要把配置文件当作任务说明书。配置负责运行行为，任务目标仍然应该写在当前对话里。

不要把密钥写进项目配置。即使是私有仓库，也应使用安全的凭证管理方式。

不要让全局配置和项目配置互相冲突。如果某个项目需要特殊行为，最好在项目配置或 profile 中写清楚原因。

不要长期不清理 profile。过期配置会让 Codex 的行为变得难以预测。

小结

Codex 配置的核心思路是：全局配置放个人偏好，项目配置放团队共享约定，AGENTS.md 放项目执行规则，一次性提示词放当前任务。把这几类信息分开，Codex 的行为会更稳定，也更容易排查问题。