用户级 config.toml 和项目级 .codex/config.toml 怎么选

用户级 config.toml 和项目级 .codex/config.toml 怎么选

上一篇讲了 config.toml 是什么。

这一篇解决一个实际问题：

我到底应该改 ~/.codex/config.toml，还是项目里的 .codex/config.toml？

前置教程：config.toml 是什么，和 AGENTS.md 有什么区别
如果你还分不清 config.toml 和 AGENTS.md，先看前置教程。

先给结论

新手默认选：

用户级 ~/.codex/config.toml

项目级 .codex/config.toml 等你真的需要“某个项目专用配置”时再用。

两个文件的区别

文件	影响范围	适合写什么
~/.codex/config.toml	你自己的所有 Codex 使用场景	默认模型、默认 provider、常用审批偏好
项目里的 .codex/config.toml	当前项目或当前子目录	项目专用 MCP、项目专用沙箱、项目专用子代理

简单说：

你的个人习惯，放用户级。
这个项目才需要的东西，放项目级。

场景 1：配置国内大模型

优先写用户级：

~/.codex/config.toml

因为你可能在很多项目里都想用同一个模型服务商。

不要每个项目都复制一份 provider 配置。

否则以后服务商 Base URL、模型名、环境变量名有变化，你要改很多地方。

场景 2：某个项目需要特殊 MCP

可以考虑项目级：

项目根目录/.codex/config.toml

比如这个项目需要连接：

• 内部文档 MCP。
• 项目专用数据库只读 MCP。
• 项目专用设计稿 MCP。

这类配置不一定适合所有项目，就可以项目级隔离。

场景 3：某个子目录规则不同

如果一个大型仓库里有多个模块：

repo/
  apps/web/
  services/api/
  packages/shared/

某个子目录确实需要不同配置，才考虑更深层的 .codex/config.toml。

但新手阶段不建议这么做。

层级越多，越难排查。

Codex 怎么加载项目级配置

官方手册中的核心规则可以理解为：

Codex 会从项目根目录走到当前工作目录，读取沿途的 .codex/config.toml。
如果多个文件设置了同一个键，离当前工作目录更近的配置优先。

举例：

repo/.codex/config.toml
repo/apps/web/.codex/config.toml

如果你当前在：

repo/apps/web

那么 repo/apps/web/.codex/config.toml 里重复设置的值会更优先。

受信任项目是什么意思

项目级配置不是任何时候都会加载。

为了安全，Codex 只会在受信任项目里加载项目级 .codex/ 配置层。

这意味着：

• 你从网上下载一个陌生项目时，不应该让它随便控制 Codex 配置。
• 项目级 hooks、rules、config 这类东西需要先经过信任边界。
• 如果项目没有被信任，项目级 .codex/config.toml 可能不会生效。

如果你发现项目级配置不生效，不要第一反应就改很多遍。

先检查：

1. 项目是否被 Codex 视为受信任。
2. 文件路径是不是 .codex/config.toml。
3. 当前工作目录是不是你以为的目录。
4. 是否有更近一层配置覆盖。
5. 是否尝试配置了安全敏感且不允许项目级覆盖的设置。

哪些内容不要放项目级

不要把这些放进项目级配置并提交：

• API Key 真实值。
• 你的个人账号信息。
• 只属于你个人习惯的默认模型。
• 会让陌生项目绕过安全边界的设置。

如果项目确实需要某个环境变量名，可以写变量名，不写真实值。

例如：

env_key = "DEEPSEEK_API_KEY"

真实值放在你的环境变量或用户级 .env 里。

新手推荐配置路线

按这个顺序来：

1. 先完成模型配置总览。
2. 先把 provider 写到用户级 ~/.codex/config.toml。
3. 把真实 API Key 放到环境变量或 ~/.codex/.env。
4. 打开一个安全练习项目，做只读验证。
5. 跑通后再考虑是否需要项目级配置。

不要反过来：

还没搞懂用户级配置，就在项目里到处创建 .codex/config.toml。

这样以后排查会很麻烦。

让 Codex 帮你判断应该放哪一层

你可以复制这个提示词：

请帮我判断下面这项 Codex 配置应该放在用户级 ~/.codex/config.toml，还是项目级 .codex/config.toml。

配置目标：
【这里写你的目标，比如：默认使用 DeepSeek provider】

要求：
1. 先判断它是个人默认、项目专用，还是当前一次任务临时需求。
2. 如果适合用户级配置，请说明原因。
3. 如果适合项目级配置，请说明项目需要满足哪些前提。
4. 如果不应该写进 config.toml，请告诉我应该放到哪里。
5. 不要直接修改文件。

让 Codex 检查当前到底哪层可能生效

你可以复制：

请只读检查当前 Codex 配置可能来自哪些层。

要求：
1. 不要修改任何文件。
2. 检查用户级 ~/.codex/config.toml 是否存在。
3. 检查当前项目是否有 .codex/config.toml。
4. 如果有多层项目级配置，请按从远到近列出。
5. 不要展示 API Key 真实值。
6. 最后用中文解释：如果同一个配置键重复出现，哪一层更可能生效。

预期结果：

• Codex 会列出用户级配置。
• Codex 会列出项目级配置。
• Codex 不会打印密钥真实值。
• Codex 会解释覆盖关系。

常见错误

错误 1：每个项目都复制一份模型 provider

如果你所有项目都用同一个 provider，放用户级即可。

重复复制只会增加维护成本。

错误 2：项目级配置不生效就乱改

先检查项目是否受信任、路径是否正确、当前工作目录是否正确。

错误 3：把 API Key 写进项目仓库

这是严重错误。

真实密钥只放在你自己的环境里。

错误 4：把项目规则写进 config.toml

比如：

所有教程必须写成喂饭级。

这应该写进 AGENTS.md，不是 config.toml。

这一篇的验收标准

读完后你应该能判断：

1. 默认模型配置应该优先放哪里。
2. 项目专用 MCP 应该考虑放哪里。
3. 为什么项目级配置需要信任边界。
4. 为什么 API Key 真实值不能提交到项目。
5. 排查配置不生效时先看哪几件事。

下一步可以进入 MCP 入门，也可以先把这四篇高阶入门重新过一遍，确认分层完全清楚。