Codex 高级配置：把权限、工具和项目默认行为管起来

适用场景

这篇手册适合已经使用过基础 config.toml，并希望把 Codex 的运行方式做得更稳定的团队。高级配置通常涉及权限、工具、hooks、profile 和项目级默认行为。

OpenAI 官方文档提供了 Codex Advanced Configuration 说明。实际字段和可用能力会随产品更新变化，写入配置前应以当前官方页面为准。

步骤 1：先确认你要解决的问题

不要为了“高级”而写高级配置。先判断你遇到的是哪类问题。

适合高级配置的问题：

• 每个任务都要重复指定审批模式。
• 项目需要固定 MCP server。
• 某些命令运行前后必须触发 hooks。
• 同一项目有多套稳定工作模式。
• 团队需要统一沙箱或权限边界。

不适合高级配置的问题：

• 本次任务的临时目标。
• 一篇文章的写作要求。
• 一次性的调试命令。
• 还没有稳定下来的个人偏好。

步骤 2：把配置拆成不同层级

建议按作用范围拆分：

• 当前提示词：只影响本次任务。
• AGENTS.md：项目规则、命令、内容规范。
• 项目 .codex/config.toml：团队共享的 Codex 运行配置。
• 全局 ~/.codex/config.toml：个人默认偏好。
• profile：可切换的常用场景。

这样可以避免所有规则都挤进一个文件，后续维护也更清楚。

步骤 3：先配置最稳定的部分

适合优先固化的内容：

• 项目级 MCP server。
• 团队确认过的审批模式。
• 沙箱默认策略。
• hooks 触发点。
• 与项目强相关的 profile。

不建议一开始就固化：

• 仍在试验的模型偏好。
• 某个开发者本机路径。
• 临时绕过验证的配置。
• 只为一次任务写的例外规则。

步骤 4：用 profile 表达任务模式

如果同一项目里有多类常见任务，可以用 profile 表达。

概念示例：

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

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

推荐设计：

• docs：内容写作、SEO、frontmatter 检查。
• review：只读审查、diff 风险分析。
• release：发布前构建、测试、变更总结。
• safe-edit：高风险代码修改前先计划。

profile 名称要让团队一眼知道用途。

步骤 5：高级配置必须可审查

团队共享配置需要像代码一样可审查。

审查重点：

• 是否包含密钥或私有路径。
• 是否扩大了网络、文件或命令权限。
• 是否引入了外部工具。
• hooks 是否会修改文件或发送数据。
• profile 名称和用途是否清楚。

如果配置会改变安全边界，最好在 PR 描述里说明原因。

步骤 6：改完配置后做只读验证

高级配置改完后，先做只读验证。

示例：

请读取当前 Codex 配置，说明可见的 profile、MCP、审批和 hooks 设置。
不要修改文件，不要运行会写入的命令。

确认行为符合预期后，再交给 Codex 执行真实任务。

常见错误

不要把所有规则都塞进 config.toml。项目代码风格和验证命令更适合放进 AGENTS.md。

不要把个人偏好提交给团队。团队配置应服务项目，不服务某个人。

不要让 hooks 做不可见的高风险操作。任何写入、发送、删除都应可审查。

小结

Codex 高级配置适合把已经稳定的运行方式固化下来。先明确问题，再按提示词、AGENTS.md、项目配置、全局配置和 profile 分层管理；任何影响权限的配置都要可审查、可验证。