配置层级与优先级覆盖

Codex 的运行偏好并非只存在一个文件里：本地个人配置、项目级约定、管理员强制要求、运行时临时参数共同构成配置层级，其中强制项普通用户无法覆盖。本节先建立"谁定义、谁优先、谁不可改"的心智，避免把企业托管示例直接照搬到个人环境。具体文件名与键名以当前版本官方文档为准。

一、配置来源分层

层级	典型来源	作用	普通用户可否修改
本地个人配置	用户本机的配置文件（如 config.toml 类）	保存个人审批偏好、常用目录、凭据存储方式等默认值	可修改，用于个人日常
项目级约定	项目工作区内共享的配置/指令约定	统一团队在该仓库的边界与习惯，随项目走	随项目维护，成员共同遵循
管理员强制要求	如 requirements.toml 类强制文件	下发安全基线（允许的沙箱模式、网络与凭据要求等）	不可覆盖，优先级高
托管策略	云端托管要求、操作系统托管偏好（企业场景）	在桌面应用、CLI、IDE 扩展间统一强制策略	由管理员下发，用户不可改
运行时临时参数	启动命令携带的临时选项	单次运行覆盖默认值，不写入长期配置	本次生效，具体选项以 codex --help 为准

二、优先级与覆盖原则

1. 强制优先：管理员强制要求与托管策略优先级最高，用于锁定安全底线，个人本地配置不能放宽这些强制项。
2. 运行时覆盖默认：单次启动携带的临时参数通常高于长期默认值，便于针对一次任务调整，但不改变基线。
3. 项目约定优先于个人全局：进入具体仓库时，项目共享约定用于统一协作，个人偏好让位于团队基线。
4. 冲突时取更安全者：当多个来源对同一安全项给出不同取值，以限制更严、更强制的一方为准。
5. 不臆造键名：记不准的配置项先查官方文档与本机帮助，不凭印象写入，避免无效配置或被忽略。

三、个人本地与团队企业两种视角

视角	常见配置范围	目标
个人本地	审批偏好、常用工作目录写范围、凭据存放方式、网络与检索偏好	在安全前提下提升个人效率，改动前先备份
团队/企业	强制沙箱模式、网络白/黑名单、登录与工作空间绑定、命令规则、遥测导出	统一安全基线、可审计、防止个人放宽管控

四、配置"改了却不生效"的排查顺序

• 先确认改动落在哪一层：本地、项目还是被强制要求覆盖。
• 核对键名与层级写法是否与当前官方文档一致（版本演进可能调整）。
• 确认本次运行是否被运行时临时参数覆盖。
• 对照强制要求检查该项是否属于不可覆盖范围；若是，个人侧无法放宽，应走管理员变更流程。
• 修改前保留上一版配置备份，便于快速回退。

五、FAQ

问题	处理建议
个人用户需要 requirements.toml 吗	它主要是管理员强制基线；个人通常只需维护本地偏好，不必照搬企业强制片段。
本地改了审批/沙箱偏好为何没变化	先查是否被项目约定或强制要求覆盖，再核对键名与语法，最后确认是否需重启会话生效。
如何知道当前实际生效值	以当前版本官方文档说明的查看方式与 codex --help 为准；不臆造查看命令。
能否一份配置用到底	不建议。不同项目风险与依赖不同，下一节讲按项目组织配置。

六、动手练习

• 练习：列出你当前使用环境中可能存在的配置层级（本地/项目/强制/运行时），为本地偏好做一份备份；挑选一项个人偏好，记录它属于哪一层、是否可能被上层覆盖。