Codex 示例配置：从官方 sample config 改成自己的项目配置

适用场景

这篇手册适合已经知道 config.toml，但不知道如何从官方示例落地到自己项目的用户。官方 sample config 很适合学习字段结构，但不应该原样搬进仓库。

OpenAI 官方 Sample Configuration 页面提供了配置样例。实际字段应以当前官方页面为准。

步骤 1：先读懂 sample config 的目的

示例配置通常用于展示能力，而不是推荐你全部启用。

常见内容包括：

• 模型设置。
• profile。
• 审批或沙箱策略。
• MCP server。
• hooks。
• 环境变量或工具配置示例。

你的目标是从中挑出项目需要的部分。

步骤 2：先复制到草稿，不要直接提交

建议先在本地草稿里试验。

~/.codex/config.toml

确认行为稳定后，再决定是否抽取项目级配置：

your-project/.codex/config.toml

项目级配置一旦提交，就会影响团队协作，需要更谨慎。

步骤 3：删掉不需要的字段

配置应尽量短。

保留：

• 团队明确需要的字段。
• 项目稳定使用的 profile。
• 必须共享的 MCP 配置。
• 经过审查的 hooks。

删除：

• 你看不懂用途的字段。
• 临时调试字段。
• 个人路径。
• 示例 token。
• 未启用的 MCP server。

步骤 4：把 secret 换成变量引用

不要在配置中写真实密钥。

可以写说明或占位：

# 真实 token 通过环境变量或 secret 注入。

同时在 AGENTS.md 或 .env.example 中说明需要哪些变量。

PRIVATE_REGISTRY_TOKEN=replace-with-token

步骤 5：用小任务验证配置

配置完成后先做只读验证。

请读取当前 Codex 配置，说明 profile、MCP 和 hooks 的用途。
不要修改文件。

再做一个低风险任务，比如读取项目结构或运行 lint。确认无误后再用于真实开发。

常见错误

不要完整复制官方示例。示例的目的是展示可能性，不是项目最佳实践。

不要提交真实密钥或本机路径。

不要启用自己没审查过的 MCP server 或 hooks。

不要让 sample config 比项目规则还复杂。复杂配置会降低可维护性。

小结

官方 sample config 是学习材料。落地时要先理解用途，再删减字段、移除秘密、加上必要注释，并通过小任务验证它真的符合项目需求。