配置生命周期

配置既是操作界面，也是运行时契约。将其视为具有明确所有者的状态，而不是复制到任何需要它们的子系统中的松散设置。

规范来源是 zeroclaw_config::schema::Config，从 config.toml 加载。面向用户的配置界面、生成的配置参考、网关配置编辑器、环境变量覆盖、zeroclaw config set、zeroclaw config patch、快速开始以及 RPC 配置方法都通过同一个类型化 schema 路由。

有关将类型化 schema 转换为配置参考的构建顺序、追踪输出规则和漂移检查，请参阅生成文档管道。

谁拥有什么

Surface	所有者	持久化边界	运行时应用边界
配置模式	`crates/zeroclaw-config/src/schema.rs` 以及 `Configurable` 派生	代码，而不是生成的文档	新的二进制构建
已生成的参考	`cargo mdbook refs` / `markdown-schema`	`docs/book/src/reference/config.md` 在构建时	仅文档说明
引导位置	`ZEROCLAW_CONFIG_DIR`, `ZEROCLAW_DATA_DIR`, deprecated `ZEROCLAW_WORKSPACE`	仅限环境	在 `Config` 存在之前
Schema-mirror 覆盖项	`ZEROCLAW_<lowercase_path>` 使用 `__` 表示点号	仅内存中	每个 `Config::load_or_init()`
CLI 配置写入	`zeroclaw config set`, `config patch`, 别名，模型辅助函数	`save_dirty()` 到 `config.toml`	下一次加载/重新加载，除非当前命令使用新的内存值
RPC 和 TUI 配置写入	`config/*` RPC 方法由 zerocode 使用	`save_dirty()` 到 `config.toml`	RPC 上下文立即更新；守护进程拥有的子系统需要重新加载
快速开始应用	共享 web、CLI 和 zerocode 应用路径	`save_dirty()` 到 `config.toml`	Web 和 RPC 可以触发 daemon 重载；独立 CLI 会在下次 load/reload 时应用
Gateway 配置写入	配置 API 处理程序和 `persist_and_swap()`	`save_dirty()` 到 `config.toml`	网关可见的状态更新会立即生效；守护进程子系统会在重载后应用
守护进程重新加载	`/admin/reload`、RPC `config/reload` 或进程内重载通道	重新读取 `config.toml`	在同一 PID 中重新创建守护进程子系统

不要手动编辑生成的 config reference。如果那里有字段、枚举、alias section、secret marker 或描述错误，请修正 schema 或生成器并重新生成 reference。

加载顺序

Config 加载有几个不同的阶段：

从 bootstrap 环境变量解析安装根目录。这发生在任何 Config 存在之前，因此 bootstrap 名称保持其大写形式，并且不使用 schema-mirror 语法。
读取 config.toml，在内存中运行 schema 迁移，解密已配置的密钥，并将任何格式错误的安全关键部分记录为降级安全。
将 schema-mirror 覆盖应用到内存配置中。在环境变量中，__ 映射为 .，因此 ZEROCLAW_providers__models__openai__api_key 指向 providers.models.openai.api_key。
在不将操作员锁定在网关编辑器外的情况下进行验证并发出警告。

在全新安装时，默认值会在应用环境覆盖之前保存。这样可以避免将通过环境注入的密钥和本地 CI 值写入新文件。

环境覆盖项不会被保存

Schema-mirror env vars 是运行时注入。它们在加载时进入内存中的 Config，并在 env_overridden_paths 中被跟踪，因此 CLI、dashboard 和 quickstart 可以显示覆盖标记。

保存时，必须将这些路径在加密前还原为其覆盖前的磁盘值或默认值。对于机密信息，这一点尤为重要：如果操作员在磁盘上有一个已加密的 API 密钥，并且临时为同一路径通过环境变量覆盖启动，那么一次无关的配置保存绝不能用环境变量值或掩码显示字符串替换真实凭据。

在牢记此不变式的前提下审查配置更改：

ZEROCLAW_* schema-mirror 值在加载后会影响运行中的进程。
它们不会变成持久配置。
保存路径必须保留加密密钥和外部密钥引用，除非同一路径被有意编辑。

凭据输入保持类型化

凭据类运行时值仍然属于配置值。API 密钥、OAuth 令牌、端点 URL 以及其他提供商/渠道凭据，在运行时构造函数获取它们之前，应通过类型化配置模式、配置机密处理机制或与模式镜像同步的 ZEROCLAW_* 覆盖项传递。

请勿在 provider、channel、tool、transcription、TTS、memory 或 gateway 构造函数内部添加临时的 std::env::var("PROVIDER_API_KEY") 读取。这会在 Config 之外创建第二个凭据来源，绕过 env-override 可见性，并可能导致 CLI、gateway、RPC/TUI、quickstart 和 reload 行为不一致。

如果 ZeroClaw 有意为某个集成系列提供原生环境桥接，请在集成边界处记录该桥接，并在构造前将其映射到相同的类型化配置值中。否则，诸如 ANTHROPIC_API_KEY、OPENROUTER_API_KEY 或 QDRANT_URL 等生态系统默认的 shell 名称应由操作员桥接到对应的 ZEROCLAW_* 架构镜像变量；参见 Environment variables。

脏路径和增量写入

大多数编辑界面使用 Config::mark_dirty() 加上 save_dirty()，而不是完整重写。save_dirty() 只写入已更改的点路径，尽可能保留未标记为脏的条目和注释，写入当前的 schema_version，并通过原子性的临时文件替换进行写入。

该路径也负责 map-key 区段。创建别名，例如模型提供方、MCP server、skill bundle 或 knowledge bundle，必须将正确的区段标记为已修改，这样别名才能在保存和重新加载后保留下来。只更新内存中的 dashboard 状态的配置编辑是不完整的。

在审查 config 写入时，请检查：

在持久化之前，编辑后的路径会被标记为脏状态；
map-key 会创建、重命名和删除，使父部分或自然键变为脏状态；
secret 和 env-overridden 路径保持它们的保存掩码行为；
schema_version 在增量写入后仍保持为最新；
更改后的值会在 save_dirty() 后再重新加载时保留。

已保存 vs 已应用

成功保存表示文件已更改。但这并不总意味着每个运行时组件都已采用了该更改。

守护进程拥有长期运行的子系统图：gateway、channel listeners、scheduler、MQTT listener、session wiring、memory backend、provider factories 和 cost wiring。POST /admin/reload 会向守护进程循环发送信号，守护进程重新读取 config.toml，并在同一进程中重新实例化这些子系统。PID 保持不变，但 listeners 会短暂重新绑定。

Gateway 配置写入会调用 persist_and_swap()：先保存到磁盘，然后替换网关可见的内存中的配置并设置 pending_reload。这使配置编辑器能够立即反映写入，而重新加载横幅则会告知操作员，通道、提供程序、调度器或其他守护进程拥有的组件可能仍在从先前的子系统实例运行。

独立的 zeroclaw gateway start 没有守护进程监督器。它的重载端点会返回需要重启的响应，因为没有外层守护进程循环可以发出信号。