配置 RPC（编程式更新）

配置 RPC（编程式更新）{#config-rpc-programmatic-updates}¶

对于通过网关 API 写入配置的工具，建议遵循以下流程：

• config.schema.lookup 用于检查某个子树（浅层模式节点 + 子节点摘要）
• config.get 用于获取当前快照以及 hash
• config.patch 用于部分更新（JSON 合并补丁：对象合并、null 删除、数组替换——当条目会被移除时，须通过 replacePaths 显式确认）
• config.apply 仅在你打算替换整个配置时使用
• update.run 用于显式自更新并重启；当重启后的会话需要运行一个后续对话轮次时，请包含 continuationMessage
• update.status 用于检查最新的更新重启哨兵，并在重启后验证运行版本

代理应将 config.schema.lookup 视为获取精确字段级文档和约束的首选入口。当需要更广泛的配置映射、默认值或专用子系统参考的链接时，请使用配置参考。

内置的 gateway 工具直接通过接纳该代理运行的 Gateway 分发配置读取，无需打开回环 WebSocket。显式的 gatewayUrl 或 gatewayToken 覆盖以及独立的本地代理仍使用 Gateway 客户端。两条路径都使用相同的配置处理器和读取范围。

部分补丁示例：

openclaw gateway call config.get --params '{}'  # capture payload.hash
openclaw gateway call config.patch --params '{
  "raw": "{ channels: { telegram: { groups: { \"*\": { requireMention: false } } } } }",
  "baseHash": "<hash>"
}'

config.patch 会在配置文件中记录显式提供的值，即使这些值与当前运行时默认值相同。未更改的运行时默认值则继续省略。其成功响应包含 changedPaths，即经过验证和密钥恢复后实际更改的运行时路径；若无操作则为 []。这些路径不包含任何配置值；客户端可以用它们来区分通道更改与无关写入，即使密钥值已被脱敏。

config.apply 和 config.patch 都接受 raw、baseHash、sessionKey、note 和 restartDelayMs。一旦配置文件已经存在，这两种方法都需要 baseHash（不存在配置文件时的首次写入会跳过此检查）。

对于热应用的更改，这些 RPC 会等待活动 Gateway 应用该确切写入。通道或插件重载可能会因不相关的活动工作而延迟。由插件动态读取契约涵盖的纯策略写入（例如 Discord 允许列表和 DM/群组策略）无需通道重启或排空等待即可发布。同时包含需要重启的设置的写入仍保持为单个延迟事务。如果在等待期间文件监视器接管了同一未应用的写入，RPC 会通过重放保持挂起状态；仅持久化并不是应用确认。关闭、被不同内容取代或应用失败时，会返回带有恢复指引的 UNAVAILABLE。config.set 仅确认持久化。

当已提交的写入无法完成运行时应用时，错误的 details.persistedConfig 会在可用时包含脱敏后的已提交 config 及其公开 hash。此回执确认的是持久化，而非应用。客户端可以保留不相关的草稿编辑，并使用该修订版进行后续写入；常规的 baseHash 检查仍会拒绝中间发生的更改。重试未更改的补丁可能会返回无操作，这不会重新应用已保存的配置。请遵循错误信息中的 config.apply 或重启指引来恢复应用。带有回滚结果的发布失败不包含此回执。

channels.status 在 statusIssues 中报告活动工作的延迟情况，同时报告 Control UI 和 openclaw channels status 中显示的通道策略诊断。当某通道的重载被延迟时，channels.start 也会返回诊断信息；手动停止/启动仍继续使用已发布的运行时配置。请等待活动工作完成并刷新状态。这些诊断描述的是被延迟的通道重载，而非所有已持久化但未应用的配置状态。

一旦重载已提交，它会在应用更新的配置之前完成其模型和通道工作。如果该工作需要重启恢复，RPC 会返回 UNAVAILABLE；请等待 Gateway 重启，然后使用 config.get 验证活动修订版。

config.patch 还接受 replacePaths，这是一个配置路径数组，表示有意的数组替换或删除。如果补丁移除了现有数组条目或删除了数组，除非该确切的数组路径出现在 replacePaths 中，否则 Gateway 会拒绝该写入。删除包含数组的对象需要同时提供其内部数组路径，包括空数组。删除整个数组只需其自身路径，而不需要其条目内部嵌套数组的路径。请使用确切的记录键，例如 agents.entries.main.skills。对于按 ID 合并的条目更新，嵌套数组路径使用 []，例如 models.providers.custom.models[].input。父路径和 * 通配符不能授权后代数组。这可以防止截断的 config.get 快照静默覆盖路由或允许列表数组。当你打算替换整个配置时，请使用 config.apply。

具有稳定 id 字段的对象数组按 ID 合并，除非其路径出现在 replacePaths 中。这些更新会保留未触及条目中作者书写的字段；运行时默认值（例如模型目录兼容性和上下文预算）不会保存到同级条目中。显式配置的值仍具有权威性。