配置 RPC（编程更新）

配置 RPC（程序化更新）

对于通过 gateway API 写入配置的工具，建议使用以下流程：

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

Agents 应将 config.schema.lookup 视为获取精确字段级文档和约束的第一站。在需要更广泛的配置映射、默认值或指向专用子系统参考的链接时，请使用 配置参考。

内置的 gateway 工具直接通过允许代理运行的网关调度配置读取，而无需打开环回 WebSocket。显式 gatewayUrl 或 gatewayToken 覆盖和独立本地代理仍使用网关客户端。两个路径使用相同的配置处理程序和读取范围。

部分补丁示例：

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

config.patch 在配置文件中记录显式提供的值，即使它们等于当前运行时默认值。未更改的运行时默认值将被忽略。其成功响应包括 changedPaths（验证和秘密恢复后更改的有效运行时路径）或 []（无操作）。这些路径不包含配置值；即使秘密值被编辑，客户端也可以使用它们来区分通道更改和不相关的写入。

对于仅需要提交确认的调用者，config.patch 也接受 response: "summary"。它从响应中省略了完整的配置。不需要运行时重新加载工作的更改摘要也省略了重新启动标记。维护可编辑配置草案（包括 Control UI）的客户端保留默认的完整响应，以便他们可以采用已提交的修订版本而不会丢失待处理的编辑。在任一模式下，验证、持久性和运行时应用程序都会在确认之前完成。

config.apply 和 config.patch 都接受 raw、baseHash、sessionKey、 note 和 restartDelayMs。一旦配置文件已经存在，两个方法都要求提供 baseHash（首次写入且不存在现有配置时会跳过检查）。

对于热应用的更改，这些 RPC 会等待活动网关应用确切的写入。频道或插件重新加载可能会因不相关的活动工作而推迟。插件的动态读取合约涵盖的仅策略写入（例如 Discord 允许列表和 DM/group 策略）无需通道重新启动或耗尽等待即可发布。还包含需要重新启动的设置的写入仍然是一项延迟事务。如果文件观察程序在等待期间接管相同的未应用的写入，则 RPC 通过重播保持挂起状态；单独的持久性并不是应用程序的确认。如果观察者在托管通知到达之前已经应用了确切保存的源，则 RPC 会确认已完成的应用程序，而无需再次解析机密或扫描技能。关闭、被不同内容取代或应用程序失败将返回 UNAVAILABLE 以及恢复指导。 config.set 仅确认持久性。

当提交的写入无法完成运行时应用程序时，错误的 details.persistedConfig 包含已编辑的提交的 config 及其公共 hash（如果可用）。该收据确认了坚持，而不是申请。客户可以保留不相关的草稿编辑并将该修订版本用于后续写入；通常的 baseHash 检查仍然拒绝干预更改。重试未更改的补丁可能会返回无操作，这不会重新应用已保存的配置。按照错误的 config.apply 或重新启动指南来恢复应用程序。具有回滚结果的发布失败不包括此收据。

channels.status 报告 statusIssues 中的活动工作延迟，以及 Control UI 和 openclaw channels status 中显示的通道策略诊断。当该通道的重新加载被推迟时，channels.start 还会返回诊断信息；手册 stop/start 继续使用已发布的运行时配置。等待活动工作完成并刷新状态。这些诊断描述了延迟的通道重新加载，而不是每个持久但未应用的配置状态。

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

config.patch 还接受 replacePaths，这是一个配置路径数组，其数组替换或删除是有意的。如果补丁删除现有阵列条目或删除阵列，网关将拒绝写入，除非确切的阵列路径出现在 replacePaths 中。删除包含对象需要其包含的数组路径，包括空数组。删除整个数组只需要其自己的路径，而不需要嵌套在其条目内的数组的路径。使用精确的记录密钥，例如 agents.entries.main.skills。对于 ID- 合并条目更新，嵌套数组路径使用 []，例如 models.providers.custom.models[].input。父路径和 * 通配符不授权后代数组。这可以防止截断的 config.get 快照默默地破坏路由或白名单阵列。当您打算替换完整配置时，请使用 config.apply。

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