更新如何运行

通道切换、更新验证、重启切换和 Git 签出流程。 openclaw update 参考的一部分。

它的作用

显式切换通道（--channel ...）也会保持安装方式一致：

• dev -> 创建或重用 git checkout（默认 ~/openclaw，或设置 OPENCLAW_HOME 时的 $OPENCLAW_HOME/openclaw；用 OPENCLAW_GIT_DIR 覆盖），更新它，并从该签出安装全局 CLI。
• stable -> 使用 latest 从 npm 安装。
• extended-stable -> 解析公开的 npm extended-stable 选择器，验证所选中的确切包，并安装该精确版本。它不会回退到其他选择器，也不允许用于 Git 检出版本。
• beta -> 优先使用 npm dist-tag beta，当 beta 缺失或比当前稳定版更旧时回退到 latest。

新的克隆在发表前经过验证。如果在验证过程中替换了目标或暂存文件夹，更新将停止而不更改替换。选择一个空的 OPENCLAW_GIT_DIR 并重试。

验证和激活

就绪检查在本机服务检查、侦听器检查、经过身份验证的 RPC 和 HTTP 就绪情况方面共享总体截止日期。网络探测器的每个请求限制不会缩短本机检查。缓慢的检查仍然会消耗共享的截止日期，因此无法延长更新的总体预算。这些检查属于已安装的更新程序；候选者无法更改旧更新程序已经运行的就绪等待。

在替换相同的安装之前，更新程序会观察现有网关一次。准备失败会产生警告并阻止自动回滚重新启动；更新程序不会等待现任者恢复后再进行替换。替代品仍会收到完整的启动和就绪验证。验证植根于不同安装的服务，或验证重新启动后恢复的服务，仍需在现有准备预算范围内等待。

在 Windows 上，即使启动程序进程树发生更改，候选命令也会验证其记录的切换租约及其自己的 PID/start 身份。不同的直接父级不再导致有效候选者失败并出现 Candidate executor binding does not match its parent。更新所有者必须保持活动状态，并且更改或撤销的租约仍然拒绝突变。此检查在候选版本中运行，因此它也接受来自较旧安装的更新程序的有效切换。

如果服务刷新在写入其定义之前被拒绝，则候选者会将原始拒绝保留在其输出中。然后更新程序可以重新验证并重新启动保留的服务定义。本地服务权限的实际损失仍然使恢复悬而未决，直到可以验证所有权和恢复为止。

在 Linux 上，服务刷新修复 group/other-writable 单元文件和旧安装程序创建的旧备份，前提是它们是安全目录中服务帐户拥有的常规文件。它备份先前的定义并使用仅限所有者的权限重新生成单元和备份。不安全的目录、外国所有权、符号链接和受保护的安装仍然拒绝替换。此修复在候选安装程序中运行，包括当旧安装的更新程序调用它时。

负载会减慢更新而不是造成故障：启动检查和恢复积压使安装所有者的有限准备预算内的验收保持待定状态。托管发布控制器等待标记代理的准入和响应网关，并仅在证明所选进程正常后才使用其原始幂等性密钥重试超时标记调度。恢复的前任使用相同的接受规则。错误的身份、物理损坏、错误的标记回复或耗尽准备预算仍然需要故障恢复。

通道探测失败、通道停止和运行状况收集超时是更新后验证期间的警告。网关仍必须回答、报告预期版本和构建、通过 HTTP 准备情况，并通过正常的运行状况检查。同样导致 HTTP 就绪失败的通道故障仍然无法验证。即使稍后的探测完成，超时警告仍保留在更新报告中；运行openclaw health检查受影响的通道。七秒收集预算不变。更新的网关还避免将收集超时报告为旧更新程序的负面探测，尽管这些更新程序无法将新警告添加到其更新报告中。

如果解析的注册表包版本等于已安装的版本，且未更改所选渠道或安装方法，或者 Git 目标 SHA 等于 HEAD 并且已安装的运行时通过工件验证，则插件收敛仍会运行；如果插件和运行时工件保持不变，则运行将完成 skipped，原因为 already-current。因此，运行时维护可以在不更改 Git 版本的情况下成功。相同版本的显式 --channel 或安装方法更改成功完成。更改的插件会重新启动正在运行的托管网关，除非设置了 --no-restart；保留的精确引脚会产生与核心更新相同的建议，而无需重新启动。

如果 Git 签出在未重建的情况下进行，或者其运行时缺少或未经验证的工件，则匹配的源版本仍然需要更新。验证检查构建提交、构建标记、运行时条目、Control UI 资产、版本和构建标识。 OpenClaw 构建并验证单独的候选者，然后在替换运行时并重新启动之前停止托管网关。新的构建会记录其提交，因此下一次更新可以像当前一样完成。 --no-restart 无法替换同一安装中正在运行的网关所使用的运行时文件；更新使这些文件保持完整并报告进程和 stop/retry 操作。

停止共享此安装的另一个网关可以保护其运行代码；它不会迁移该网关的单独状态。如果其旧状态需要迁移，请在该服务自己的帐户、配置文件和环境下运行更新后的 CLI 的 doctor --fix，然后再恢复。 Doctor 可能会自行恢复服务，因此请在通过服务管理器再次启动之前检查其状态。

当该安装的网关正在运行时，使用 pnpm openclaw 启动的源命令也会拒绝自动重建。使用结账时安装的 openclaw update 或 node openclaw.mjs update 来达到更新程序的托管切换，而无需首先重建源包装器。手册 pnpm build 仍然是操作员操作：在重建其安装之前停止网关。

该决定在已安装的更新程序中运行。返回 already-current 和 runtime-verification-failed 的较旧更新程序无法从它从未构建的候选程序中获取修复程序。通过其实际的服务管理器停止网关，重建结帐，并在重试之前通过该管理器启动网关。当旧网关仍在运行时，请勿重建其安装。

当核心已经是最新的或设置了 --no-restart 时，Linux 更新还会刷新过时的 OpenClaw- 管理的 systemd 策略。此仅策略刷新确认 daemon-reload，无需停止网关并保留操作员插入。 launchd、计划任务和 systemd 上的本机定义协调通过建议保留自定义策略值，同时刷新已识别的旧默认值。例如，TimeoutStartSec=45 保持不变，而旧安装程序值 TimeoutStopSec=30 变为 330。现有的身份和命令检查仍然适用。维护停止还会读取驻留网关记录的关闭预算。如果回滚发现服务已经停止，无法到达网关，并且其本地端口空闲，则直接通过受保护的本机停止进行恢复，而不是等待耗尽期限。正在运行的网关和未经验证的服务或端口状态保持正常的排水检查。发布 2026.9.5 的居民即使在 daemon-reload 之后仍保留其启动预算；因此，他们的第一站使用 short/unknown-budget 路径。网关的生命周期所有者会限制准入并报告耗尽进度，直到空闲或现有更新步骤截止日期（默认为 30 分钟，自动更新为 45 分钟）。在该截止日期之前，剩余的回合可能会被中断，并在更新历史记录中发出警告；报告的写入保管拒绝停止并指定其所有者阶段。没有可选的writeCustody观察的居民无法区分备份或迁移保管与普通root/cron工作。在截止日期前，他们会发出警告，指出这些计数；丢失监护信息永远不会阻止更新。下一个网关以刷新的服务策略开始。仍然缩短本机超时的操作员插入被保留并报告。

由于运行时文件不可用而拒绝连接的已替换网关将通过其服务所有者停止并发出警告，而不是等待它无法提供服务的 RPC。对于已发布的 June 网关发出的较旧错误，这还需要与拥有的服务 PID 匹配的实时旧锁和本地侦听器。在停止之前会重新检查侦听器所有权、锁定和本机服务身份。缺少侦听器属性或不相关的连接错误会保持正常的排出路径。

维护消耗使用服务的本地凭据，包括在未配置共享令牌或密码时的现有配对操作员身份。它不会创建身份或请求新的配对。忽略此标识的较旧安装的更新程序可以报告 device identity required 并等到其现有的耗尽截止日期，然后再停止并发出警告。新的候选者无法更改已经运行的更新程序；后续更新在安装后使用更正的本地控制客户端。

显式包工件（例如 tarball 路径和 URL）会在相同版本无操作之前比较已知的构建 ID。匹配已知身份使包裹保持不变；不同或缺失的标识会在正常的更新验证和安装过程中继续存在，因为仅匹配版本并不能建立工件相等性。注册表请求保留其基于版本的相同版本无操作。即使其构建标识匹配，安装方法切换和新配置文件初始化仍会保留并验证新版本。

当一次性验证副本清理、停用的派生缓存清理或 Git 上游跟踪设置失败时，更新会继续并记录警告。解决报告的原因，然后运行警告的确切清理命令或 openclaw doctor --fix。无效的所有权、不安全的状态迁移以及无法启动或通过就绪状态的网关仍然会阻止完成。请参阅 状态和历史记录 以检查记录的警告。

Linux 服务检查将隐式 systemd 设备名称及其显式安装名称视为相同的选择，包括带或不带 .service 后缀的名称。在停止网关之前，更新程序仍会重新检查服务所有权。

Linux 用户服务停止在更新和独立 openclaw gateway stop 期间使用相同的顺序：检查管理器路线，检查当前托管，然后停止所选单元。管理器检查有自己的 60 秒宽限，并会重试一次短暂超时并记录警告。第二次超时指定了停止的检查并让原始网关继续运行；所有权拒绝永远不会重试。安装的更新程序拥有此序列，因此候选者无法更改旧更新程序在首次更新期间的停止行为。

不可用的服务检查会生成记录的 managed-service 警告，包括手动重新启动操作。过时的、不可检查的服务记录无法选择更新的包根、Node 可执行文件或状态目录。暂存、验证、安装和 Doctor 最终确定在调用安装中继续。医生保留未经验证的服务记录不变并报告建议；状态协调员和数据库租约仍然保护活跃的写入者。

为了使用单独的、未更改的安装恢复托管服务，OpenClaw 会重新检查其服务定义、运行时 pin、包目录和版本、启动器、Node 可执行文件、构建标识和架构支持。它不会对安装的整个包树进行指纹识别；更新期间该树中其他位置的编辑将尽最大努力。保持修改任一安装的工具停止，直到更新完成。

为回滚而保留的包的基线指纹是尽力而为。如果其有界扫描超时或达到其字节或条目限制，则更新会记录警告并继续使用保留的包目录。然后回滚验证恢复的目录身份、软件包版本和受影响的启动器，并记录完整指纹验证不可用。仅扫描预算不会导致更新或回滚失败；不可用或更改的目录标识、无效的包元数据以及受影响的启动器故障仍然拒绝恢复。一旦获得完整的基线指纹，恢复检查必须与其匹配。这些检查使用调用者的每步限额，没有单独的三十秒扫描上限。如果保留或恢复的包发生更改，则故障会指定要在重试恢复之前检查的确切包路径。同级 .openclaw.update-stage-* 目录位于该包指纹之外；不要删除其他更新程序可能仍在使用的阶段。

启动器备份验证保存的文件字节或符号链接目标。重新创建等效的 npm 或 Homebrew 启动器不会使恢复无效，因为其 inode、时间戳或所有权元数据已更改。更改后的符号链接目标仍然拒绝交换并命名两个目标；文件系统突变所有权检查仍然有效。此修复属于已安装的更新程序，因此候选者无法在第一次更新期间更改旧更新程序的启动器检查。

在 POSIX npm 安装上，发布准入会在暂存之前检查现有包目录或源链接条目和标准启动器。源链接检查不需要外部结帐的所有权。在验证之前，将根据暂存的候选程序检查其他启动器目标；不相关的前缀文件将被保留。所有权拒绝会命名对象路径、其所有者 UID 以及预期的 UID。可写前缀父代如 bin 和 lib/node_modules 可能属于另一个 UID；它们的目录标识在发布和恢复期间仍然必须保持不变。已发布的对象和私有恢复工件保留其所有权检查。此准入行为属于已安装的更新程序，因此它无法修复已运行的旧更新程序中的检查。

日志拥有的发布和回滚还会比较启动程序字节或链接目标，而不需要非根更新程序无法恢复的 uid/gid 元数据。在更换之前，他们仍然需要记录的启动器身份。新的符号链接尽可能保留现有启动器的所有权；否则，他们将使用更新程序的有效用户和组，而不是继承不可用的 bin 目录组。所有权回退会产生警告。

包发布会验证激活前的候选包和发布后已安装的包。启动器发布会检查包身份，而无需重复对两代进行哈希处理。退役在删除过时的备份之前验证实时包；回滚仍然会在恢复之前对备份进行哈希处理并验证恢复的字节。这些改进属于已安装的更新程序，不会更改已运行的旧更新程序。

保留更新程序的运行时会跳过包恢复锚点、控制日志以及已安装包旁边的固定证据。即使硬链接未更改的恢复文件也会更改其元数据，并可能使旧的密封助手的指纹失效。拒绝那些恢复工件的显式运行时链接；对于其回收者来说，证据仍然没有受到影响。

当文件系统支持时，未更改的保留运行时文件使用硬链接。保留在链接之前验证每个源并检查生成的 inode 和元数据，而无需重新哈希由其自身链接引起的更改时间的字节。需要独立插件安全检查或重新定位的文件仍然使用经过验证的副本。

当其扫描达到资源限制时，候选验证使用相同的尽力而为合同：激活和发布继续进行目录标识、包版本和启动器验证，记录完整的包内容未经验证。阅读器允许 500,000 个条目/8 GiB；共享的截止日期仍然限制了扫描时间。扫描完成后，其指纹仍必须匹配。

当完全验证可用时，这些检查会遍历每个条目以验证身份、元数据、目录列表、链接和最终元数据扫描。仅当文件的完整元数据（包括 inode、链接计数、大小、修改时间和更改时间）未更改且其更改时间比先前读取的时间早至少五秒时，才会重用来自早期基线或暂存包扫描的文件内容摘要。在准备期间太新的文件在稍后成功验证观察到它们已解决后将变得合格；随后的出版物检查重复使用该观察结果，同时仍与原始包装指纹进行比较。恢复助手和后续命令重新读取文件内容。与元数据扫描一样，这些检查观察包而不是锁定它：通过已修改的共享内存映射进行写入可能不会更新文件时间。在更新期间保持其他修改安装的包管理器和工具停止。

未来安装的更新程序会在短期工作线程中对包文件进行哈希处理，并进行同步读取，一次最多四个文件。密封恢复助手使用相同的路径；如果工作线程不可用，则哈希在进程内运行。根据上述规则重用摘要的文件不会被重新读取；所有其他文件都会在工作人员中重新读取。异步目录遍历、串行最终元数据重新检查和截止日期均保持不变。较旧安装的更新程序保留其自己的扫描行为。

已发布的 2026.9.7 和 2026.9.8 更新程序仍然使用自己的 50,000 条目/1 GiB 候选上限；候选人无法更改已安装的驱动程序。对于 2026.9.8 或更早版本的主管版本（包括预发布），候选准入会拒绝具有超过 50,000 个条目的树，并指示您手动运行 npm i -g openclaw@latest（指定时保留请求的版本或标签）。这会计算包根目录和每个条目，包括隐藏的锁定文件，而不遵循符号链接。新主管不会收到这种尺寸的拒绝。

以 Package rollback verification entry limit exceeded 或 Package rollback verification byte limit exceeded 停止的较旧安装的更新程序同样需要安装的 手动包更新方法 ，并具有经过验证的备份和在替换期间停止的托管网关。

在激活记录失败的 interrupted 历史条目之前中断新的本地更新，同时其安装所有者仍被保留。预激活中断不是成功的更新或经过验证的回滚。未解决的影响在更新报告中仍然可见。不受支持的挂起检查点记录会阻止进一步的可变更新工作并保持不变。

在激活或验证期间，SIGINT、SIGTERM 和 SIGHUP 停止转发工作并保留更新程序，直到其现有恢复所有者尝试恢复网关并写入故障报告。恢复使用更新的现有预算和 package/state 安全检查。报告列出了中断的相位和信号；使用 openclaw update status，如果恢复仍处于待处理状态，则使用 openclaw update repair。这需要在已安装的更新程序中进行修复；新候选人无法改变老司机的信号处理方式。 SIGKILL 无法运行此清理，仍然需要显式恢复。

目标Doctor迁移共享状态后，安装的目标运行时拥有数据库验证、服务完成和更新历史记录写入，包括回滚结果。父更新程序保留其实时安装和请求者检查，而无需通过其旧架构重新打开迁移状态。成功的迁移将进入最终确定阶段；它仍然禁止仅代码回滚。

对于支持安装前检查的版本，旧网关继续通过staging和validating提供服务。更新程序使用新版本运行运行状况检查 （doctor --lint --json --severity-min error）、配置验证以及只读插件解析和兼容性规划。它还测试迁移并使用复制的配置启动测试网关，并在隔离的临时状态目录中验证 SQLite 快照。复制的数据库注册表指向复制的代理数据库。安装的插件有效负载及其依赖项也会被复制；复制的安装记录指向这些副本，其 OpenClaw 主机链接以分阶段安装为目标。对共享源模块的文字导入、require() 调用和文字动态导入将这些模块及其包元数据包含在私有副本中。不相关的存储库文件保留在快照之外。

插件快照使用 SHA-256 验证库存字节。当旧网关服务时，本机同伴捕获可能会添加或删除硬链接；仅链接元数据更改不会使 Windows 或 POSIX 上未更改的文件无效。内容、文件标识、类型、权限、所有权、大小和修改时间更改仍然拒绝快照。

此检查属于已安装的更新程序。在本机捕获期间报告 Plugin entry changed after snapshot inventory 的较旧更新程序无法从已验证的候选程序中获取此修复。使用安装的 手动更新方法，并使用经过验证的备份，并且托管网关在软件包替换期间停止。

在每个候选检查开始之前，更新程序都会命名检查和命令。这些进度消息通过 --json 发送到 stderr，将 JSON 结果留在 stdout。安装的更新程序拥有这些公告，因此较旧的更新程序在安装此版本后的下一次更新中会获得这些公告。

插件依赖项清单会跳过名为 <destination>.openclaw-update-<UUID>.tmp 的偶然 Git 运行时事务目录。他们的候选者和回滚内容保持不变；显式引用的依赖项仍会进行正常验证。其他临时目录仍然是插件输入。这可以防止废弃事务的重定位链接阻止不相关的更新。

此清单在已安装的更新程序中运行。在这些事务目录之一内出现 Cannot privately copy plugin dependency 失败的旧更新程序需要安装的 手动更新方法 才能使用修复程序。保留事务内容，直到任何活动更新或回滚得到协调。

当已发布的更新程序从外部插件副本中省略共享模块时，新版本的Doctor可以在加载插件修复挂钩之前完成私有副本。恢复需要该更新程序保留的原始路径和匹配的 source/manifest 字节；它永远不会替换现有的私有文件或更改服务插件。完整快照不需要原始源保持可用。一些较旧的托管状态或跨卷投影不保留可恢复的原始路径，Doctor 在更新诊断中报告了这一点。

解析为正在运行的包的捆绑插件的路径别名使用具有相同 ID 的分阶段捆绑插件（如果可用），从而保留捆绑信任。外部路径安装保留其现有分类。实时插件文件和主机链接保持不变。通道、cron、自动更新和其他辅助服务在此金丝雀中被抑制。复制的数据库会经历相同的架构检查和迁移，而不会恢复已删除的任务注册表。金丝雀还将会话目录水合、子代理和工作线程恢复以及启动维护推迟到激活，并记录警告。在准备就绪之前，所需的配置、数据库所有权、架构和迁移检查仍会运行；插件运行时加载仍然是验证的一部分。服务网关在激活后正常准备其会话目录和维护。

在复制状态之前，更新程序承认其现有模式进度编写器并通过验证保留该连接。因此，进度写入使共享数据库的 WAL 文件保持可用，同时 SQLite 获取一致的快照。连接重用其承认的模式事实，而每次写入仍检查当前权限、源身份和模式更改。这可以防止进度记录本身中断复制；完整性和替换检查保持启用状态。安装的更新程序必须包含此修复程序。新候选人无法更改旧驱动程序的初始快照行为。

初始进度接收拒绝会在状态复制或子启动之前停止验证。如果保存已完成的检查失败，更新程序将保留报告错误；该检查保留其成功结果并且不会再次报告。更新程序仍然解决拥有的子进程和临时副本清理问题。当阶段处于活动状态时，进度错误会保留该阶段的现有故障和清理处理。

金丝雀通过后，更新程序将临时副本清理和先前的网关准备情况验证记录为活动步骤。 openclaw update status，包括--json，显示记录的操作、等待原因、开始时间和预算。每个检查阶段内，准备情况观察最多每 30 秒刷新一次。验证检查托管服务、侦听器身份、已安装的 version/build、运行状况 RPC 和 HTTP 就绪情况。其隐含津贴是金丝雀启动持续时间的十倍，最短五分钟，上限一小时；显式的 --timeout 优先。天花板为缓慢的硬件保留了空间，同时限制了对已经服务的网关的观察。到期时会记录一条警告，并继续处理未验证的先前网关准备情况；自动回滚无法重新启动未经验证的先前网关。运行openclaw gateway status --deep --require-rpc进行检查。

每次清理一次性副本有五分钟的时间。如果删除时间较长，更新会记录警告并继续；删除可能仍会在后台完成。该警告命名了临时路径并解释了更新程序退出后的清理工作。这些进度改进需要在下一个更新跃点上修复更新程序。已经运行的 2026.9.5 更新程序保留其原始静默验证窗口；独立的 openclaw gateway status --deep --require-rpc 和 /readyz 检查可以显示旧网关是否仍在服务，但不能确定更新程序的等待原因。

更新结果、openclaw update 输出和运行历史记录记录私有状态副本 （candidate-state-snapshot）、排练医生 （candidate-doctor）、测试网关启动 （candidate-gateway-startup） 和临时副本删除 （candidate-state-cleanup） 的定时步骤，包括 Git 更新。激活还记录 post-stop-checks（网关停止后的架构、工件和配置检查）和 git-runtime-activation。更新程序启动的每个 Doctor 都会添加一个 Doctor sections: … 诊断及其数据库预检、配置和贡献时间，以及最慢的贡献。当旧的诊断被修剪时，运行历史记录会保留这些行。已安装的更新程序会记录这些步骤，因此它们首先出现在安装此版本的更新之后。

该报告还保留了 updater-runtime-retention，它衡量在突变之前保留正在运行的更新程序的包、构建的运行时和依赖关系树。这与私有状态快照是分开的，并且可以在以前的网关仍在服务时运行。本机服务工作记录 managed-service-executor-check 与成功的 managed-service-install 或 managed-service-restart 子项分开。 update-driver-handoff 测量从前一个驱动程序上次完成的接收到新驱动程序恢复完成的时间间隔。切换计时器可以出现在安装更新上；保留和服务计时器要求执行这些操作的更新程序包含此检测。

更新构建和验证过程从分阶段安装根解析源链接的插件 SDK，即使服务源启动器通过了自己的签出根。这使得分阶段资产和验证独立于旧的结帐。

医生警告不会阻止更新检查或插件更新后的准备情况。更新程序将它们保留在 openclaw update status 显示的运行报告中，包括当有意的开放通道策略不需要配置更改时。所需的配置、状态安全和就绪失败仍然拒绝更新。安装软件包后，如果没有明确的编写器或迁移拒绝，则失败的插件后 Doctor 进程会记录警告。更新程序仍然验证最终配置和准备情况，然后启动网关。无法确认终止的子进程仍处于阻塞状态，因为它仍可能写入状态。

离线 Doctor cron 检查在备份边界后重用其承认的维护读取器，而不是创建另一个一次性 SQLite 快照。如果可选的内存梦想 cron 所有权检查不可用，Doctor 会保留现有行和挂起的插件修复，记录警告，并继续核心恢复。运行 openclaw doctor --fix 重试该检查。 Cron 重写和所需的状态迁移失败保留了现有的安全检查。

Doctor 的一次性数据库迁移和修复连接使用 64 MiB SQLite 页面缓存余量来减少重建大型存储时的重复读取。当每个连接关闭时，津贴结束；服务连接保留其现有的缓存策略。转录转换还在准备导航元数据时重用解析后的 JSON，保留原始转录字节。当较旧的更新程序调用新的 Doctor 时，这些候选端改进将适用；它们不会更改更新程序的截止日期、完整性检查或回滚规则。

在私人迁移预演中，Doctor lint 将可选的核心检查推迟到激活后。这包括每个代理模型和工具架构诊断；当这些检查被推迟时，lint 不会准备其运行时元数据。每个省略的检查都会记录一个警告及其检查 ID 和更新后运行的命令。所需的迁移、配置、插件和网关准备情况检查仍在运行。独立 Doctor lint 和明确选择的 --only 检查保持其正常范围。候选者可以识别已发布的 2026.9.4 更新程序设置的私有副本标记，因此这也减少了第一跳的工作。当更新程序是 2026.10.1 或更高版本时，每个检查都有自己的时间预算，因此候选者从该检查开始时测量其可选检查窗口；慢速状态快照或 Repair Doctor 不会导致 lint 推迟检查。对于较旧的更新程序，该窗口仍会在验证开始时启动。

排练修复医生还推迟了纯粹的咨询检查，包括安全性、提供程序目录和运行时工具模式诊断，并在其输出中记录它们的 ID，而不消耗修复警告槽。还进行修复的贡献仍在排练中，包括身份验证配置文件、插件运行状况修复、技能、记忆回忆和会话记录。实时交换后医生和最终准备情况检查保持其现有范围。此节省适用于提供私有副本标记的已发布 2026.9.3–2026.9.6 更新程序；老司机保持现有的行为。

这些检查不会运行代理轮次或需要可用的模型身份验证路由。 OAuth-仅安装和没有提供商凭据的安装可以更新。 Auth 诊断是建议性的；仅在失败的更新解决后，可选的推理修复才会通过分类运行。它使用正常的运行时凭证解析器，包括共享配置文件和 OAuth 刷新。

新版本在加载配置或初始化调试捕获之前回答了更新程序的本机服务能力检查。检查功能不会打开或迁移共享状态，因此旧网关可以在其数据库模式比新版本旧的情况下继续提供服务。首先运行已安装的更新程序；当它检查的版本包含修复程序时，此修复生效。

调用更新程序提供功能检查的每步时间预算。该检查不会强制规定单独的启动期限。

快照准备预算 SQLite 数据库和日志字节的时间，包括复制和验证过程，启动时间为五分钟。它使用该限额和配置的每步超时中的较大者。截止日期延长，而私人文件继续发生变化。停滞的快照报告其大小和应用的预算。快照时间不消耗单独的运行时验证预算。每个验证过程都会收到一个新的配额，该配额会根据测量的数据库和插件字节进行扩展。明确的每步超时取代了派生的限额。在保留其自己的运行时的同时，更新程序直接报告已完成的文件操作，而不是重复扫描不断增长的副本。如果这些操作停止完成，隔离文件系统检查仍会跟踪缓慢的单个副本。当安装的更新程序包含修复程序时，此改进适用。自动和聊天更新留下了从状态派生的运行时间津贴。他们的请求和恢复看门狗不会成为更新验证的最后期限。启动和准备响应共享自己的津贴，包括读取响应正文。从一组固定的启动事件中完成候选 CLI 和 Gateway 启动里程碑后，各更新该津贴一次；超过最初的截止日期会记录一条警告，而启动仍在继续进行。未知名称将被忽略并在调试级别记录。检查回复不会更新津贴。即使里程碑提前，总的就绪等待时间也不能超过初始限额的四倍。达到该上限会拒绝候选人并记录经过的时间和达到的里程碑，而之前的网关保持不变。退出或停止前进的候选者无法通过其最后的启动证据进行验证。没有启动证据的无法访问的检查和配置的代理失败仍然是警告。这种进度感知等待属于已安装的更新程序。已发布的 2026.9.4 更新程序在检查较新的候选者时保留其固定的五分钟上限。

在复制更新演练期间，候选 Doctor 在进行插件检查之前发布其 lint 报告。其私有状态保持所有权，直到处置完成或拥有的检查员进程树被确认停止为止。处置津贴遵循测量的检查时间和剩余的已发布驱动程序窗口；超限记录警告及其持续时间。这还允许需要零进程退出的 2026.9.4 驱动程序在仅处理速度较慢时完成。主管发起的处置终止保留对 Windows 以及 macOS 和 Linux 的已完成检查。呼叫者取消和独立失败退出仍然是失败。

当候选 Doctor 完成检查但其流程或输出管道在超出限额后仍保持打开状态时，更新程序会记录退出阶段警告并继续处理已完成的结果。 Lint 完成需要孩子完整的 JSON 报告；先前修复的 Doctor complete. 行无法证明 lint 成功。错误结果仍然拒绝验证。没有完成结果的孩子会报告 candidate-checks-timeout、检查阶段和已用时间。

这些截止日期属于调用更新程序。已发布的 2026.9.3 和 2026.9.4 更新程序将其完整排练（包括快照）限制在五分钟内，而随后的模式检查则限制在三十秒内，即使使用 --timeout 900 也是如此。安装较新的候选者无法延长第一次更新时的父进程截止日期。后续更新将使用上述较新更新程序的配额。检查无法在 2026.9.4 排练的五分钟窗口内完成的主机仍需要 手动升级恢复路径。

在复制之前，更新程序会测量共享和代理 SQLite 数据库系列以及更新检查所需的已安装插件有效负载和依赖关系树。入场费包括临时副本和新版本的 Doctor 备份的空间。活动插件有效负载保留在快照中，以便配置和启动验证可以加载它们；未引用的插件生成不会被复制。

更新程序选择第一个具有足够测量可用空间的可用目标：

1. 设置时为显式 TMPDIR。
2. <state-dir>.update-captures/ 下的私有目录，位于其文件系统上选定的状态目录旁边。
3. 系统临时目录。

更新报告记录测量的 SQLite 和插件大小、所需的总空间、检查的目标及其可用空间以及选择的位置和原因。如果都不适合，快照准备将在使用 snapshot-capacity-insufficient 复制之前拒绝，并解释如何释放空间或设置 TMPDIR。无法分配的路径被记录并跳过；如果所有适配路径均不可用，则 snapshot-location-unavailable 命名其路径或权限错误。容量检查不会为并发写入保留空间。复制工作人员使用库存插件计划。如果安装记录、插件所有者或数据库注册在其副本之前发生更改，则准备工作会拒绝该未测量的状态，以便下次更新可以再次对其进行盘点。这些副本保持一次性验证状态；回滚不会恢复它们。如果甚至最初的 SQLite 检查副本也无法容纳，则拒绝报告需要下限并将插件大小标记为尚未检查。

快照放置属于已运行的更新程序。已发布的 2026.9.3 和 2026.9.4 更新程序在新版本代码运行之前准备快照，因此更新到此修复程序无法更改第一跳。如果系统临时文件系统太小，请选择另一个有足够空间的文件系统：

TMPDIR=/var/tmp openclaw update --yes

后续更新使用新更新程序的测量目标选择。

快照创建会检查源和最终转换输出的完整 SQLite 完整性和外键一致性。它在私有发布暂存中验证转换后的输出一次，并在使快照可用之前验证其确切字节。相同的检查涵盖恢复备份。这可以避免重复的全数据库扫描，而无需更改备份或回滚合同。已发布的 2026.9.7 更新程序选择自己的快照工作程序，因此其初始快照不会从第一次升级时的此更改中受益。选择暂存候选者工作线程的更新程序可以使用候选者的快照实现。

实时快照使用 SQLite 读取事务和私有备份，同时写入继续。工件保留规划和医生检查保留字节中立副本，使源 SHM 保持不变。 WAL 副本在经过验证的 WAL 生成中捕获有界前缀，因此附加提交不需要安静的数据库。不完整的 WAL 系列和崩溃日志会私下恢复，而不会创建丢失的源 sidecar。检查预算包括数据库和日志大小、冷启动以及对每个发现的存储重复进行 IO 传递。元数据检查仍然可以取消。复制进度会更新看门狗，并保留更大的调用者配额。工人们在私人舞台被拆除之前停下来；清理失败会保留原始错误。如果无法验证兼容性，则拒绝回滚。检查失败报告数据库或已知范围、检查阶段、已用时间和下一步操作。在重试之前检查对指定路径的访问、并发编写器和存储性能。无法报告当前数据库的年长候选工作人员会识别已知范围。

如果初始配置检查遇到 SQLite 锁争用或更改快照源，更新程序将重复读取一次。成功读取会记录警告并让目标选择继续。腐败和其他检查错误仍然是失败。一旦新的数据库准入成功，预登台故障将在更新历史记录中保留其原始诊断和下一步操作；未解决的恢复所有权仍然会阻止终端发布。

此检查行为属于调用更新程序。已发布的 2026.9.4 更新程序在暂存候选程序之前仍然可能会失败。在这种情况下，请使用安装的 手动更新方法，然后从更新的安装运行 openclaw update repair。

在停止前一个网关之前，更新程序会等待确认准备就绪。它的观察窗口使用金丝雀测量的启动时间以及慢速硬件的余量，或明确的每步超时。短暂的就绪性未命中不会放弃上一代的回滚资格。通过最终观察，本机服务和网关启动标识仍必须匹配。

测试网关绑定一个空闲环回端口，并且必须将 /startupz 报告为 started，然后 /readyz 在运行时验证限额内准备就绪。归因于命名插件的插件解析错误会被记录，但不会拒绝更新。无效的插件清单、未归因的注册表错误或未能满足所需的核心启动或准备情况检查仍然会导致验证失败。故障记录阶段、经过的时间和有限的诊断。更新程序尝试进​​程树终止和临时状态清理。如果有界拆卸不能确认终止请求完成和子关闭，它会与验证结果分开记录维护警告。准备就绪、子进程关闭和临时副本清理并不能证明每个后代都停止了。临时副本清理仍然是尽最大努力。该报告属于调用更新程序；新版本无法更改旧更新程序的拆卸行为。启动检查证明新版本的核心在复制状态下启动；激活后会检查直播频道和提供商的行为。迁移继续之前的目标将运行时验证记录为不可用，并使用当前更新程序的现有最终化路径。具有无效模式契约的当前延续条目仍然拒绝激活。数据库架构预检仍然拒绝不兼容的降级。这些较旧的目标不支持自动模式中立回滚；请参阅 降级完成 。

阻止验证失败会丢弃分阶段更新，而不停止服务网关。更新程序不会运行推理或修复一次性验证副本。在失败的更新解决并释放其所有权后，符合条件的失败可以进入失败后分类。分类保留最初的失败结果；修复的安装不会使更新成功。参见无人值守维修。

已发布的 2026.9.4 更新程序仍然可以向候选程序请求推理修复工作程序。候选者保留该线路协议并返回修复不可用，而无需加载推理或更改操作员状态。安装的更新程序仍然拥有第一跳及其失败报告。

仅 activating 停止托管服务。其离线工作包括包或签出交换、所需的 doctor --fix 迁移和状态兼容性检查，然后在 restarting 中启动服务。更新验证不使用模型推理。在 verifying 中，更新程序检查托管服务是否正在运行并拥有其端口，需要正常的 12 检查运行状况解决和与预期版本和 Git 构建身份匹配的网关问候握手，并需要来自 /readyz 的 HTTP 200。当这些核心检查通过时，插件激活或加载失败仍然会出现命名警告；它们不会将成功的核心更新变成错误。核心验证成功后，通道探测错误、超时以及停止或抑制的通道将成为命名警告。运行openclaw channels status --probe或openclaw health --json进行诊断；它们不会阻止经过验证的包备份失效。

来自 2026.9.3 的托管更新可以通过新运行时完成迁移，同时原始更新程序保留安装所有权。在完成 Git 或 npm 安装之前，新的运行时会根据其实时父级检查捕获的更新身份。此延续不会改变下面的恢复限制。

验证失败时新版本可以运行。恢复指导使用最新观察到的服务状态，并在已知时命名正在运行的版本；较早的激活停止并不意味着服务保持停止状态。

如果更新恢复发现其托管服务仍然停止，则未经验证的服务定义或安装程序备份收据不会禁止启动已安装的运行时。更新程序保留现有定义，重新验证服务所有权，通过服务所有者重新启动，并验证正常准备情况。成功恢复完成，但会出现警告，并保留 openclaw update repair 的程序包备份。启动失败会报告其具体错误，并将您定向到 openclaw update repair 和 openclaw gateway status --deep。只有指定的数据风险，例如不稳定的 Doctor 编写者或未经验证的迁移状态，才会指示您保持网关停止。

重生和更新验证使用与网关重新启动相同的进度感知就绪等待。持续取得进展的初创公司可以使用现有的五分钟启动租约。如果该租约结束时同一网关仍在进行中，则验证结束时会出现警告和原因 still-starting。该进程保持运行，恢复备份仍然可用，并且更新程序不会再次重新启动它、回滚它或指示您使其保持停止状态。直接更新程序验证报告 skipped，因为准备情况尚未验证。对于前台 RPC 切换，替换网关保留最终验证：运行保持待定状态，并保留其继续，直到启动验证解决。尚未观察到的版本是未知的；版本不匹配需要观察到的服务版本与安装的目标不一致。

当正在运行的网关的准备时间到期，而重新启动所有者报告正在等待侦听器、启动迁移或健康稳定时，更新程序会将经过的等待和启动阶段记录为警告。它让进程继续启动，保持准备状态未确认，并保留恢复备份。运行以 gateway-readiness-unverified 的原因结束 skipped，记录有意的未经验证的结果，而不是成功或无限期的挂起运行。仅 PID 或引导生成更改不会导致此等待失败；当前的运行状况、版本、构建和侦听器检查仍然适用。在停用这些备份之前检查 openclaw gateway status --deep。单独的超时并不授权恢复重启或回滚；拒绝回滚也不会影响候选者。单独的运行状态、对已建立的侦听器的失败检查或 HTTP /readyz 故障不会确定启动进度。这些不健康的服务观察和具体版本、构建或停止服务故障仍然是其自身诊断的故障。 Doctor 将合格的启动超时明确报告为 gateway-readiness-unverified，包括在迁移完成之后，并告诉操作员准备就绪情况尚未确认。

此警告处理属于已运行的更新程序。完成迁移更新时，已发布的 2026.9.3 和 2026.9.4 父级无法区分挂起的就绪状态和已验证的成功，因此仅候选更新无法更改其备份停用和 Windows 自动启动决策。已发布的 2026.9.4 运行时在验证其启动的子进程时还保留了自己的十秒重生运行状况等待。安装新版本无法更改已经运行的等待。当新的运行时拥有重生时，包括由其驱动的后续升级，共享重生准备等待适用；当旧更新程序将工作交给已安装的运行时时，候选端重新启动验证将使用新所有者。

在托管网关重新启动之前，插件包会下载并与已安装的目标同步。通过 channel/config 写入、插件聚合以及任何所需的完​​整 Doctor 迁移，服务仍保持停止状态。因此，下载次数计入停机时间。未更改的插件使用只读验证和就绪检查，无需另一个完整的 Doctor pass。服务所有权在收敛后重新验证，最终运行时验证检查生成的快照。

在 Windows 上，计划任务自动启动保持暂停状态，直到候选终结器激活更新的网关。迁移后，保留的更新程序检查其实时执行程序租约，而无需重新打开较新的状态数据库。当候选者完成激活时，插件版本漂移仍然是一个警告。当更新的驱动程序运行下一次升级时，此切换修复适用；它无法更改已运行的 2026.9.5 更新程序。如果旧驱动程序因恢复挂起而停止，请使用已安装版本的 openclaw update repair。

如果在 Windows 任务自动启动最初暂停时中断，更新程序将在退出之前恢复其先前的自动启动设置。恢复仍需要原始实时更新所有者和任务身份。该中断处理属于已经运行的更新程序；正在进行的旧更新程序会保留其现有行为。

当 Doctor 在修复写入开始之前无法获得维护时，最终确定会恢复其停止的任何服务，并成功退出并记录警告。这包括来自未知或非服务进程的锁争用。医生和插件的融合仍悬而未决；解决指定的拒绝并再次运行 openclaw update repair。延迟完成不会确认之前中断的更新或将挂起的迁移标记为完成。实时或未经验证的网关、主动迁移写入、不可读状态、不完整迁移和未解决的清理仍然会失败，而不是释放其恢复义务。

此行为存在于已安装的终结器中，因此已发布的更新程序在调用新版本的 update finalize 时可以使用它。年长的父母可能会在自己的总结中忽略警告；终结器打印它并将其记录在更新历史记录中。

恢复限制

软件包更新在实时 Doctor 迁移之前捕获经过验证的 SQLite 备份。共享数据库和每个发现的代理数据库都保存在 <package-backup>.databases 中保留的包旁边。快照名称使用备份存档的源路径布局，因此在压缩详细的运行历史记录后，它们的原始目标仍然可识别。报告保留目录位置；每个文件的路径、模式版本和摘要出现在有界诊断中。提交的 WAL 数据包含在每个独立快照中。快照卷需要 2 × total SQLite family bytes + 3 × largest family + 64 MiB 用于保留文件和工作空间。未知可用空间产生警告；在迁移之前，一定程度的短缺会被拒绝。每个单独的源卷还保留其数据库系列总数及其最大系列和 64 个 MiB 用于恢复，同时保留迁移的原始卷。硬链接数据库或日志文件在迁移之前会被拒绝，因为恢复一个路径名无法安全地恢复每个别名。

备份元数据重用快照发布者经过验证的 SHA-256 和字节计数，避免再次完整数据库读取。在替换任何实时数据库之前，恢复仍会根据该收据验证存储的字节，因此稍后的快照更改将被拒绝。此保存需要安装的更新程序包含修复程序；较旧的更新程序保留其原始备份路径。

本机管理程序的 update migrate --backup-root 捕获在网关停止的情况下运行。检查点数据库文件在可用时使用文件系统克隆（包括 APFS 和具有 reflink 功能的 Linux 文件系统），并在其他文件系统上具有独立的字节副本。该捕获检查 SQLite header/schema，记录现有恢复合同的一个 SHA-256 摘要，并验证源文件和日志状态是否保持不变。克隆创建避免了复制有效负载页面，但所需的摘要仍会读取每个快照一次。保留的 WAL 或回滚日志使用现有的一致的、经过充分验证的快照路径。

即使在仅共享状态模式升级期间，每个发现的代理数据库仍然被覆盖：医生可以编写代理簿记，而无需升级其模式。更新时间 Doctor 推迟对模式已经是最新的数据库的媒体内容维护；显式 openclaw doctor --fix 仍执行该维护。需要架构修复或记录损坏的数据库保留修复路径。这避免了服务停止时重复的备份完整性审核和不必要的可写打开；启动验证保留其自己的策略。

解决后，验证成功激活将删除当前更新的数据库快照以及旧包备份。回滚、失败或未验证的完成以及恢复拒绝保留它们。清理失败会产生保留路径的维护警告。较旧的快照目录保持不变，因为无法从现有收据中证明其所有权和成功结果； Doctor 报告较旧的 npm 快照目录及其大小和删除命令。确认没有更新正在进行，并在手动删除它们之前检查其更新报告和恢复状态。

如果在捕获期间确认网关已停止，并且在允许候选启动之前更新失败，则恢复还需要匹配数据库写入证据。 Doctor 在迁移之前检查捕获的文件代，并在释放维护所有权之前记录其最后几代。维护期间的任何指纹更改（包括新创建的数据库）都会拒绝自动恢复。网关维护所有权不排除独立的 SQLite 编写者，这些观察结果无法区分 Doctor 自己的写入和外部提交。更改的数据库需要手动恢复。回滚会再次检查这些事实，同时保留数据库文件排除。指纹涵盖数据库身份、提交的页面内容以及保留的 WAL 事务计数器和提交校验和；他们重复使用快照库存。在同一数据库中对已捕获的 WAL 页面进行检查点不会使回滚无效，同时写入证据仍然可用。新的提交、数据库的替换或捕获的 WAL 写入证据的丢失仍然拒绝恢复。允许精确的写入反转，使已提交的字节和保留的写入证据均保持不变：它不会留下稍后要回滚丢弃的数据。

当该证据匹配时，更新程序会在恢复包之前恢复数据库。它保存网关生命周期和数据库文件排除项，将迁移的文件移动到 <database>.migrated-<runId>（具有匹配的 WAL/SHM/journal 后缀），并将经过验证的快照发布到空闲路径。快照和移位的文件仍然可用于手动恢复；他们的位置出现在报告中。如果包或配置恢复被拒绝，网关将保持停止状态，并且两代数据库仍可用于手动恢复。尝试启动候选程序、不确定的子终止、不可用的文件排除或委派的 Windows 自动启动保管权会阻止静默恢复。这些案件保留现有的拒绝追偿及其下一步行动。未计入的更改报告 state-migrated-no-rollback，保留当前数据库，并命名保留的快照目录和 openclaw doctor 恢复步骤。在 Doctor 开始之前进行更改也会阻止恢复。比较无法识别作者：后来的更新历史写入也可能使证据无效。此检查不提供跨 Doctor 子流程的持续监管。如果Doctor无法提供写入证据，则回滚需要最后验证的数据库世代保持不变。网关可能仍在写入时拍摄的快照（包括 --no-restart）仍可用于手动恢复，并带有警告，直到验证成功激活为止。它们永远不会仅仅因为该网关后来退出而有资格进行自动恢复。

此保护属于已运行的更新程序。安装它不会改造 2026.9.1 或 2026.9.5 驱动程序；它可以保护修复后的驱动程序运行的后续软件包更新。它不会重播较旧的全状态检查点记录或替换独立备份。用于验证的私人快照是一次性排练副本。在重大更新之前，创建 独立验证的备份 。

未知或已更改 schema/configuration 不授权恢复。当无法建立兼容性时，更新程序拒绝回滚，保留状态和保留的包材料，并报告失败的操作。仅恢复旧包并不能证明服务可以安全启动。

此更新路径不支持需要检查点重播的现有挂起记录。 openclaw update 在普通可变更新工作之前报告它们；它不会重播、重写、退出或清除其保留状态。 update finalize 不会绕过该拒绝。保留记录和任何指定的恢复工件，以便通过兼容的实施或经过验证的备份进行恢复。稍后的调用不得将未解决的中断运行标记为成功。

兼容性检查包回滚

在验证激活或包恢复之前，之前的包树仍然可用。如果在确认工作包之前激活失败并且无法验证回滚，则最终化将保留备份并报告其位置。在重新启动之前保留该备份并修复安装，包括对于不继续迁移的较旧目标。自动回滚需要保留的包、其预更新验证、自激活Doctor pass以来未更改的配置内容以及兼容的预先存在的共享和受影响的每个代理SQLite user_version值，包括通过上述预启动恢复恢复的数据库。在激活或验证期间首次创建的数据库仅在该数据库类型的新安装支持的架构版本上是架构中立的；缺少预先存在的数据库或外部版本中的新数据库会阻止回滚。新创建的数据库也必须能够被之前的包读取；未知或不兼容的支持拒绝使用 rollback-state-unverified 进行回滚。更新程序恢复上一代并在完成 rolled-back 之前验证其运行，保留失败检查作为其原因。有关恢复和包管理器防护，请参阅 自动回滚 。新版本主配置文件中自己的 Doctor 迁移不会阻止回滚，包括全新安装的第一次更新。单独的 $include 文件必须保留其预激活配置内容。 Doctor 必须已使用捕获的更新前配置，并且当前文件必须与其报告的输出匹配。恢复会保留正常的配置写入器锁，并在写入之前重新检查捕获的哈希值。需要时，回滚会使用 Doctor 和所有者权限 （0600） 之前捕获的确切字节替换主配置，包括之前的写入者标记。操作员在激活块恢复后进行的编辑，包括Doctor读取配置之前或最后一次写入之后的编辑；下一个操作命名更改的配置文件。仅发生故障并不能授权重新启动新版本。

如果在激活 Doctor pass 后配置文件发生更改，或者在候选启动之前无法安全恢复迁移的数据库，则自动回滚将被拒绝，并显示 state-migrated-no-rollback。更新程序保留失败的结果和迁移的状态。如果回滚本身失败，它会保留包和服务恢复诊断信息。可选的故障后Triage仅在更新所有权和服务补偿结算后启动；它不会重写失败的更新或授予新的重新启动权限。这些临时验证快照不是全状态备份；请参阅 Rollback。如果无法验证模式状态，则拒绝回滚，并显示 rollback-state-unverified；未知状态永远不会被视为模式中立。

如果更新在激活之前失败，恢复会观察现有网关一次，而无需等待启动或重新启动它。本机服务和侦听器检查共享更新的现有观察限额；它们的运行时间不会消耗单独的短健康请求超时。明确的较短支票津贴和总期限仍然适用。当已安装的更新程序包含此更正时，此更正才会生效，而不是在已运行的旧更新程序中。

重启交接

服务管理器命令和帮助器确认共享激活或恢复限额。缓慢的检查或拆卸不会强制执行单独的五秒或三十秒命令截止。服务安装还通过安装和激活转发一位呼叫者预算；家长拥有取消权。

当代理在 systemd 用户服务或 macOS LaunchAgent 网关内运行 openclaw update 时，CLI 在停止网关之前将更新交给同一托管服务帮助程序。它打印帮助程序日志路径以及更新状态和网关运行状况的后续命令，然后退出；这确认了切换，而不是完成的更新。确认 CLI 会以代码 75 （EX_TEMPFAIL） 退出，因此脚本不会将已接受的后台工作误认为是已完成的更新。脱离的帮助者仍然是解决当局；使用打印的状态和运行状况命令来检索其最终结果。在候选人准入期间接受的移交在本地暂存清理后保留此待定结果；它不会创建更新失败报告。帮助程序在网关的服务边界之外启动暂存和验证，而旧网关继续提供服务。仅当协调器到达 activating 时，它才会停放网关，然后完成现有的提交或取消切换。保持 stdout 连接到代理：停止服务可以终止周围的 exec shell（SIGTERM 或 exit 143），包括更新后链接的命令。交接结果后，使用打印的后续命令得出最终结果。普通终端更新保持同步，并且 --no-restart 不授权停止代理的网关。

核心后步骤遵循已验证的替换包，包括更改全局包链接目标的 pnpm 更新。帮助器保留原始安装标识以供恢复；从不同安装运行的子进程仍然被拒绝。

来自稳定版 2026.9.2 和 2026.9.3 的更新保留了对其服务移交记录的支持，这些记录早于记录的 Linux 服务管理器 UID。新版本仍然重新验证服务所有权、配置文件、单元和受保护的启动器数据。当切换记录管理器UID时，不同的UID会阻止服务突变。

网关核心自动更新程序需要托管服务重新启动路径。它在激活之前将 CLI 更新交给独立的助手。前台网关保留更新提示，但将安装和激活留给操作员：停止它，运行 openclaw update，然后再次启动它。

Control-plane update.run 使用相同的独立 CLI 更新所有者进行包管理器和 Git 安装，包括经过验证的前台网关。网关在验证期间保持可用。在替换其已安装的代码之前，更新程序会要求该网关耗尽工作并关闭其服务、数据库和侦听器。仅当更新程序稳定后，前台网关才会启动新进程；更换后它不会重新打开旧的模块图。托管服务通过其现有服务管理器重新启动。

在暂存和验证运行时，聊天更新会保留请求者的原始人员访问权限。撤销该授权将停止挂起的更新并让网关继续服务；发放新的拨款不会恢复原来的请求。在停车之前，网关必须确认原来的授权和当前的管理权限仍然允许更新。缺失、失败或超时确认并不授权停止网关。

授权停放后，本机更新程序拥有同一更新的完成或恢复，包括医生和重新启动验证。在关机期间关闭原始网关的访问策略服务不会取消此已接受的操作。原始配置文件链接、角色、配置权限、安装所有权和配置写入检查仍然适用。新的更新或分类请求需要新的授权。

启用 OPENCLAW_NO_RESPAWN 后，前台网关在启动更新程序之前会拒绝 update.run。停止网关，运行 openclaw update，然后再次启动它，或者在没有 OPENCLAW_NO_RESPAWN 的情况下重新启动它以允许控制平面更新。

每个请求的更新都会在接受其目标之前检查当前的本地安装和 Git 上游。在固定的 Git 更新使签出分离后，经过验证的更新收据会保留相同签出和修订的上游。启动状态发现不会冻结以后的更新请求。

当初始准备情况观察结束时，前台替换仍然可以开始。 OpenClaw 使该进程保持运行并报告准备情况为未经验证。使用 openclaw gateway status --deep 检查其进度。成功的更新将保持挂起状态，直到替换验证启动为止。

如果就绪状态拒绝前台替换，OpenClaw 会请求正常关闭，并将关闭报告为等待替换 PID。旧的网关进程等待该替换进程关闭。如果关闭未完成，请在手动停止之前检查替代设备的启动日志和活动更新。

在帮助程序启动、包暂存或激活期间停止前台网关，等待拥有的更新工作完成，然后让网关停止。新的更新和不相关的重新启动无法绕过该等待。如果清理所有权不确定，网关仍然会耗尽；检查更新程序后，再次发送“停止”以重新检查相同的工作。已经开始的替换也被停止。待启动验证将在下次网关启动时运行。在验证挂起期间，之前的包备份仍然可用。

当启用 update.checkOnStart 时，存储的扩展稳定选择会收到只读启动和 24 小时更新提示。这些检查从不应用更新、启动切换、重新启动网关、使用稳定的 delay/jitter 或使用 beta 轮询节奏。仍支持显式前台更新、使用存储的 update.channel: "extended-stable" 的裸前台更新、按需状态及其托管网关切换。

更新验证和服务定义

在重新启动可写托管服务之前，更新完成会使用共享服务审核和本机安装程序来修复已识别的过时策略。它备份定义，保留支持的自定义设置，并在更新警告中记录更改的密钥和备份路径。未知操作员编辑保持不变。更新时医生报告偏差并将此重写留待最终确定。

候选者拥有的回滚会在运行先前安装程序的恢复之前恢复已验证的定义备份。当较旧的已发布更新程序拥有回滚功能时，该版本的安装程序会使用其支持的设置重新生成定义；保留的备份记录原始字节。

启用本地托管服务并重新启动后，更新验证会在停止之前进行，如上所述。仅当重新启动的服务通过验证后，更新程序才会报告 Gateway: restarted and verified.。插件拥有的准备情况检查针对隔离状态快照运行，并且不运行交互式设置、下载模型或更改配置。准备就绪所有者是在其健康 API 加载之前选择的，因此不相关的可选医生检查不能中断大门。选定的检查仍然是强制性的，包括缺少所需工件的情况。

代码更新不需要重写本机服务定义的权限。在 Linux 上，密封或未经验证的定义写入权限会跳过元数据刷新，即使元数据已过时也是如此。更新安装所拥有的可检查服务仍使用其本机管理器进行重新启动和 health/version 验证。激活会使用 gateway restart --preserve-definition 运行更新的 CLI，因此应用其自己的版本防护，并且自动修复保持禁用状态。如果目标 CLI 不支持该选项，它将在修复之前拒绝激活。代码更新保持安装状态，但命令以非零值退出并出现激活错误（在 JSON 模式下的 stderr 上）。因更新而停止的服务可能会保持停止状态。运行 openclaw gateway status --deep 并要求部署所有者通过其本机管理器重新启动它或修复过时的元数据；除非打算修复定义，否则不要在没有保留选项的情况下重试。

Shell 安装程序

Shell 安装程序不会建立相同的服务所有权证明。如果他们的服务刷新被拒绝，他们会报告代码安装成功，保持服务不变，并打印指导以检查所有权并手动重新启动。

Linux 无服务管理器

在没有服务管理器的 Linux 上，当本机检查证明服务不存在并且所选网关没有活动锁或侦听器时，更新将继续。该命令报告没有要重新启动的网关。

如果服务检查不可用或安装所有权未解决，更新将继续并发出警告，并保持记录的服务不变。未经验证的记录无法选择更新的包、Node 运行时、配置或状态目录。更新后重新启动手动启动的网关，并使用 openclaw gateway status --deep 检查记录。已验证的服务仍然选择自己的安装和状态目录；所有权冲突、待恢复和活动状态写入者保留其现有的准入检查。另一个安装所拥有的服务保持不变。

已发布的 2026.8.2 CLI 还拒绝无服务 Linux 安装的更新。确认没有网关正在运行后，使用 openclaw update --no-restart 进行升级；新的CLI无法修复旧的CLI的更新前检查。

Node 用于包管理器更新的运行时

包管理器更新通常会继续使用记录在受管服务中的 Node 二进制文件。如果该 Node 无法运行目标版本，但当前 CLI 使用的 Node 可以，并且已确认该服务确实属于正在更新的包，那么启用重启的更新会在最终完成时使用当前 Node，并将服务元数据重写为该运行时。--no-restart 无法修复服务元数据，因此同样的运行时不匹配会在包变更之前停止。

macOS LaunchAgent 验证

On macOS，更新后检查还验证LaunchAgent is loaded/running对于活动配置文件并且配置的环回端口运行状况良好。如果 plist 已安装但launchd并没有对其进行监督，OpenClaw重新引导LaunchAgent自动并重新运行health/version/ 通道准备情况检查（新的引导程序加载RunAtLoad直接工作，所以恢复不会立即kickstart -k新生成的网关）。保留定义时，本机restart/bootstrap无需文件修复即可运行；失败的本机激活或运行状况检查不会触发稍后的 plist 重写。如果网关仍未恢复正常，该命令将以非零值退出并打印重新启动日志路径以及重新启动、重新安装和程序包回滚说明。

当重启被跳过或失败时

如果重新启动无法运行，该命令将打印 Gateway: restart skipped (...) 或 Gateway: restart failed: ... 以及检查服务并手动重新启动的指导。对于 --no-restart，包替换或 git 重建仍然运行，但更新程序不会停止或重新启动网关。当正在运行的网关检测到其安装被替换时，它仍然可以退出；之后通过其服务或前台进程所有者重新启动它。

当更新程序拥有的 Doctor 在前台网关完成关闭之前达到维护状态时，它会等待独占状态所有权，直到安装检查间隔加上现有的重新启动耗尽和服务停止限额。 Doctor保留更新者的实时权限，并且在修复状态之前仍然获取其正常维护锁。如果所有者在 Doctor 等待期间退出或发生变化，则同样适用有界等待；只有获得物理维护锁才可以进行维修。失去更新权限或未解决的争用会停止维护并提供恢复指导。普通 Doctor 命令和未经授予 Doctor 权限的较旧更新驱动程序保留立即拒绝的权利。

主动网关暂停将安装更改保持在其主机操作的控制之下。当暂停正在准备、排空或准备时，安装观察程序不会独立重新启动网关。恢复或租用到期后，其下一次检查会再次读取当前安装；回滚期间恢复的指针不会留下过时的替换判决。显式停止和重新启动请求保留其现有行为。

已发布的 2026.9.5 网关没有安装替换观察程序。安装较新的候选者无法将该行为添加到已经运行的进程中。对于第一个前台更新，通过其前台进程所有者停止网关并等待其退出，运行 openclaw update，然后再次启动网关。保持相同的安装、配置文件和 state/config 覆盖。 --no-restart 未授权 Doctor 停止该进程或跳过所需的状态维护。

如果软件包已被替换并且 Doctor 在实时网关锁定上失败，请等待更新程序退出，通过其所有者停止前台网关，然后从更新的安装运行 openclaw update repair --yes --no-restart --json。再次启动网关之前请验证修复结果。保留现有状态和恢复备份；仅替换文件并不能完成维护。

Control-平面响应形状

当 update.run 在包管理器安装或受监督的 git checkout 上通过网关控制平面运行时，处理程序将与在分离帮助程序中继续的 CLI 更新分开报告切换启动：

• ok: true、result.status: "skipped"、result.reason: "managed-service-handoff-started" 和 handoff.status: "started"：网关创建托管服务切换，以便分离的帮助程序可以在实时服务进程之外运行 openclaw update --yes --json。旧网关在验证期间保持可用；此响应并不意味着服务已停止或更新已完成。
• ok: false, result.reason: "managed-service-handoff-unavailable"，以及 handoff.status: "unavailable"：OpenClaw 无法找到用于安全交接的监管服务边界和持久服务身份（例如，systemd 交接需要 OPENCLAW_SYSTEMD_UNIT 单元身份，而不仅仅是环境中的 systemd 进程标记）。响应会包含 handoff.command，即需要从 Gateway 外部运行的 shell 命令。
• ok: false, result.reason: "managed-service-handoff-failed"：Gateway 尝试创建交接，但无法启动分离的辅助进程。

sentinel 有效负载在网关退出之前写入，并且在托管服务重新启动运行状况检查完成后，CLI 切换会更新相同的重新启动标记。切换过程中，哨兵可以携带stats.reason: "restart-health-pending"，但没有成功延续；仅在 CLI 验证服务运行状况并使用最终的 ok 结果重写哨兵后，重新启动的网关才会对其进行轮询并触发延续。当该哨兵挂起或失败时，openclaw status 和 openclaw status --all 显示 Update restart 行。 update.status保留最新的哨兵，同时返回持久运行记录。哨兵携带stats.runId；通知传递消耗哨兵后，运行记录仍然可用。

Git 检出流程

渠道选择

• stable：选择最新的非测试版标签。
• beta: 优先选择最新的 -beta 标签；如果 beta 缺失或更旧，则回退到最新的稳定标签。
• dev：获取 main 并重新设定分阶段结帐的基础。
• extended-stable: 不支持 Git 检出；不会发生任何 checkout 变更。

更新步骤

插件同步详情

在稳定更新中，将从选定的核心版本队列中修复已配置的没有安装记录的 OpenClaw- 官方插件。这也适用于早期升级丢失以前捆绑的插件后的 doctor --fix。核心后协调会在重新启动之前尝试安装；当核心更新继续时，不可用的目标仍然是命名警告。现有记录保留其注册表和来源选择。已验证的官方软件包使用现有的 能力同意豁免 。

成功更新后，npm 的合格托管发布引脚和 @openclaw/* 软件包的可信官方 ClawHub 安装将恢复目录的默认选择器。记录的选择器必须是精确的 OpenClaw 版本，不得比已安装的核心更新，并且同一包必须具有经过验证的默认目录目标。这包括之前记录的自动和手动引脚。提供给当前插件更新命令的显式选择器优先。资格之外的 Pin 图、范围、显式标签和其他来源将保留其现有政策。

Beta 通道上的托管 npm 插件按语义版本顺序从 beta 和 latest dist 标签中选择最新版本，使用与核心更新程序相同的策略。这包括具有 default/latest 目录目标和托管 @beta 选择器的官方插件。 OpenClaw 安装精确检查的版本，同时保留所选标签或恢复的目录默认值以供将来更新。

Npm 插件更新重复使用已为同一安装尝试选择的注册表元数据，从而避免在下载前进行第二次查找。兼容性、完整性、安装策略和功能同意检查仍然适用于所选软件包。回退到另一个目标会单独解决该目标。

Beta 通道上的 ClawHub 插件尝试使用自己的 @beta 标签。如果该版本不可用，OpenClaw 会回退到 default/latest 规范，并报告命名所请求和使用的目标的警告。完整性、兼容性、信任、安装策略和功能同意失败不会触发回退。可用性回退警告不会导致核心更新失败。上述托管释放引脚恢复之外的引脚、范围和 beta 之外的显式标签保留其选择器。 Doctor 可以刷新与当前 OpenClaw 版本队列绑定的过时的官方运行时插件。该修复保留在记录的注册表中并验证替换工件。现有的运行时插件保留在适当的位置；无操作启动修复不会重新安装软件包或使迁移检查点失效。

当后核融合在自动释放引脚恢复之外保留官方引脚并且 npm 检查发现更新版本时，更新会打印引脚建议并在 JSON 中报告 postUpdate.plugins.status: "warning"。该警告包括观察到的已安装和可用版本以及更换引脚的明确命令。如果有意的话请保留该别针。此通报不会造成不兼容性、更改引脚或使其他成功的核心更新失败。

不可用的 npm 目标或无法访问的注册表不会导致其他成功的核心更新失败。当安装了兼容的、可运行的插件时，插件同步会保留该安装的版本及其记录的选择器。摘要、警告日志和运行历史记录为插件命名、请求的目标、解决失败和 openclaw plugins update <id> 下一步操作。 JSON 保留顶级 status: "ok"，并在 postUpdate.plugins.warnings 下提供 plugin-target-unavailable 咨询。

在突变之前，OpenClaw 检查已安装的兼容性元数据并跳过兼容插件的注册表查询。如果插件声明的 openclaw.compat.pluginApi 范围或 openclaw.install.minHostVersion 排除了目标核心并且无法解析兼容的替换，它会记录指定通知并继续核心更新。在安装兼容版本之前，该插件可能会保持不可用状态。配置、所有权、模式和核心准备情况检查仍然必须通过。

在新版本的代码运行之前，较旧的更新程序可能仍会拒绝 plugin-target-unavailable。使用安装的 手动更新方法，然后从更新的安装运行 openclaw update repair。

扩展稳定核心更新成功后，后核心插件完整性和收敛目标是在确切安装的核心版本上符合资格的官方 npm 和受信任的官方 ClawHub 插件。对于 default/latest 意图，OpenClaw 不会查询插件 @extended-stable 或回退到 npm latest；它从已安装的核心中派生出软件包版本。符合条件的托管释放引脚根据上述恢复规则恢复目录默认值。超出该资格的引脚、显式非 latest 标签、第三方软件包、自定义 ClawHub 注册表和其他来源保留其现有意图。为当前插件操作提供的显式选择器优先。

包管理器安装

对于包管理器安装，openclaw update 在调用包管理器之前解析目标包版本。 npm 全局安装使用分阶段安装：OpenClaw 将新软件包安装到临时 npm 前缀中，让分阶段软件包在 preinstall 期间验证主机 Node 版本，并验证其中打包的 dist 清单。打包的完成防护将保留在该清单之外，直到 preinstall 成功，因此跳过生命周期脚本的包管理器也会在激活之前停止。在 npm 12 及更高版本上，更新程序仅批准分阶段的 OpenClaw 包的生命周期；传递依赖脚本仍然被阻止。然后 OpenClaw 将干净的包树交换为真正的全局前缀。如果验证失败，则更新后医生、插件同步和重新启动工作不会从可疑树运行。

暂存在目标全局 node_modules 内使用唯一的 .openclaw.update-stage-* 目录，与一次性 npm 重命名剩余内容分开。每次尝试仅尝试删除自己的暂存前缀；剩余的清理不会回收这些阶段。如果中断的更新留下了一个目录，请在删除该目录之前确认没有更新程序仍在使用它。这种分离并不能使同时包交换变得安全。

匹配的安装版本会跳过核心替换，但仍然会聚插件。核心更新还刷新了核心命令完成；完整的插件命令完成重建仍然显式 openclaw completion --write-state 运行。

pnpm 和 Bun 在 macOS/Linux 上部署自己的全局项目和启动器，保留管理器的清单、锁和同级包以供回滚。对该全局项目的并发更改将停止激活。 Windows Bun 更新在服务停止之前被拒绝，因为分阶段更新程序无法重新定位其二进制启动器；使用拥有的 Bun 管理器进行 手动更新 。在激活之前，使用 --channel dev 将 pnpm 或 Bun- 拥有的软件包安装切换到 Git 也会被拒绝。分阶段源代码检查暴露当前需要 npm- 拥有的包符号链接；包到包的更新仍然通过所属管理器支持。

当 npm 包链接指向构建的 Git 签出时，回滚会在恢复链接和启动器之前验证相同的签出和构建。本地源编辑被保留。在更新期间替换签出或重建它可以防止自动回滚；单独恢复链接并不能证明运行时安全。

本地打包覆盖

在替换旧包之前，包更新会在恢复包中保留本地 dist 编辑。捕获发生在服务耗尽和旧树移动之后，因此包含新版本安装时所做的编辑。该报告在选定状态目录的 update-recovery/ 目录下命名该包。保留它直到您检查了更新的安装；移除是手动的。

默认情况下，更新会安装新包而不重播本地代码。要重播您在更新期间信任的编辑：

openclaw update --reapply-local-overrides

公布内容清单的包记录了文件哈希值和可执行状态。重放需要新包对应的基线和实际字节匹配；上游更改、不安全路径和硬链接目标会阻止重播。冲突会将整个覆盖集保留在恢复包中。未引用的内容散列添加也需要手动恢复。在替换实时包之前，重播会针对私有暂存包运行。发布和恢复拒绝覆盖同时创建的目标。重放并不能确定本地代码仍然与新版本兼容。

没有内容清单的旧包无法区分本地编辑和供应商文件。他们的常规 dist 文件将被保留以供手动检查，即使设置了标志，也不会自动重播。为该副本保留足够的可用空间；恢复包不会自动修剪。依赖树和清单元数据不是本地覆盖有效负载。符号链接和其他不受支持的条目可以拒绝更新，包括否则排除的 dist 子树中的条目；在重试之前修复这些条目。正常的包管理器权限更改（例如应用安装程序的 umask）不会被视为本地编辑。

保留的覆盖与自动包回滚是分开的。失败的更新仍遵循现有所有权、配置、架构和保留包检查。如果后期编辑使回滚验证无效，请保留指定包备份和覆盖包；该报告不授权重新启动未经验证的安装。

此行为属于已运行的更新程序。在第一次从不包含本地编辑的旧更新程序升级之前备份本地编辑。 Git 签出继续使用现有的 clean-worktree 和 Git 更新规则。