配置运行时

Codex 的配置系统不是简单读取 ~/.codex/config.toml。它由多层 config、requirements、profiles、permissions、plugins、MCP 和 feature gates 合成，最终变成 thread/session/turn 的运行时快照。

配置运行时

Config Layer

codex-rs/config/src/merge.rs 定义 TOML merge 规则：低优先级层提供默认，高优先级层覆盖标量和列表，表递归合并。合并时还会做 key alias normalization，例如旧字段名和新字段名的兼容。

特别处理：

  • permissions.*.network.domains 的 domain key 会经过 host normalization。
  • overlay 中的表递归合并。
  • overlay 中的非表值整体替换 base。

Requirements Layer

codex-rs/config/src/requirements_layers/stack.rs 说明 requirements 与 config 使用相同优先级顺序，但有几个领域字段不能用普通 TOML 覆盖：

  • remote_sandbox_config 在每层内先求值。
  • rules.prefix_rules 高优先级规则排在前面。
  • hooks 高优先级事件组排在前面，并对 managed dir 冲突 fail closed。
  • permissions.filesystem.deny_read 是高优先级优先的 union。

这类字段是“策略”，不是普通配置值；直接覆盖会丢失安全语义。

ThreadConfigSnapshot

SessionConfiguration::thread_config_snapshot 会把当前 session 的关键配置拍成快照：

  • model、provider、service tier
  • approval policy、approvals reviewer
  • permission profile、active permission profile
  • environments、workspace roots
  • reasoning effort/summary
  • personality、collaboration mode、multi-agent mode
  • session source、parent/fork source

app-server resume、UI 状态展示、线程元数据都依赖这类快照。

配置更新

SessionConfiguration::apply 负责把 SessionSettingsUpdate 合入 session 配置，并检查 Constrained<T> 约束。例如 approval policy、permission profile、sandbox mode 等不是随便能改，必须满足 requirements 限制。

为什么配置要分层

Codex 同时有这些来源：

  • 用户全局配置。
  • 项目配置。
  • profile。
  • cloud/admin requirements。
  • CLI overrides。
  • app-server turn/thread overrides。
  • 插件和 marketplace 状态。

分层合成让每个来源保留优先级和来源信息，出错时能报告“哪个 layer 的哪个字段”导致冲突。