用 AI coding agent 一段时间，配置总会越攒越多：全局的模型偏好、某个项目专属的沙箱档位、另一台机器上想同步的习惯。这些配置写在哪个文件、哪一层说了算，直接决定「为什么我明明配了却不生效」这类困惑。config.toml 的分层机制回答的就是这件事：全局层跟着用户走，项目层跟着仓库走，两者按规则合并，上面再压一道信任门槛——没被信任过的项目，项目层配置根本不会被读取。这篇讲清分层结构、合并顺序、信任流程，以及配置来源拿不准时怎么核对；分层的常见错法已整理成八错清单，见配置八错清单一篇。
两层配置：跟着人与跟着项目
第一层是全局配置，通常放在用户主目录下的 .codex 目录里，管跨项目通用的偏好：默认模型、审批档位、通知习惯，改一次处处生效。第二层是项目配置，放在仓库根目录的 .codex 目录里，管这个项目特有的约定：放开哪个目录的写权限、挂哪个 MCP 服务、验证改动用什么命令。项目的归项目，个人的归个人，这是分层的首要原则——把项目特有的配置写进全局层，换台机器就丢；把个人偏好写进项目层并提交，同事就得被动接受你的口味。MCP 服务的登记同样分两层，挂载细节见MCP 接入一篇；涉及凭据的条目不该进任何会被提交的文件，边界见密钥分离一篇。
合并顺序：项目层覆盖全局层
两层写了同一个配置项时，按「越靠近项目越具体、越具体越优先」的顺序合并：项目层的值覆盖全局层，全局层只提供缺省。规则符合直觉，但有两个容易踩偏的地方。其一，覆盖发生在条目级而非文件级：项目层只覆盖它写了的条目，没写的条目照旧继承全局层——你以为「被项目覆盖掉了」的某个全局习惯，可能还在暗中生效。其二，部分开关是复合结构，项目层改的是其中一个子项，父项的取值来自哪一层，肉眼不容易判断，这正是需要调试命令的原因，下文会讲。
信任机制：未信任的项目不读项目层
分层之上还有一道门槛：项目信任。agent 进入一个新仓库时，项目层配置不会立刻生效，而是先问一句信不信任这个目录；确认之后，项目层的沙箱、审批、MCP 条目才开始加载。这个设计防的是一类真实风险：从网上拉下来的仓库自带一份配置，里面写了放开权限或挂上不明服务，如果进门即生效，等于替别人执行了它的配置。信任是一次性动作，信任过的项目后续进入不再重复询问；后悔了可以撤销重信。版本行为有迭代（截至发稿版本，以官方更新日志为准），拿不准当前版本是否加载项目层，直接用调试命令核实，比猜靠谱。指令文件 AGENTS.md 的加载同样受信任状态影响，排查思路见AGENTS.md 排查一篇。
多来源与核对：配置到底从哪来
实际环境里配置经常不止两层来源：npm 装的、brew 装的、官方安装器装的 agent，可能各读各的家目录，同一台机器并存多套配置，改了这份那份不认账——这是「我明明配置了」的另一种常见成因。处理原则是先收敛再调优：确定日常使用哪一套安装，其余卸干净或统一迁移，避免配置分裂。核对来源有一个直接入口：会话里运行调试类命令（如 /debug-config），把当前生效的完整配置与每一项的来源层打印出来，哪一层覆盖了哪一层，一目了然。想系统梳理自己的配置，可以让 Kimi 把全局层与项目层的条目列成两张对照表，再用通义千问逐条判断该归哪一层，归位之后配置立刻清爽。
| 症状 | 最可能的来源 | 核对与处理 |
|---|---|---|
| 全局改了，项目里不生效 | 项目层写了同一条目 | 用 /debug-config 看生效值与来源层 |
| 项目层配置整份没加载 | 项目尚未被信任 | 先确认信任状态，再进仓库 |
| 同一台机器改了一份不认账 | 多套安装各读各的家目录 | 先收敛安装来源，卸干净或统一迁移 |
| 只改了一个子项，行为没变 | 复合结构的父项取自另一层 | 打印完整生效配置，按层判断 |
配置分层速查
- 两层：全局层在主目录管通用偏好，项目层在仓库管项目约定
- 合并按条目级覆盖：项目层写了才覆盖，没写的继承全局
- 信任是门槛：未信任项目不加载项目层，防带配置进门的仓库
- 多套安装并存会分裂配置，先收敛来源再调优
- /debug-config 打印生效值与来源层，覆盖关系一目了然
config.toml 分层快问快答
- 项目层配置写了为什么没生效？：先查两处：项目是否已信任、条目是否被别的层覆盖。用调试命令看生效值与来源，比逐个文件翻快得多。
- 全局配置想只在部分项目关闭怎么办？：在那些项目的项目层把对应条目显式写回，覆盖全局值；分层合并天然支持「默认开、个别关」的写法。
- 信任错了一个项目能撤销吗？：可以。信任状态保存在配置里，找到对应条目删除或改回未信任，下次进入会重新询问。
