跳转至

配置热重载

配置热重载

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

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

agents.create、agents.update 和 agents.delete Gateway 方法会等待运行时应用完成后再报告成功。成功响应可让客户端立即创建会话或读取更新后的代理列表。如果配置已保存但无法应用(包括重载为 off 时),该方法会返回 UNAVAILABLE 并附带恢复指引,而不是报告代理变更已就绪。在重试已保存的变更之前,检查 config.get。

如果繁忙的状态存储暂时拒绝重载的生命周期租约,Gateway 会保持该变更待定,并自动以递增退避重试,最多在五秒退避后进行一次最终尝试。之前的运行时在变更应用之前保持活动。重试耗尽或不可重试的准入失败会向等待中的配置变更返回 UNAVAILABLE;后续的配置观察可以重试已保存的变更。关闭会取消重试并结束等待中的变更。重载失败在 Gateway 日志中仍然可见。

如果自动插件重载无法排空活动工作,Gateway 会记录失败并保持最后正常运行时。当排空在该插件已准入的工作上超时时,Gateway 会在工作完成后自动重试替换;无需额外的配置编辑。其他排空失败会等待 openclaw plugins reload <id> --wait 或回退待定的插件设置。在此之前,后续编辑不会重复排空,并且仍包含未应用插件设置的编辑会保持待定;它们不能通过无关的热更新发布这些设置,并且会与重试或恢复一起应用。当编辑待定期间,config.get 会报告一个与已保存修订不同的 appliedConfigHash,Control UI 将其显示为未应用的配置。openclaw plugins reload <id> --wait 还可让你监视超时的替换完成。重启 Gateway 会完整应用已保存的配置。

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

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

如果外部编辑在 Gateway 写入的最终重读期间导致配置缺失或无效,等待运行时应用的 config.patch 或 config.apply 会返回 UNAVAILABLE,并附带已提交的配置详情。它不会等待另一个文件事件。修复文件,运行 config.get,然后重新应用预期配置。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 并重启。重载从不迁移工作区状态。

重载模式

模式 行为
hybrid(默认) 应用可热重载的设置。需要时自动重启。
off 继续监视并验证配置。被动运行时更改等待手动重启;显式插件生命周期操作仍会应用。
{
  gateway: {
    reload: { mode: "hybrid" },
  },
}

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

哪些可热应用,哪些需要重启

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

  • Gateway 重启(restart):重启 Gateway 进程。
  • 热重载(hot):在保持 Gateway 进程 运行的同时应用更改。这可以包括重启所属子系统,例如频道、 cron 或 heartbeat。
  • 无重载操作(none):更新运行时配置快照,而 不为该路径安排重载操作。读取当前配置的消费者可在后续读取时观察到新值。

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

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

模型运行时选择会将您编写的设置与目录默认值分开。热重载和密钥重载会保留这种区分:目录兼容性元数据不会变成自定义请求覆盖,从而将原生运行时切换回 OpenClaw。 对 agents.defaults.models、代理模型选择和回退以及 models.providers 的更改会热应用,而不会排空 Codex 插件。更改 Codex 自身的插件设置仍遵循其插件重载策略。

agents.entries.<id>.tools.sandbox 下的代理沙箱工具允许/拒绝列表会热应用,而无需重启插件服务。Workboard 读取实时会话事实;File Transfer 仅针对工作区输入重新加载。

如果在配置热重载期间服务停止超时,该服务将保持受管并处于降级状态,同时 Gateway 继续提供服务。健康的服务可以完成其重载。警告会指明插件和服务;插件健康状态包含其服务故障。清理稳定后,重试 openclaw plugins reload <id> 以恢复受影响的插件。缓慢的服务清理不会安排 Gateway 重启。

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

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

类别 字段 是否需要 Gateway 重启?
频道 channels.*、web(WhatsApp) 取决于设置和已加载插件
代理与模型 agents、models、auth.order、auth.profiles、broadcast、worktreeRoot、worktreeAcceleration 否
自动化 hooks、cron、agents.defaults.heartbeat 否(重新加载所属子系统)
会话与消息 session、messages 否
工具与媒体 tools、skills、mcp 除 Apps 监听器设置外、audio、talk、tts、memory.citations、attachments.ttlHours 否
插件配置 plugins.entries.*、plugins.allow、plugins.deny、plugins.enabled、plugins.slots、plugins.load、旧版 plugins.installs 否(默认重新加载插件运行时)
类别 字段 是否需要重启 Gateway?
UI 及其他 ui, logging, identity, bindings, surfaces 否
审批与安装策略 approvals.exec, approvals.plugin, security.installPolicy, security.audit.suppressions 否(后续操作)
诊断与 ACP diagnostics.flags, diagnostics.cacheTrace.enabled, acp 否(后续操作)
更新与遥测 update.checkOnStart, update.channel, update.auto.enabled, telemetry.enabled, telemetry.consentedAt 否(下次检查)
托管 URL gateway.publicOrigin, mcp.apps.sandboxOrigin 否(新 URL、托管应用以及继承的浏览器源策略;被禁止的浏览器会重新连接)
Gateway HTTP API gateway.http.endpoints, gateway.http.securityHeaders.strictTransportSecurity 否(下次请求)
Gateway 工具与节点 gateway.tools, gateway.nodes.browser, gateway.nodes.pairing, gateway.nodes.commands, gateway.nodes.pluginTools.enabled, gateway.nodes.allowSkills 否
Gateway 客户端功能 gateway.cliAgents,以下选中的 gateway.controlUi 设置 否
Gateway 推送 gateway.push.apns.relay 否(下次推送)
Gateway 终端 gateway.terminal 否
桌面和 Cloud Workers desktop.host, cloudWorkers 否(协调所属服务)
Gateway 凭据 gateway.auth.token, gateway.auth.password,且有效认证模式相同 否(旧共享认证客户端会重新连接)
Gateway 访问策略 gateway.roles, gateway.trustedProxies, gateway.allowRealIpFallback, gateway.auth.allowTailscale, gateway.auth.identityScopes, gateway.auth.trustedProxy 否(客户端以当前权限重新连接)
会议捕获 transcripts.enabled, transcripts.autoStart 否(协调捕获写入器)
类别 字段 是否需要重启 Gateway?
Gateway 认证限制 gateway.auth.rateLimit 否(保留限流器状态)
发现可见性 discovery.mdns.mode 否(替换发现通告)
浏览器默认设置 browser.profiles, browser.defaultProfile, browser.headless, browser.executablePath, browser.attachOnly, browser.cdpUrl, browser.noSandbox, browser.extraArgs, browser.snapshotDefaults, browser.tabCleanup, browser.allowSystemProfileImport 否
浏览器控制策略 browser.enabled, browser.evaluateEnabled, browser.ssrfPolicy, browser.extensionRelay.allowLegacyAuth 否(替换浏览器控制服务)
Gateway 服务器 其他 gateway.* 设置(端口、绑定、认证模式、tailscale、TLS) 是
基础设施 其他 discovery 和 browser 设置、MCP Apps 监听器设置、secrets.egressProxy 是

通道插件声明哪些设置会重启其通道 (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) 适用于后续事件和准入。禁用收集会排空已接受的 写入;启用它不会重建更早的事件,也不会为已准入且原本没有身份的运行 添加身份。现有保留策略保持不变。

当选择 Memory Core 时,对 models.providers 的更改会重新加载其索引 服务。缓存的内存管理器在替换项使用新的提供者配置之前关闭, 因此更正嵌入端点或凭据不需要重启 Gateway。现有索引仍保留在磁盘上。

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

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

内部钩子更改会在发布前准备完整替换。 加载失败会保留之前的处理器;已在运行的事件会以其原始处理器完成。 工作区更改会从新选择的工作区重新加载目录钩子。 重新加载不会重放 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 服务和云 worker 继续运行。重新启用会恢复已配置的主机来源或现有的支持桌面的云 worker。云 worker 配置档预配仍然独立:settings.desktop 影响新预配的云 worker。

云 worker 配置档更改适用于新预配的云 worker。运行中的云 worker 保留其已接受的预配设置。保留计数和空闲暂停策略会与当前配置协调;更改超时时间会取消过时的排队暂停。仓库配置档默认值适用于未来的放置。

ACP 启用、调度、默认智能体、允许的智能体和后端策略适用于后续的准入和轮次。现有的运行时句柄在无关配置更改后继续存在;后端故障转移保留其配置的恢复行为。工作树加速适用于下一次分配或还原。

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

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

节点命令策略会立即更新已连接的节点。禁用节点发布的工具或技能会将其撤回;重新启用会在节点现有的配对批准范围内恢复最后一次发布。重新加载绝不会授予未经批准的命令。撤销命令会取消其活动调用,并拒绝后续的输入和结果。撤销桌面流式传输也会关闭其观察者传输通道。浏览器节点路由适用于后续操作。节点配对策略(gateway.nodes.pairing)也会热应用:待处理的自动批准在授予访问权限之前会重新检查当前策略,包括在 SSH 检查之后。现有已配对设备保持配对。终端 shell 更改适用于新打开的终端;活动终端保留其原始 shell。分离会话超时更改会根据每个终端的原始断开时间重新计算截止时间。已过期的会话立即关闭;附加的终端继续运行。终端启用也会热应用。禁用终端会关闭附加、分离和对话拥有的会话,并取消待处理的打开操作。重新启用允许新会话;已关闭的会话不会返回。重新加载已打开的 Control UI 页面以获取终端的内容安全策略。

不相关的延迟重启不会延迟已提交的终端启用或 shell 更改。待处理的重启仍可能使较早的终端或沙箱限制保持有效,直到该重启完成或其被拒绝的更改被还原。

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

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

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

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

Gateway 会接受其配置的密钥,无论客户端将其作为 token 还是密码发送;gateway.auth.mode 仍决定哪个配置值是密钥。

本地入门默认会生成 Gateway 密钥(gateway.auth.mode: "token"),而不会要求你选择身份验证机制。现有密码模式配置会被保留。若要显式选择自己的密码,请使用 openclaw onboard --gateway-password <value> 或 --gateway-auth password。远程入门会要求一个 Gateway 密钥,并将其存储为 gateway.remote.token。有关存储选项以及在不使用共享密钥的情况下连接,参见 Onboard。

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

Note

更改 gateway.reload 或 gateway.remote 也不会触发重启。

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

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

插件安装、更新、启用、禁用、卸载和元数据刷新通过正在运行的 Gateway 的插件生命周期应用,无需重启 Gateway。当被动重载为 off 时,显式插件操作也可用。源或清单编辑需要 openclaw plugins reload <id>。仅更改代理工作区不会刷新插件发现;请使用显式元数据刷新。参见 应用更改并检查 和 插件元数据快照。

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

如果插件替换在停止通道后超时,插件生命周期所有者会重试已准入工作的排空,最长 60 秒,然后使用新的注册恢复之前的代码和配置。成功恢复后,它会重启通道,并保留手动停止。未完成的写入会保留其资源所有权;它们永远不会被丢弃以强制替换。如果恢复达到截止时间或清理失败,操作将以失败结束并释放通道重载暂停。详细的 /ready 会报告 plugin-reload,并包含受影响的插件和恢复说明。一旦未完成的工作稳定下来,请重试 openclaw plugins reload <id>,或重启 Gateway。有关清理和所有权详细信息,参见 插件生命周期。

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

重载规划

当你编辑通过 $include 引用的源文件时,OpenClaw 会根据源编写的布局规划重载,而不是根据扁平化的内存视图。即使单个顶级部分位于其自己的包含文件中(例如 plugins: { $include: "./plugins.json5" }),这也能使热重载决策(热应用与重启)保持可预测。如果源布局不明确,重载规划会失败关闭。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw