自动更新

无头节点和受管 Gateway 服务的自动更新，包括新版本何时可以重启每个进程。属于更新指南的一部分。

无头节点更新¶

长时间运行的打包无头节点默认会自动更新。这包括前台运行的 openclaw node run 和已安装的节点服务。在首次经过身份验证的连接之后，节点会检查是否有更新的版本，并每小时重复检查一次。它会准备一份单独的程序文件和依赖副本，并且仅在节点空闲时激活它。全局 CLI 包以及使用该包的任何 Gateway 不会被节点更新替换。

空闲意味着节点不再拥有活动命令、后台执行、终端会话、工作进程会话、插件工作、待处理输出或清理任务。节点在激活前会停止接受新命令，因此工作不会在空闲检查与重启之间启动。忙碌的工作可能会无限期推迟更新。自动激活之间至少间隔 12 小时；此限制绝不会强制忙碌的节点重启。

插件必须明确报告其保留的工作已空闲。没有空闲工作回调的旧插件会推迟自动激活，即使在其最后一个命令返回后也是如此。将该插件更新到兼容版本，或完成其工作并使用 openclaw update，然后重启节点。

替换进程会以相同的身份、配对、设置和启动选项重新连接。单独的运行时更改的是程序文件，而不是节点的状态目录。激活要求候选版本成功重新连接；如果启动失败，启动器会回退到之前的运行时。

如果节点与在节点自动更新功能引入之前安装的 Gateway 共享其状态目录，请先更新该 Gateway 一次。旧版 Gateway 会拒绝与其自身版本不同的本地节点。更新后的 Gateway 会在协议兼容时接受较新的本地节点，因此后续的节点更新可以让 Gateway 继续以现有版本运行。

自动节点更新要求状态和 agent schema 版本匹配，并且与候选版本所需的数据库形态完全匹配。仅匹配数字版本是不够的。需要迁移或启动修复的版本会被推迟，并提示使用常规更新工作流。受管替换会使用现有状态，而不会运行共享的 Doctor 或启动修复。常规更新工作流负责这些修复、迁移和回滚，包括与共享状态目录的 Gateway 进行协调。

原生应用节点和私有 worker 进程将继续使用其现有的更新所有者。源码检出和 dev 安装也保持由所有者管理。节点针对 stable 和 beta 版本遵循 update.channel；extended-stable 固定版本绝不会自动应用更新。

要选择退出，请在节点机器上进行如下设置：

{
  nodeHost: {
    autoUpdate: {
      enabled: false,
    },
  },
}

共享的选择退出设置 update.checkOnStart: false 和 OPENCLAW_NO_AUTO_UPDATE=1 同样会禁用节点更新检查和自动激活。update.auto.enabled 控制 Gateway 更新；它不控制此节点特定的默认行为。

要检查已连接节点的运行时版本，请从连接到其 Gateway 的 CLI 运行 openclaw nodes status --json，并检查 nodes[].version。openclaw --version 报告的是该 CLI 的已安装版本，该版本在节点更新后可能会有所不同。

在前台节点的 stderr 或其服务日志中查找更新准备、繁忙延迟、激活和回退消息。如果更新因 schema 迁移或修复而被推迟，请在节点机器上运行 openclaw update。然后使用 openclaw node restart 重启其服务，或重新启动前台 openclaw node run 命令。

如果启动器报告过期的 node-runtime/activation.lock，请先确认没有节点更新正在运行，然后再删除消息中的确切锁路径。然后重启节点。保留运行时选择器及其恢复备份；启动器会使用它们在中断的激活后恢复之前选定的运行时。

自动更新器¶

Gateway 自动更新默认关闭。请在 ~/.openclaw/openclaw.json 中启用它们：

{
  update: {
    channel: "stable",
    auto: {
      enabled: true,
    },
  },
}

您还可以在 Control UI 的 设置 → 更新（/settings/updates）中选择更新渠道并启用自动更新。检查更新 控制现有的 update.checkOnStart 设置。当该设置为关闭时，自动更新会被禁用，但会保留您已保存的偏好；重新开启检查会恢复发现以及任何已启用的自动更新策略。这不会更改您单独的 feature-statistics 偏好。当连接的 Gateway 支持时，该页面上记录的错误包括类型化的 检查状态 和 重试更新 操作。有关原因代码、引导式恢复、CLI 回退和需要收集的诊断信息，请参阅更新故障排查。

对于 dev git 安装，打开此页面会刷新跟踪的上游，并显示检出是否是最新、领先、分叉、不可用，或落后于特定数量的提交。它还会显示构建、已验证安装和最后提交的精确时间与相对时间。现有检出的安装时间显示为未知，直到下一次经过验证的成功更新。

自动安装需要一个受管 Gateway 服务，该服务可以安全地交接更新并重启。直接在终端中运行的 Gateway 仍然可以显示更新提示，但不会自动替换正在运行的安装。停止该 Gateway，运行 openclaw update，然后在之后重新启动它，或者安装受管服务以实现无人值守更新。

更新活动¶

当自动更新到期时，活动会等待当前活动工作完成，然后开始一分钟倒计时。倒计时一旦开始，新的工作不会重置它，也不会让活动回到等待状态。15 分钟的硬性截止时间会启动更新，即使仍有工作未完成，并使用正常的重启排空和会话恢复路径。打开的终端会话不会推迟倒计时或应用更新。Gateway 重启会结束这些进程本地 PTY，之后终端会话不会恢复。

管理员可以使用一次 Hold 1 h 来推迟活动并顺延其硬性截止时间，或者从侧边栏更新卡片或 Settings → Updates 中选择 Update now。对于 dev git 安装，活动会安装它所宣布的确切提交。显示的列表预览来自该固定目标的最多五个提交；如果在倒计时期间上游 main 分支前进，列表不会移动。

每次失败的应用都会结束该活动，这样 UI 不会一直停留在 Updating…。托管服务交接开始后发生的失败也会记录在重启哨兵中，并在 Gateway 返回后显现。

update.checkOnStart: false 会禁用所有自动更新检查、功能统计和更新通知，即使 update.auto.enabled 为 true 也是如此。OPENCLAW_NO_AUTO_UPDATE=1 同样会禁用自动检查和自动应用。外部监督者模式会禁用自动应用；除非同时禁用 update.checkOnStart，否则启动时更新提示仍可运行。有关每日检查所发送的信息以及可选的匿名功能统计，请参阅 使用遥测和更新检查。

禁用检查还会取消未完成的发现过程及其活动；来自先前设置的延迟响应之后无法启动更新。

Gateway 关闭或被替换会取消未完成的更新发现，并等待其 Git 进程和临时预检清理结束。已移交给托管服务更新程序的更新仍由该独立更新程序控制。

Gateway 还会在启动时记录一条更新提示（可用 update.checkOnStart: false 禁用）。已存储的 extended-stable 选择会使用这条只读提示路径和现有的 24 小时提示间隔，但绝不会触发自动安装、交接、重启、stable 延迟/抖动或 beta 轮询。

通过实时 Gateway 控制平面（update.run）请求的包管理器更新不会替换运行中 Gateway 进程内部的包树。在托管服务安装中，Gateway 会启动一个分离的交接，运行正常的 openclaw update --yes --json CLI 路径。旧 Gateway 在候选验证期间继续提供服务；辅助程序仅在激活时将其停置。CLI 会替换包、应用必需的迁移、刷新服务元数据、启动并验证 Gateway，并在可能的情况下恢复已安装但未加载的 macOS LaunchAgent。如果 Gateway 无法安全地进行该交接，update.run 会报告一条安全的 shell 命令，而不是在进程内运行包管理器。

当 update.run 具有可路由的聊天会话时，Gateway 会在开始交接或进程内更新之前发送更新确认。它最多等待 10 秒以确保送达；聊天发送失败不会阻塞更新。RPC 响应包含 ackDelivered，以便客户端能够区分已送达的确认与不可用或失败的路由。重启、验证和完成通知遵循持久运行状态，如从聊天中所述。

Control UI 会在更新请求中包含其活动会话。任何具有现有内部/webchat 来源会话的 run 都会在该会话的记录中收到其报告，无论调用方是否提供了投递上下文。具有外部投递路由的会话会在该渠道中收到持久通知。没有来源会话的更新会在可用时通过系统主会话的外部路由发送通知。否则，恢复会保持系统会话唤醒，而不发送出站聊天通知。无会话恢复绝不会将提供的延续作为另一个聊天回合来恢复。

当 Control UI 侧边栏更新卡片会直接启动此 update.run 流程时，它会显示 Update Gateway。这包括浏览器托管的 Control UI、远程 Gateway 以及手动管理的本地 Gateway。

从 Control UI 启动的手动更新总是先询问。第一次点击侧边栏更新卡片或 Settings → Updates → Update now 会打开一个确认对话框，其中指明目标、已知时的已安装版本和可用版本，以及重启影响；在您选择 Update and restart 之前不会发送任何内容。取消、按 Escape 或关闭对话框都会让 Gateway 保持原样。自动活动、CLI 和 update.run API 客户端不受影响。

确认后，对话框会显示实时阶段列表、步骤详情和验证结果。重启期间它会保持打开，并在重新连接后从 Gateway 的运行记录中恢复。成功和失败都会在对话框以及 设置 → 更新 中留下最终报告。参见 控制 UI 更新。

在已签名的 macOS 应用中，本地应用管理的 Gateway 会将该卡片更改为 更新 Mac 应用 + Gateway。Sparkle 会先更新应用；重新启动后，应用会运行 openclaw update --tag <app-version> --json，重启其 Gateway，并在设置式进度窗口中验证健康状态。仅当该受管 Gateway 需要更新、修复或安装时，窗口才会出现；仅应用更新会直接重新启动到应用。失败详情保持可见，并提供“重试”、更新指南 和 Discord 操作。应用绝不会对远程或外部管理的 Gateway 使用此协调路径，绝不会降级较新的 Gateway，也绝不会覆盖 extended-stable 通道固定。

当更新成功时，应用会为最近一次具有真实用户/频道交互的顶层直接会话排队一次性欢迎事件。Cron 运行、心跳以及仅后台的会话更新不会改变该选择。在远程模式下，应用仅更新其本地 Mac 节点运行时，并且仅当所连接的远程 Gateway 至少与应用一样新时才发送该事件。