在管理 Codex 配置时，开发者常面临选择：是将配置放在全局的 ~/.codex/config.toml，还是放在项目内的 .codex/config.toml。理解二者的作用域与优先级是构建稳定工作流的前提。

配置层级概览

| 配置文件 | 影响范围 | 适用场景 |

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

| 用户级 (~/.codex/config.toml) | 个人所有项目 | 默认模型、Provider、个人审批偏好 |

| 项目级 (.codex/config.toml) | 当前项目或子目录 | 项目专用 MCP、特定沙箱限制、自定义子代理 |

选择指南

1. 优先使用用户级配置

对于通用的模型接入信息（如 Provider、Base URL、环境变量名），应始终优先放在用户级。这样可以避免在每个项目中重复配置，降低维护成本，并防止敏感信息意外进入项目仓库。

2. 审慎使用项目级配置

项目级配置仅在以下特定场景下建议使用：

  • 项目专用工具：需要连接该项目特有的数据库 MCP 或内部文档服务。
  • 严格的安全隔离：该项目对文件读写或网络访问有特殊的沙盒限制。
  • 团队协作预设：为团队成员预设特定的 Subagent 角色。

加载与覆盖规则

  • 继承与覆盖：Codex 会从根目录向当前目录逐级读取配置。如果同一配置项重复出现，离当前工作目录最近的设置将生效。
  • 信任边界：出于安全考虑，Codex 仅在受信任的项目中加载项目级配置。未被信任的项目将忽略 .codex/ 目录下的规则。
  • 安全保护：部分高风险配置项（如全局安全开关）可能被限制，不允许通过项目级配置进行越权覆盖。

安全红线

无论选择哪一层级，严禁将以下内容写入项目级配置并提交：

  • 真实的 API Key 或 Token 字符串。
  • 个人私有账号信息。
  • 可能导致安全漏洞的越权配置。

排查建议

如果发现项目级配置不生效，应按序核对：

  1. 项目是否已标记为“受信任”。

    2. 2. 文件路径是否准确（需在 .codex/ 目录下）。

    3. 当前工作目录是否正确。

    4. 是否存在更高优先级的覆盖配置。

    对于新手，建议先在用户级完成所有配置，待确实产生“项目特有需求”时，再引入项目级配置层。