配置热重载

配置热重载

网关自动应用修订后的配置快照。大多数设置不需要手动重启。 ~/.openclaw/openclaw.json 仍然是配置源，包括 JSON5、$include 和环境替换。

启动在完成之前等待配置观察程序的初始协调、排队的文件稳定性检查以及任何由此产生的重新加载尝试。初始配置发布无法与启动后的第一个请求竞争。保持有效配置不变的凭证刷新会保留待处理的工作，而不是使其配置快照无效。

通过正在运行的网关进行的写入将其提交的快照直接发布给重新加载所有者。它们不等待文件观察器事件或其反跳窗口。运行时使用者会继续读取上次成功应用的快照，直到替换事务提交。日志记录接受的源修订以及它是否来自网关写入或文件编辑。当其应用程序挂起时，稍后的热可重载写入不会删除已提交的重新启动要求。

如果重新启动准备或信号传送失败，网关会记录该失败并让重新启动处于挂起状态，而不自动重试。更正报告的问题，然后重新应用配置或手动重新启动网关。

UI 首选项保留在 ui.prefs 中。更改它们会保留准备好的模型目录、提供者身份验证和插件注册。显示更改仍会将更新的配置发布给读取这些设置的消费者。

agents.create、agents.update 和 agents.delete 网关方法在报告成功之前等待运行时应用程序。成功的响应可以让客户立即创建会话或读取更新的代理名册。如果配置已保存但无法应用，包括当重新加载为 off 时，该方法将返回 UNAVAILABLE 以及恢复指南，而不是将代理更改报告为就绪。在重试保存的突变之前检查 config.get。活动配置应用程序在下一个排队配置之前完成。当较新的配置保留待处理或未完成的网关写入更改时，该写入将等待较新的配置应用。覆盖未应用更改的取代编辑仍将先前的写入报告为未经确认。

仅代理编辑会保留未更改代理的会话准入和活动运行时间。创建过程在发布其配置条目之前准备新代理的运行时数据库。重叠的创建和删除将保持代理准备好的模型生成和会话创建不变。登记处发现是在完成名册发布之后进行的；删除代理仍然会撤销对该智能体店的访问权限。并发写入器通过共享写入器队列释放每个已完成的重新加载的生命周期租约，因此繁忙的数据库不会让稍后的重新加载等待租约到期。对删除代理的数据库开放拒绝使其他代理承认的工作可用。安排自己重试的心跳监视器协调不需要重新启动网关。热重载会记录警告并继续，而 cron 在 30 秒后重试，包括启动仍在稳定时。如果删除回滚，则通过重试来恢复因代理删除而推迟的监视器。重叠的代理编辑可以取代早期的模型运行时刷新。如果刷新失败，较新的配置将重试未完成的准备工作，而无需重新启动网关，包括当较新的编辑不更改模型时。如果该后继者无效或准备失败，则受影响的模型所有者可能会保持不可用状态，直到应用有效的配置为止。更正被拒绝的配置并重新应用它；即使未更改的有效配置也能完成待定的模型准备。

如果繁忙的状态存储暂时拒绝重新加载的生命周期租用，则网关会保持更改挂起并自动重试，并增加回退，最多在五秒回退后进行最后一次尝试。先前的运行时保持活动状态，直到更改应用。耗尽重试或不可重试的准入失败将 UNAVAILABLE 返回到等待配置突变；稍后的配置观察可以重试保存的更改。关闭会取消重试并解决等待的突变。重新加载失败在网关日志中仍然可见。

如果自动插件重新加载无法耗尽活动工作，网关会记录失败并保留最后的良好运行时间。当该插件承认的工作耗尽超时时，网关会在工作完成后自动重试替换；不需要额外的配置编辑。其他排出故障等待 openclaw plugins reload <id> --wait 或恢复挂起的插件设置。在此之前，以后的编辑不会重复消耗，并且仍包含未应用的插件设置的编辑仍处于待处理状态；他们无法通过不相关的热更新发布这些设置，并且它们与重试或恢复一起应用。当编辑待处理时，config.get 报告与保存的修订版本不同的 appliedConfigHash，Control UI 将其显示为未应用的配置。 openclaw plugins reload <id> --wait 还可以让您观看超时替换完成。网关重新启动会完整应用保存的配置。

直接文件编辑在验证之前将被视为不受信任。源的文件适配器等待编辑器 temp-write/rename 搅动稳定下来，读取最终文件，并拒绝无效的外部编辑，而不重写 openclaw.json。 OpenClaw- 拥有的配置写入在写入之前使用相同的模式门（有关适用于每次写入的 clobber/rollback 规则，请参阅 严格验证 ）。

该适配器还监视包含的文件并遵循编辑器重命名替换写入。本机文件事件会触发通常的重新加载反跳。后台协调每五分钟运行一次以恢复丢失的事件，因此没有本机事件的编辑最多可能需要五分钟才能被检测到。轮询和自动轮询回退保持现有间隔，包括 CHOKIDAR_INTERVAL 覆盖。所有重新加载消费者共享每个观察的快照；网关写入的文件系统回显保留该写入的应用程序接收和重新启动意图。写发布还会协调在其最终确定期间已经观察到的文件编辑，因此它不能丢弃挂起的外部更改。无效编辑会使最后一个良好的运行时保持活动状态。重新启动通过正常的启动验证和恢复路径读取相同的配置文件；源修订号是正在运行的网关的本地版本号。

如果外部编辑在网关写入的最终重读期间使配置丢失或无效，则等待运行时应用程序的 config.patch 或 config.apply 将返回 UNAVAILABLE 以及已提交的配置详细信息。它不等待另一个文件事件。修复文件，运行 config.get，然后重新应用预期的配置。网关不会覆盖外部编辑。

当网关应用最终重读所拾取的有效外部编辑时，保存的值被覆盖的等待写入会报告 superseded 而不是成功。保留已保存值的不相关编辑仍然可以成功完成。重新应用之前运行 config.get。

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

选择具有停用设置状态的工作区的实时更改也会被拒绝，并带有 openclaw doctor --fix 提示。网关保持其最后良好的运行时间。网关管理的写入，包括config.set，在持久化之前拒绝候选；即使观察者拒绝激活它们，来自单独 CLI 进程的手动编辑和写入也可以保留在磁盘上。停止网关，如果写入在持久化之前被拒绝，请在停止时保存预期的工作空间路径。然后运行openclaw doctor --fix并重新启动。重新加载永远不会迁移工作区状态。

重载模式

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

早期的 hot 和 restart 模式已弃用；openclaw doctor --fix 会将两者映射为 hybrid。重载防抖不再可配置，而是使用内置的默认值运行。

哪些更改会热应用，哪些需要重启

重新加载计划将每个更改的路径分类为以下三个结果之一：

• Gateway restart （restart）：重新启动Gateway进程。
• HHot 重新加载 （hot）：应用更改，同时保持网关进程运行。这可以包括重新启动所属子系统，例如通道、cron 或心跳。
• 无重新加载操作 （none）：更新运行时配置快照而不安排该路径的重新加载操作。读取当前配置的消费者可以在稍后读取时观察到新值。

在 hybrid 模式下，网关会在需要时自动重新启动。最长的匹配配置前缀决定结果。插件提供的规则仅在加载该插件时适用；不匹配任何规则的路径默认为网关重新启动。

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

模型运行时选择使您编写的设置与目录默认值分开。热重载和机密重载保留了这种区别：目录兼容性元数据不会成为将本机运行时切换回 OpenClaw 的自定义请求覆盖。对 agents.defaults.models、代理模型选择和回退以及 models.providers 热应用的更改不会耗尽 Codex 插件。更改 Codex 自己的插件设置仍然遵循其插件重新加载策略。重叠模型或凭证更改使用较新写入的运行时应用程序；取代早期出版物本身并不需要重新启动网关。

代理沙箱工具allow/deny列在agents.entries.<id>.tools.sandbox热应用下，无需重新启动插件服务。工作板读取实时会话事实；文件传输仅针对工作区输入重新加载。

如果在配置热重载期间服务停止超时，则该服务将保持所有权并降级，而网关继续提供服务。健康的服务可以完成它们的重新加载。警告命名插件和服务；插件健康状况包括其服务故障。清理完成后，重试 openclaw plugins reload <id> 以恢复受影响的插件。缓慢的服务清理不会安排网关重新启动。

通道传输编辑（例如 channels.slack.streaming.mode）保留准备好的会话行和模型目录。代理名册、会话策略、存储拓扑、配置的模型引用和通道激活仍然使它们受影响的事实无效。当模型或提供程序身份验证输入更改时，目录请求会等待替换发布，而不是报告启动未完成。

更改 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 的更改会刷新捕获这些策略的已加载通道运行时。手动停止的帐户保持停止状态，网关继续运行。

入站去抖设置 在下一次入站准入时应用，无需重新连接支持的通道。 messages.ackReactionScope 适用于后续匝数，无需重新连接 Discord、Matrix、Signal、Slack、Telegram 或 WhatsApp。其他频道插件会刷新，除非它们声明已实时阅读该政策。每个通道和每个帐户的覆盖仍然优先；承认的回合保留他们的政策。

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

审核收集（logging.audit.enabled、messages 和 executionIdentity）适用于后续活动和入场。禁用收集耗尽已接受的写入；启用它不会重建早期事件或将身份添加到已允许的运行中，而无需事件。现有保留政策不变。

当选择内存核心时，更改为 models.providers 重新加载其索引服务。缓存内存管理器在替换使用新的提供程序配置之前关闭，因此更正嵌入端点或凭据不需要重新启动网关。现有索引保留在磁盘上。

操作设置适用于下次使用；它们不会重新启动运行中的运行或重新创建配置的工作线程。批准有效期的变更会影响新发放的补助金。附件保留更改适用于下一次清理扫描，包括已经早于新限制的文件。

更新和遥测设置适用于下一次计划检查。挂起的自动更新倒计时会在开始之前重新检查启用和通道选择；已应用的更新保留其承认的目标。更改这些设置不会强制更新。在下一次更新检查请求之前再次读取遥测同意。

内部挂钩更改在发布之前准备完整的替换。加载失败会保留之前的处理程序；已经运行的事件以其原始处理程序结束。工作区更改从新选择的工作区重新加载目录挂钩。重新加载不会重播 gateway:startup。

根据 gateway.controlUi、enabled、environment、github、sessionObserver、embedSandbox、allowExternalEmbedUrls、experimental.customPlugins、experimental.claws 和automaticallyFetchFavicons 设置热应用。重新加载打开的 Control UI 页面以选取环境标签、CLI 代理选择器、嵌入首选项和图标显示首选项； Gateway 进程继续运行。 allowedOrigins 和 dangerouslyAllowHostHeaderOriginFallback 也热应用：待处理的握手重新检查新策略，并且浏览器连接不再允许关闭。删除已承认的浏览器源也会撤销其已接受的运行和委派的工作，即使在连接关闭后也是如此；删除不相关的来源则不会。禁用 Control UI 将停止提供仪表板页面和资产并取消待处理的资产准备。现有网关连接和代理运行继续。重新启用会在后台准备丢失的仪表板资产；请求返回 503 直到准备好。 Control UI 服务路径仍然需要网关重新启动。

自定义插件 UI 更改连接的 Control UI 页面中的刷新插件视图。禁用它会删除自定义视图并阻止新的自定义本机 UI 加载；重新加载浏览器选项卡以清除已运行的插件 JavaScript。捆绑的插件视图和后端插件操作仍然可用。

主机桌面和云工作桌面交换机无需重新启动网关即可更新连接的桌面选择器。主机连接更改（managed、port 和 passwordFile）会在下次使用创建替换源之前取消现有观测值和计算机保留。禁用源会关闭其桌面观察。现有系统 VNC 服务和云工作人员保持运行。重新启用将恢复配置的主机源或现有的支持桌面的工作人员。云工作人员配置文件配置保持独立：settings.desktop 影响新配置的工作人员。

云工作人员配置文件更改适用于新配置的工作人员。正在运行的工作人员保留其承认的配置设置。储备计数和空闲暂停策略与当前配置相一致；更改超时会取消过时的排队暂停。存储库配置文件默认值适用于将来的放置。

ACP 启用、调度、默认座席、允许座席和后端策略适用于后续的准入和轮流。现有的运行时句柄可以承受不相关的配置更改；后端故障转移保留其配置的恢复行为。工作树加速适用于下一次分配或恢复。

会议捕获更改通过记录所有者进行协调。添加的源开始，删除或更改的源耗尽，未更改的捕获继续运行。标题编辑适用于未来的捕获并保留现有的文字记录标题。禁用记录存储会阻止捕获编写者，但不会结束会议。

角色定义、代理信任、身份范围、Tailscale 身份验证和可信代理策略实时应用。运输政策的变化可能需要重新握手，而不会取消已接受的运行。代理标头、OIDC 映射、设备自动批准和代理地址会更改栅栏连接，但在所有者的授权未更改时保留已接受的工作。这包括 sessions.create 提交新会话后请求的初始轮次。编辑另一个登录名的身份范围或重新排序相同的范围可以使连接及其接受的运行保持活动状态。更改所有者的身份范围授权、从代理白名单中删除该身份或禁用其身份验证方法都会撤销保留和委派的工作，即使授权随后恢复也是如此。共享秘密轮换还会撤销使用旧凭证承认的工作。角色限制仍然由每次运行的权限强制执行。接受的策略写入可以完成它们的响应；后续请求必须根据当前传输策略重新进行身份验证。更改身份验证模式或侦听器拓扑仍需要重新启动网关。

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

浏览器默认配置文件更改适用于下一个请求。下次使用时，启动设置更改将替换受影响的托管浏览器进程；外部连接的浏览器保持运行。浏览器启用、评估和 SSRF 策略更改仅替换浏览器控制服务：挂起的操作取消，并在新策略应用之前关闭拥有的 Chrome 进程。当 OpenClaw 断开其控制会话时，连接的和远程浏览器进程保持打开状态。启用后，浏览器控件会根据需要再次启动；不再保留已退役进程中的托管选项卡。更改分机中继传统身份验证取代了拥有的中继代；外部管理的中继守护进程保留自己的生命周期和策略。快照默认值适用于下一个快照，选项卡清理设置适用于下一次扫描。

TLS 证书续订监视正在运行的网关接受的证书、密钥和 CA 路径中的文件。有效的替换材料可更新现有和未来的 HTTPS 侦听器、发现和配对指纹，而无需中断连接。不完整或无效的替换会保留之前的材料。重装模式 off 暂停更新；重新启用检查暂停时所做的更改。 TLS 配置和路径更改仍然需要重新启动网关。远程证书密码仍由操作员控制；请参阅 网关 TLS。

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

发现模式更改会替换当前的通告，而不会中断网关连接。从 full 切换到 minimal 会从 LAN 通告和任何配置的广域 DNS-SD 区域中删除额外的 TXT 提示。 off 停止 LAN 通告，同时配置的广域发现保持启用状态。 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> 下的编辑默认替换受影响的实例，并使用其新配置重新运行注册。未更改的插件实例保留其注册快照。插件的较窄重新加载策略可以保留实例或需要重新启动。

当模型、harness、CLI 后端和会话扩展事实保持不变时，插件配置编辑会保留缓存的会话行。当这些事实发生变化时，完成的模型目录出版物会刷新受影响的代理；不相关的挂钩设置或插件启用不会重建整个会话列表。

插件安装、更新、启用、禁用、卸载和元数据刷新适用于正在运行的网关的插件生命周期，无需重新启动网关。当被动重新加载为 off 时，显式插件操作也有效。源或清单编辑需要 openclaw plugins reload <id>。单独更改代理工作区不会刷新插件发现；使用显式元数据刷新。请参阅 应用更改并检查 和 插件元数据快照 。

代理请求等待开始暂停，而插件热重载会耗尽旧的运行时。当准备就绪时，它们会继续替换，或者在成功回滚后继续替换之前的运行时。您无需重新发送这些请求。恢复失败或网关关闭仍报告失败。已经承认的轮次通过嵌套模型工作保留其运行时生成。不相关的插件拥有的设置不会使准备好的 chat.send 无效；会话、模型、工具策略和核心插件准入策略更改仍会重新检查用于准入的事实。如果替换在激活之前失败，回滚将恢复之前配置的模型上下文限制，而无需等待模型发现。

如果停止通道后插件替换超时，插件生命周期所有者会重试承认的工作消耗最多 60 秒，然后再使用新注册恢复以前的代码和配置。它会在成功恢复后重新启动通道并保留手动停止。未完成的写入保留其资源所有权；它们永远不会被丢弃以强制更换。如果恢复达到截止日期或清理失败，操作将以失败结束并释放通道重新加载暂停。详细的 /ready 报告 plugin-reload 以及受影响的插件和恢复说明。一旦未完成的工作解决，请重试 openclaw plugins reload <id>，或重新启动网关。有关清理和所有权详细信息，请参阅 插件生命周期。

在通道或插件热重载期间，网关托管的通道 Webhook 路由返回 503 和 Retry-After: 1，直到替换入口寄存器。发件人必须尊重重试响应；这并不承认交货。禁用或删除的帐户、手动停止以及取消的更换生命周期会释放这些临时路由。当替换入口报告准备就绪时，未回收的旧路径将被删除。

重载规划

当您编辑通过 $include 引用的源文件时，OpenClaw 计划从源创作的布局（而不是展平的内存中视图）重新加载。即使单个顶级部分位于其自己的包含文件（例如 plugins: { $include: "./plugins.json5" }）中，这也可以使热重载决策（热应用与重新启动）保持可预测性。如果源布局不明确，则重新加载计划将停止。