在深入使用 Codex 时，理清 config.toml 与 AGENTS.md 的职责边界是构建专业工作流的基础。简单来说：config.toml 管理的是 Codex 自身的运行偏好，而 AGENTS.md 定义的是 Codex 在特定项目中的行为准则。

职责分工矩阵

| 维度 | config.toml | AGENTS.md |

| :--- | :--- | :--- |

| 核心定位 | 个人“驾驶舱”配置 | 项目“操作说明书” |

| 管理对象 | 模型引擎、Provider 接入、沙箱策略、审批流程 | 目录规范、构建脚本、代码风格、验收标准 |

| 生效范围 | 个人全局或项目专用的运行环境配置 | 当前仓库或特定子目录的工程约定 |

| 安全敏感性 | 涉及环境变量引用（如 API Key 标识） | 纯文本规则，严禁包含任何敏感信息 |

config.toml 核心配置维度

  • 模型与 Provider 接入：指定默认驱动模型（如 gpt-4o, deepseek-coder）及其对应的 API 端点 (Base URL)。
  • 审批策略 (Approval Policy)：定义高风险操作的介入机制。例如，删除文件、发起网络请求或执行特定系统命令时，是否需要开发者显式授权。
  • 沙箱边界 (Sandbox Mode)：限制 Codex 的读写权限。您可以配置为“仅限当前工作区写入”或“全局只读模式”，以确保本地环境安全。
  • MCP 工具集成：配置外部工具服务器（MCP Server）的连接参数，扩展 AI 的知识获取与工具调用能力。
  • 配置预设 (Profiles)：针对不同任务类型预设配置组合。例如，readonly 模式用于代码审计，full-access 模式用于复杂重构。

场景决策指南：配置该放在哪？

场景 A：我习惯默认使用 DeepSeek 模型进行开发

放置位置：用户级全局配置 ~/.codex/config.toml

理由：这是您的个人偏好，应当贯穿您处理的所有项目。

场景 B：本项目强制要求所有注释必须符合特定 JSDoc 规范

放置位置：项目根目录 /AGENTS.md

理由：这是项目级别的工程约束，所有参与该项目的成员都应遵循相同的代码风格。

场景 C：本项目需要连接一个企业内部的私有文档库

放置位置：项目级运行配置 .codex/config.toml

理由：这是该项目特有的工具链需求，属于对 Codex 运行能力的特定扩展。

专业实践建议

  1. 分层治理：坚持“个人习惯入全局，项目规则入仓库”的原则，确保配置的灵活性与项目的一致性。

    2. 2. 环境变量优先：严禁将真实的 API Key 字符串直接写入任何配置文件。应通过环境变量或 .env 文件进行引用，保障密钥安全。

    3. 动态维护：随着项目演进，务必及时同步 AGENTS.md 中的脚本命令。失效的规则会误导 AI 产生非预期的操作尝试。

    理解并践行这套分层配置原则，是让 AI 协作从“随意尝试”转向“专业交付”的关键。

    ---

    下一篇推荐：配置作用域与优先级 —— 深入了解多层配置如何冲突与合并。