---
summary: "自动更新程序、每个频道的自动行为以及更新活动如何应用和报告更新"
read_when:
  - "您希望对托管网关服务进行无人值守更新"
  - "您想要控制无头节点主机的自动更新"
  - "您需要知道自动更新何时适用以及如何推迟"
  - "您正在关闭更新检查或自动更新"
title: "自动更新"
---

无头节点和托管网关服务的自动更新，包括新版本何时可以重新启动每个进程。 [Updating](/install/updating) 指南的一部分。

## <a id="headless-node-updates"></a> 无头节点更新

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

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

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

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

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

自动节点更新需要匹配的状态和代理模式版本以及与候选人所需的数据库形状的精确匹配。仅匹配数字版本是不够的。需要迁移或启动修复的版本被推迟，并附有使用正常 [ 更新工作流程 ](/install/updating) 的说明。托管替换会消耗现有状态，而不运行共享 Doctor 或启动修复。正常的更新工作流程负责这些修复、迁移和回滚，包括与共享状态目录的网关进行协调。

本机应用程序节点和私有工作进程继续使用其现有的更新所有者。源签出和 `dev` 安装也仍然由所有者管理。节点遵循 `update.channel` 的 `stable` 和 `beta` 版本； `extended-stable` 引脚永远不会自动应用更新。

要选择退出，请在节点计算机上进行设置：

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

共享选择退出 `update.checkOnStart: false` 和 `OPENCLAW_NO_AUTO_UPDATE=1` 还会禁用节点更新检查和自动激活。 `update.auto.enabled`控制网关更新；它不控制这个特定于节点的默认值。

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

查看前台节点的 stderr 或其服务日志以获取更新准备、繁忙延迟、激活和回退消息。如果由于架构迁移或修复而推迟更新，请在节点计算机上运行 `openclaw update`。然后使用 `openclaw node restart` 重新启动其服务，或重新启动前台 `openclaw node run` 命令。

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

## <a id="auto-updater"></a> 自动更新器

默认情况下，网关自动更新处于关闭状态。在 `~/.openclaw/openclaw.json` 中启用它们：

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

您还可以选择更新渠道并启用自动更新**设置 → 更新** （`/settings/updates`）在Control UI. **检查更新**控制现有的`update.checkOnStart`环境。当它关闭时，**自动更新**已禁用，但保留您保存的首选项；重新检查恢复发现和任何启用的自动更新策略。这不会改变您单独的功能统计偏好。该页面上记录的失败包括键入**检查状态**和**重试更新**当连接的网关支持时执行的操作。看[更新疑难解答](/install/update-troubleshooting)对于原因代码、引导恢复、CLI后备方案和要收集的诊断信息。对于一个`dev`git install，打开此页面会刷新跟踪的上游，并显示签出是否是当前的、提前的、分歧的、不可用的或落后的特定数量的提交。它还显示准确和相对的构建、验证安装和上次提交时间。现有的结帐显示未知的安装时间，直到下一次验证成功更新为止。

自动安装需要托管网关服务，该服务可以传递更新并安全重新启动。直接在终端中运行的网关仍然可以显示更新提示，但它不会自动替换其正在运行的安装。停止该网关，运行 `openclaw update`，然后再次启动它，或者 [ 安装托管服务 ](/cli/gateway#manage-the-gateway-service) 进行无人值守更新。

| 渠道           | 行为                                                                                                                                                            |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `stable`          | 在通过可重复的偏移量进行内置延迟以分散部署后，宣布更新活动。                                                                |
| `extended-stable` | 在启用 `checkOnStart` 时，于启动时以及每 24 小时检查一次只读更新提示。永不自动应用更新。                                       |
| `beta`            | 按内置间隔检查，并在有更新版本可用时立即宣布更新活动。                                                             |
| `dev`             | 启用 `auto.enabled` 后，git 安装每小时检查一次。当存在上游提交时，Gateway 会宣布一个固定到所宣布确切提交的更新活动。 |

### <a id="update-campaigns"></a> 更新活动

当自动更新到期时，营销活动会等待活动工作完成，然后开始一分钟倒计时。一旦倒计时开始，新的工作就不会重置倒计时，也不会让活动返回等待状态。即使工作仍然存在，也会使用正常的重新启动耗尽和会话恢复路径，在 15 分钟的硬性截止期限内开始更新。打开终端会话不会推迟倒计时或应用。网关重新启动会结束这些进程本地 PTY，并且此后终端会话不会恢复。

管理员可以使用一次 **暂停 1 小时** 来推迟活动并顺延其硬性期限，或者从侧边栏更新卡片或 **设置 → 更新** 中选择 **立即更新**。对于 `dev` git 安装，活动会安装其所宣布的确切提交。显示的列表会从该固定目标中预览最多五个提交；即使上游 `main` 在倒计时期间前进，该列表也不会移动。

每次失败的应用都会结束活动，因此 UI 不会保留在 **Updating…** 上。托管服务切换开始后的故障也会记录在重新启动哨兵中，并在网关返回后显示出来。

`update.checkOnStart: false` 禁用所有自动更新检查、功能统计和更新通知，即使 `update.auto.enabled` 为 `true` 时也是如此。 `OPENCLAW_NO_AUTO_UPDATE=1` 还禁用自动检查并应用。外部主管模式禁用自动应用；除非 `update.checkOnStart` 也被禁用，否则启动更新提示仍然可以运行。有关每日检查和可选匿名功能统计发送的信息，请参阅 [ 使用遥测和更新检查](/gateway/telemetry)。

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

网关关闭或更换会取消未完成的更新发现，并等待其 Git 进程和临时预检清理解决。已移交给托管服务更新程序的更新仍处于该单独更新程序的控制之下。

网关还在启动时记录更新提示（使用 `update.checkOnStart: false` 禁用）。存储的扩展稳定选择使用此只读提示路径和现有的 24 小时提示间隔，但从不调用自动安装、切换、重新启动、稳定 delay/jitter 或 beta 轮询。

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

当 `update.run` 具有可路由聊天会话时，网关会在开始切换或进程内更新之前发送更新确认。最多等待 10 秒发送；聊天发送失败不会阻止更新。 RPC 响应包括 `ackDelivered`，因此客户端可以区分已传递的确认和不可用或失败的路由。重新启动、验证和完成通知遵循持久运行状态，如 [From chat](/install/updating#from-chat) 中所述。

Control UI 在更新请求中包含其活动会话。任何使用现有 internal/webchat 源会话的运行都会在该会话的记录中接收其报告，无论调用者是否提供了传递上下文。具有外部传递路由的会话会在该通道中收到持久通知。没有原始会话的更新会通过系统主会话的外部路由（如果可用）发送通知。否则，恢复将保持系统会话唤醒，而不会发出出站聊天通知。无会话恢复永远不会在轮到另一个聊天时恢复提供的延续。

Control UI 侧边栏更新卡片会在将直接启动此 `update.run` 流程时显示 **更新 Gateway**。这适用于浏览器托管的 Control UI、远程 Gateway 以及手动管理的本地 Gateway。

从 Control UI 启动的手动更新始终会先询问。首次点击侧边栏更新卡片或 **设置 → 更新 → 立即更新** 时，会打开确认对话框，其中会说明目标、已安装和可用版本（若已知）以及重启影响；只有在你选择 **更新并重启** 后才会发送请求。取消、按 Escape 键以及关闭对话框都会使 Gateway 保持不变。自动活动、CLI 和 `update.run` API 客户端不受影响。

确认后，对话框将显示实时阶段列表、步骤详细信息和验证结果。它在重新启动期间保持打开状态，并在重新连接后从网关的运行记录中恢复。成功和失败都会在对话框和 **Settings → Updates** 中留下最终报告。请参阅 [Control UI 更新 ](/web/control-ui/settings#updates)。

在签名的 macOS 应用中，本地应用自有的 Gateway 会将该卡片改为 **更新 Mac 应用 + Gateway**。Sparkle 会先更新应用；重新启动后，应用运行 `openclaw update --tag <app-version> --json`，重启其 Gateway，并在类似设置流程的进度窗口中验证健康状态。只有当受管 Gateway 需要更新、修复或安装时，才会显示该窗口；仅应用更新会直接重新启动进入应用。失败详情会保持可见，并提供重试、[更新指南](/install/updating) 和 [Discord](https://discord.gg/clawd) 操作。对于远程或外部管理的 Gateway，应用从不使用此协调路径；从不降级较新的 Gateway；也从不覆盖 `extended-stable` 频道固定设置。

更新成功后，应用程序将一次性欢迎事件排队，以进行最近的顶级直接会话，并进行真正的 user/channel 交互。 Cron 运行、心跳和仅后台会话更新不会移动该选择。在远程模式下，应用程序仅更新其本地 Mac 节点运行时，并且仅当连接的远程网关至少与应用程序一样新时才发送事件。