config.toml 参考导读：作用域、优先级与最小可复现配置

配置生效了，反而没人敢动

同事从网上复制了一份 config.toml。模型、审批和工具行为都变了。任务暂时能跑，可换一台电脑就完全不同。

最麻烦的配置不是报错的配置，而是悄悄生效、又说不清来源的配置。

config.toml 不是参数收藏夹，它是行为契约。 这节课会把一份不可复现配置拆成来源、作用域、优先级和验证结果，最后只留下团队真正需要的最小集合。

config.toml 与 AGENTS.md 的边界

AGENTS.md 告诉 Codex“在这个项目里应该怎样工作”；config.toml 控制客户端和运行行为，例如模型选择、审批、沙箱、功能、MCP、profile 与其他运行设置。把两者混在一起会出现两种失败：

• 在 AGENTS.md 写“开启某权限”，文字无法替代真实安全配置；
• 在 config.toml 塞项目写作风格，配置层无法清晰表达任务语义。

常见配置层

官方 Config basics 当前说明用户配置通常位于 ~/.codex/config.toml，可信项目可以提供 .codex/config.toml。还有 profile、CLI 一次性覆盖和组织级配置等层。具体优先级、键名和受信任项目行为属于高漂移事实，每次新增配置前查当前官方 reference。

维护一个配置清单：

项	作用域	为什么需要	官方来源	漂移	验证	回退
approval policy	用户或 profile	控制越界询问	Config/Sandbox	高	/status 或实际行为	恢复旧值
sandbox / permissions	用户、项目或 profile	文件与网络边界	Permissions	很高	受控读写测试	最小档位
MCP server	Codex host	接入工具	MCP	很高	mcp list 与只读调用	禁用 server
model / reasoning	会话或配置	默认模型策略	Config	高	状态页	删除覆盖

不要在教程里永久写死模型名或 beta 键；用“到官方 reference 查当前允许值”作为长期入口。

最小配置原则

只配置你能解释和验证的项。一次加入十几个复制来的键，会让默认行为、性能和权限变化难以定位。推荐流程：

1. 保存当前配置副本或 Git 管理的脱敏版本；
2. 每次只新增一组相关设置；
3. 启动新会话，报告实际状态；
4. 运行一个无副作用的验证任务；
5. 记录结果与回退；
6. 再考虑推广到项目或团队。

配置文件不得保存明文令牌。需要凭据的集成应使用官方支持的环境变量或认证流程，并限制可见范围。

用户级、项目级与 Profile 怎么选

• 所有仓库都需要的客户端偏好放用户级；
• 只对可信仓库成立、且团队需要一致的设置放项目级；
• 一组经常切换的权限或工具组合放命名 profile；
• 调试一次问题用 CLI 一次性覆盖，确认后再决定是否持久化。

不要为了某个仓库修改全局设置，也不要在不可信项目中自动加载能扩大能力的项目配置。

如何验证优先级

设计一个可观察但无害的差异，例如在 profile 中使用不同批准策略或日志位置。然后：

1. 在普通会话查看状态；
2. 使用目标 profile 启动新会话；
3. 在可信项目和项目外各检查一次；
4. 记录最终值来自哪个层；
5. 删除一次性覆盖，确认恢复。

如果只看配置文件文本，不代表运行时采用了它。验证必须来自当前会话状态或可控行为。

高风险变化的处理

涉及 full access、公共网络、外部工具写入、hooks 或无人值守任务时：

• 先在隔离练习项目验证；
• 列出它新增的攻击面；
• 限制目录、域名和工具；
• 记录人工审批点；
• 为异常输出和秘密泄露设计检查；
• 保留一键禁用或回退方式。

配置漂移与知识库维护

每条配置参考记录：官方 URL、校准日期、客户端版本、适用表面、是否 preview/beta。Changelog 出现相关变化时把章节标 stale，不能静默用新值覆盖旧教程。

先区分配置、指导和任务约束

三个表面经常被混在一起：

需求	应放位置	原因
默认 sandbox 与模型设置	config.toml / profile	是运行时默认值
仓库测试和评审要求	AGENTS.md	是可读的项目工作方式
这次不要改支付 API	当前 prompt	只属于当前任务

把所有东西塞进 config.toml 会让任务语义不可见；把配置键写进 prompt 又难以复现。

完整案例：最小配置实验

不要从网上复制一整份 sample config。先只改变一个可观察变量：

# .codex/config.toml
sandbox_mode = "workspace-write"
approval_policy = "on-request"

然后建立验证记录：

预期：可以修改当前可信仓库，访问工作区外文件或网络时暂停。
检查：报告当前配置来源和最终生效值。
正例：修改 workspace 内练习文件。
负例：尝试读取 workspace 外测试路径，应被拒绝或请求批准。
恢复：删除项目覆盖，回到用户默认配置。

配置是否“写对”不只看 TOML 能解析，还要看行为是否符合预期。

优先级调查的正确方式

当行为与预期不一致时，按来源列账本：

1. 管理员强制策略；
2. 当前命令或一次性覆盖；
3. profile；
4. 可信项目配置；
5. 用户级默认；
6. 产品默认。

不同产品版本和表面可能调整具体能力，最终以当前官方参考和实际 status 输出为准。本教程重点是调查方法：找出谁设置了值、谁覆盖了它、当前生效值是什么。

配置中不要放什么

• API key、访问 token 和个人认证文件；
• 只对一次任务有效的页面路径；
• 没有验证过的第三方命令；
• 与管理员策略冲突的“绕过”设置；
• 大段工作流程说明。

秘密使用受支持的环境或认证机制；流程进入 AGENTS.md 或 Skill；一次性边界留在 prompt。

Profile 适合保存一组有名字的工作方式

例如个人可能需要“只读审计”和“可信本地开发”两组配置。Profile 的价值是让一组模型、推理、权限和工具设置可以被明确选择、比较和回退，而不是在每次任务前临时改多个键。

建立 profile 后仍应做行为验证：只读 profile 不应能改文件；本地开发 profile 可以写当前仓库，但不应因此获得生产部署授权。Profile 描述运行能力，任务 prompt 描述本次要做什么。

当一次实验失败时，先回到可工作的最小 profile，再逐个恢复设置。一次同时调整模型、权限、MCP 和特性开关，会让你无法知道哪一项真正改变了行为。

故障诊所

现象	检查	恢复
项目配置完全不生效	项目是否可信、路径是否正确	先用一个最小键验证加载
CLI 与 App 行为不同	是否共享同一 profile 和配置层	分别报告表面、版本与生效值
权限比配置写得更严格	管理员要求或 sandbox 边界	不尝试绕过，报告强制来源
加载后启动失败	TOML 语法或过期键	回退到最小配置，再逐项加入

知识检查

如果只想让当前一次运行使用更高推理强度，应先改团队仓库配置吗？通常不应。一次性选择优先用当前表面的临时覆盖，确认有长期价值后再沉淀。

每个配置值都应该回答「为什么在这里」

打开你的配置，只保留能说清来源和用途的键。对每个值记录谁覆盖谁、怎样验证、出问题如何撤回。

官方键名和默认值会变化。无法在当前参考里确认的示例，不要因为「别人也这么配」进入长期配置。

完成检查

• 能解释 config.toml 与 AGENTS.md 的职责差异
• 每个持久配置都有真实需求和官方来源
• 高漂移键在操作前回查 reference
• 运行时状态证明配置生效
• 配置没有明文秘密
• 修改前值、验证与回退均已记录