配置热重载

配置热重载¶

Gateway 会自动应用带修订号的配置快照。大多数设置无需手动重启。~/.openclaw/openclaw.json 仍然是配置源，包括 JSON5、$include 和环境变量替换。

通过正在运行的 Gateway 进行的写入会将其已提交的快照直接发布给重载所有者。它们不会等待文件监听事件或其防抖窗口。运行时消费者会继续读取最后成功应用的快照，直到替换事务提交。日志会记录已接受的源修订号，以及它来自 Gateway 写入还是文件编辑。后续可热重载的写入不会在其应用待处理期间清除已提交的重启要求。

如果繁忙的状态存储暂时拒绝重载的生命周期租约，Gateway 会保持该更改待处理，并自动以有上限的退避重试。无需额外的配置编辑。之前的运行时保持活动，直到更改应用，关闭会取消待处理的重试。其他重载失败仍会显示在 Gateway 日志中。

直接文件编辑在通过校验前被视为不可信。源文件适配器会等待编辑器临时写入/重命名抖动平息，读取最终文件，并拒绝无效的外部编辑，且不会重写 openclaw.json。OpenClaw 拥有的配置写入在写入前使用相同的模式门控（参见 严格校验，了解适用于每次写入的覆盖/回滚规则）。

适配器还会监视包含的文件，并跟随编辑器的重命名-替换写入。所有重载消费者共享每次观察的快照；Gateway 写入的文件系统回声会保留该写入的应用回执和重启意图。写入发布还会协调在其最终化期间已观察到的文件编辑，因此不会丢弃待处理的外部更改。无效编辑会保留最后正常运行时处于活动状态。重启会通过正常的启动校验和恢复路径读取相同的配置文件；源修订号仅对正在运行的 Gateway 本地有效。

如果你看到 config reload skipped (invalid config) 或启动报告 Invalid config，请检查配置，运行 openclaw config validate，然后运行 openclaw doctor --fix 进行修复。参见 Gateway 故障排查 获取检查清单。

选择具有已退役设置状态的工作区的实时更改也会被拒绝，并附带 openclaw doctor --fix 提示。Gateway 会保留其最后正常运行时。Gateway 管理的写入（包括 config.set）会在持久化前拒绝候选项；手动编辑和来自单独 CLI 进程的写入可能仍保留在磁盘上，即使监视器拒绝激活它们。停止 Gateway，并且如果写入在持久化前被拒绝，请在停止期间保存预期的工作区路径。然后运行 openclaw doctor --fix 并重启。重载从不迁移工作区状态。

重载模式¶

{
  gateway: {
    reload: { mode: "hybrid" },
  },
}

早期的 hot 和 restart 模式已退役；openclaw doctor --fix 将两者都映射到 hybrid。重载防抖不再可配置，并在内置默认值下运行。

哪些可热应用，哪些需要重启¶

重载规划将每个更改的路径分类为三种结果之一：

• Gateway 重启（restart）：重启 Gateway 进程。
• 热重载（hot）：在保持 Gateway 进程运行的同时应用更改。这可能包括重启拥有该路径的子系统，例如 channel、cron 或 heartbeat。
• 无重载操作（none）：更新运行时配置快照，但不为该路径调度重载操作。读取当前配置的消费者可以在后续读取时观察到新值。

在 hybrid 模式下，需要时会自动发生 Gateway 重启。最长匹配的配置前缀决定结果。插件提供的规则仅在该插件加载时生效；不匹配任何规则的路径默认执行 Gateway 重启。

默认情况下，更改 agents.defaults.mediaMaxMb 会重启 channel 运行时，以便其继承的附件限制一起生效。自动重载会保留手动停止的账户；请使用显式 channel 启动来恢复这些账户。

模型运行时选择会将你编写的设置与目录默认值分开。热重载和密钥重载会保留这种区分：目录兼容性元数据不会变成自定义请求覆盖，从而将原生运行时切换回 OpenClaw。

对 channel 传输的编辑（例如 channels.slack.streaming.mode）会保留已准备的 session 行和模型目录。Agent 名册、session 策略、存储拓扑、已配置的模型引用以及 channel 激活仍会使受影响的事实失效。当模型或提供商身份验证输入发生变化时，目录请求会等待替换发布，而不是报告启动未完成。

更改 session.store 不会迁移对话。绑定到先前物理存储的排队通知会以记录的 store-replaced 结果结束。待处理的子结果投递会暂停，同时结果和已完成任务仍可用于显式恢复；再次选择旧存储不会自动重新启用该投递。保持同一存储的替换和进程内重启会保留排队通知的交接。

频道插件会声明哪些设置会重启其频道（reload.configPrefixes），哪些设置无需重新加载操作（reload.noopPrefixes）。例如，在加载 WhatsApp 后，channels.whatsapp.enabled 会重启 WhatsApp 频道，而 channels.whatsapp.replyToMode 匹配其更宽泛的无操作前缀。

对 channels.defaults、channels.modelByChannel、commands、accessGroups、tts、surfaces、acp.stream 和 diagnostics.flags 的更改会刷新已加载的频道运行时，这些运行时捕获了相应策略。手动停止的账户将保持停止状态，Gateway 会继续运行。

入站防抖设置 在下次入站准入时生效，无需重新连接受支持的渠道。 messages.ackReactionScope 对后续轮次生效，无需重新连接 Discord、Matrix、Signal、Slack、Telegram 或 WhatsApp。其他渠道插件 会刷新，除非它们声明会实时读取策略。按渠道和 按账户的覆盖设置仍然优先；已准入的轮次保留其策略。

diagnostics.enabled 会实时更新诊断分发和心跳所有权。 加载 diagnostics-otel 后，diagnostics.otel 仅重启其导出器服务， 在启动新服务之前先刷新旧代。外部预加载的 OpenTelemetry 提供者保留其传输和关闭所有权。

审计收集（logging.audit.enabled、messages 和 executionIdentity） 适用于后续事件和准入。禁用收集会排空已接受的写入；启用它不会重建更早的事件，也不会为已准入且原本没有身份的运行添加身份。现有保留策略保持不变。

操作设置在其下次使用时生效；它们不会重启进行中的运行 或重新创建已预配的工作节点。审批过期变更会影响新签发的 授权。附件保留变更在下次清理扫描时生效，包括 已经比新限制更旧的文件。

更新和遥测设置在下次计划检查时生效。待处理的 自动更新倒计时在启动前会重新检查启用状态和渠道选择；正在应用的更新保留其已准入的目标。更改这些 设置不会强制更新。在下次更新检查请求之前，会重新读取遥测同意。

内部钩子变更在发布前会准备一个完整替换。加载 失败会保留先前处理器；已在运行的事件会以其原始处理器完成。工作区变更会从新选择的工作区重新加载目录钩子。重新加载不会重放 gateway:startup。

在 gateway.controlUi 下，enabled、environment、github、 sessionObserver、embedSandbox、allowExternalEmbedUrls、experimental.customPlugins 和 automaticallyFetchFavicons 设置会热生效。重新加载已打开的 Control UI 页面， 以获取环境标签、CLI 代理选择器、嵌入偏好和 favicon 显示偏好；Gateway 进程继续运行。allowedOrigins 和 dangerouslyAllowHostHeaderOriginFallback 也会热生效：待处理的握手会重新检查新策略，不再被允许的浏览器连接会关闭。 移除一个已准入的浏览器源也会撤销其已接受的运行和委派的工作，即使连接已关闭；移除无关源则不会。 禁用 Control UI 会停止提供仪表板页面和资源，并取消 待处理的资源准备。现有 Gateway 连接和代理运行继续。 重新启用会在后台准备缺失的仪表板资源；在它们就绪之前，请求返回 503。Control UI 服务路径仍需要 Gateway 重启。

自定义插件 UI 变更会刷新已连接 Control UI 页面中的插件视图。 禁用它会移除自定义视图并阻止新的自定义原生 UI 加载； 重新加载浏览器标签页以清除已经运行的插件 JavaScript。捆绑插件 视图和后端插件操作仍然可用。

Host Desktop 和 Cloud Worker Desktop 开关会更新已连接的桌面选择器， 无需 Gateway 重启。主机连接变更（managed、port 和 passwordFile）会在下次使用创建替换源之前，退役现有观察和计算机占用。禁用某个源会关闭其桌面观察。 现有系统 VNC 服务和云工作节点继续运行。重新启用 会恢复配置的主机源或现有具备桌面能力的工作节点。 Cloud Worker 配置预配保持独立：settings.desktop 影响 新预配的工作节点。

Cloud Worker 配置变更适用于新预配的工作节点。运行中的工作节点 保留其已准入的预配设置。预留数量和空闲挂起 策略会根据当前配置进行协调；更改超时会取消 过期的排队挂起。仓库配置默认值适用于未来放置。

ACP 启用、分发、默认代理、允许代理和后端策略 适用于后续准入和轮次。现有运行时句柄可以存活于 无关配置变更；后端故障转移保留其配置的恢复行为。Worktree 加速适用于下一次分配或恢复。

会议捕获变更会通过转录所有者进行协调。新增源 会启动，移除或变更的源会排空，未变更的捕获继续运行。 标题编辑适用于未来捕获，并保留现有转录标题。 禁用转录存储会停止捕获写入器，而不会结束其会议。

角色定义、代理信任、身份范围、Tailscale 身份验证和 可信代理策略实时生效。传输策略变更可能需要新的 握手，而不会取消已接受的运行。代理头、OIDC 映射、设备 自动批准和代理地址变更会隔离连接，但在所有者授权不变时保留已接受 工作。这包括在 sessions.create 提交其新会话后请求的初始轮次。编辑另一个登录的身份范围 或重新排序相同范围会保持连接及其已接受运行处于活动状态。 更改所有者的身份范围授权、从代理 允许列表中移除该身份，或禁用其身份验证方法会撤销保留和委派 工作，即使之后恢复授权。共享密钥轮换也会撤销 使用旧凭据准入的工作。角色限制仍由每个 运行的权限执行。已接受的策略写入可以完成其响应；后续 请求必须在当前传输策略下重新身份验证。 更改身份验证模式或监听器拓扑仍需要 Gateway 重启。

节点命令策略会立即更新已连接节点。禁用节点发布的 工具或技能会撤回它们；重新启用会在节点现有配对批准内恢复最后一次发布。重新加载绝不会授予未批准命令。 撤销命令会取消其活动调用，并拒绝后续输入和 结果。撤销桌面流也会关闭其观察者传输。浏览器 节点路由适用于后续操作。节点配对策略 （gateway.nodes.pairing）也会热生效：待处理自动批准在授予访问前会重新检查 当前策略，包括在 SSH 探测之后。现有 已配对设备保持配对。终端 shell 变更适用于新打开的 终端；活动终端保留其原始 shell。分离会话超时 变更会从每个终端的原始断开时间重新计算截止时间。 已过期会话会立即关闭；附加终端继续运行。 终端启用也会热生效。禁用终端会关闭附加、 分离和对话拥有的会话，并取消待处理打开。重新启用 允许新会话；已关闭会话不会返回。重新加载已打开的 Control UI 页面以获取终端的内容安全策略。 无关的延迟重启不会延迟已提交的终端启用或 shell 变更。待处理重启仍可使较早的终端或沙箱限制 保持生效，直到该重启完成或其被拒绝的变更被回滚。

浏览器默认配置文件的更改将在下一次请求时生效。启动设置更改会在受影响的受管浏览器进程下次使用时替换这些进程；外部附加的浏览器保持运行。浏览器启用、评估和 SSRF 策略更改仅替换浏览器控制服务：在新策略生效前，待处理操作会取消，所拥有的 Chrome 进程会关闭。附加和远程浏览器进程保持打开，OpenClaw 会断开其控制会话。启用后，浏览器控制会按需再次启动；已退役进程中的受管标签页不会保留。更改扩展中继旧版身份验证将替换所拥有的中继代；外部管理的中继守护进程保留其自身的生命周期和策略。快照默认值应用于下一次快照，标签页清理设置应用于下一次清理扫描。

TLS 证书续期会监视运行中网关所接受的证书、密钥和 CA 路径上的文件。有效的替换材料会更新现有和未来的 HTTPS 监听器、发现以及配对指纹，且不会中断连接。不完整或无效的替换材料会继续使用之前的材料提供服务。重载模式 off 会暂停续期；重新启用后会检查暂停期间所做的更改。TLS 配置和路径更改仍需要重启网关。远程证书固定保持由操作员控制；请参阅 Gateway TLS。

身份验证速率限制更改会保留已记录的失败、已获得的锁定截止期限以及待处理的环回延迟。新的限制和环回豁免适用于后续尝试；收紧尝试次数限制可能会根据保留的失败记录锁定客户端。移除 gateway.auth.rateLimit 会恢复默认值。浏览器来源和节点重新批准预算仍不豁免。

发现模式更改会替换当前通告，而不会中断网关连接。从 full 切换为 minimal 会从局域网通告中移除额外的 TXT 提示以及任何已配置的广域网 DNS-SD 区域。off 停止局域网通告，而已配置的广域网发现保持启用。Bonjour 插件必须已启用，且环境覆盖仍然适用。

网关会接受其配置的密钥，无论客户端以令牌还是密码形式发送；gateway.auth.mode 仍决定哪个配置值作为密钥。

本地引导默认生成一个网关密钥（gateway.auth.mode: "token"），而不会要求您选择身份验证机制。现有的密码模式配置会保留。要显式选择您自己的密码，请使用 openclaw onboard --gateway-password <value> 或 --gateway-auth password。远程引导会要求提供一个网关密钥，并将其存储为 gateway.remote.token。有关存储选项以及无需共享密钥即可连接的信息，请参阅 Onboard。

仅当有效身份验证模式保持不变时，令牌和密码轮换才会热生效。使用旧共享凭据的现有客户端必须使用新凭据重新连接；独立配对的设备令牌客户端保持连接。从旧共享凭据派生的浏览器设备令牌也会被撤销。对于 SecretRef 凭据，请显式设置 gateway.auth.mode，使轮换符合热重载条件。身份验证模式更改仍会重启网关。

Canvas 启用使用插件热重载。其托管能力发生更改的当前协议节点会重新连接以接收新的能力 URL；其他当前协议节点和操作员连接保持打开。旧版节点在托管表面描述符更改时重新连接，以便重新计算其协议限制。待处理的节点握手在准入前也会重新检查这些能力。

普通运行时查找使用缓存的插件清单，并且不会扫描插件文件。在混合模式下，对 plugins.entries.<id> 下的编辑默认会替换受影响的实例，并使用其新配置重新运行注册。未更改的插件实例保留其注册快照。插件较窄的重载策略可以保留实例或要求重启。

插件安装、更新、启用、禁用、卸载和元数据刷新都会通过运行中网关的插件生命周期应用，而无需重启网关。显式插件操作在被动重载关闭时也有效。源代码或清单编辑需要 openclaw plugins reload <id>。仅更改代理工作区不会刷新插件发现；请使用显式元数据刷新。请参阅 Apply changes and inspect 和 Plugin metadata snapshots。

插件热重载排空旧运行时时，等待启动的代理请求会暂停。当替换就绪后，它们会继续使用替换运行时；成功回滚后，则使用之前的运行时继续。您无需重新发送这些请求。恢复失败或网关关闭仍会报告失败。如果替换在激活前失败，回滚会恢复之前配置的模型上下文限制，而无需等待模型发现。

如果插件替换在停止通道后超时，插件生命周期所有者会重试已受理工作的排空，最多 60 秒，然后才恢复之前的代码和配置并使用全新注册。恢复成功后，它会重启通道，并保留手动停止状态。未完成的写入保留其资源所有权；它们绝不会为了强制替换而被丢弃。如果恢复达到截止时间或清理失败，操作会以失败结束，并释放通道重载暂停。详细的 /ready 会报告 plugin-reload，其中包含受影响的插件和恢复说明。待未完成工作平息后，重试 openclaw plugins reload <id>，或重启网关。有关清理和所有权详细信息，请参阅 Plugin lifecycle。

在通道或插件热重载期间，由 Gateway 托管的通道 webhook 路由会返回 503，并附带 Retry-After: 1，直到替换入口完成注册。发送方必须遵守 重试响应；这并不确认投递。被禁用或移除的账户、手动停止以及已取消的替换生命周期会释放这些临时路由。 当替换入口报告就绪时，其未回收的旧路径将被移除。

重载规划¶

当编辑通过 $include 引用的源文件时，OpenClaw 会基于源文件编写的布局来规划 重载，而不是基于扁平化的内存视图。即使某个顶级章节位于其自身的包含文件中（例如 plugins: { $include: "./plugins.json5" }），这也能让热重载决策（热应用与重启）保持可预测。 如果源布局存在歧义，重载规划会失败关闭。