openclaw update

更新 OpenClaw，并在 stable/extended-stable/beta/dev 渠道之间切换。

如果通过 npm/pnpm/bun 安装（全局安装，无 git 元数据）， 更新将遵循 更新中所述的包管理器流程。

用法

openclaw updateopenclaw update statusopenclaw update repairopenclaw update wizardopenclaw update --channel extended-stableopenclaw update --channel betaopenclaw update --channel devopenclaw update --tag betaopenclaw update --tag mainopenclaw update --dry-runopenclaw update --no-restartopenclaw update --yesopenclaw update --acknowledge-clawhub-riskopenclaw update --jsonopenclaw --update

openclaw --update 会重写为 openclaw update（适用于 shell 和 启动器脚本）。

选项

不存在 --verbose 标志。使用 --dry-run 预览计划执行的操作， 使用 --json 获取机器可读结果，使用 openclaw update status --json 仅获取渠道/可用性信息。Gateway 网关控制台详细程度（--verbose）和 文件日志级别（logging.level: "debug"/"trace"）是相互独立的设置；请参阅 Gateway 网关日志。

update status

显示当前更新渠道、git 标签/分支/SHA（仅限源代码检出）， 以及更新可用性。

openclaw update statusopenclaw update status --jsonopenclaw update status --timeout 10

对于 extended-stable 包安装，状态检查会执行与前台更新相同的公共选择器解析 和确切包验证。当已安装版本较新时，它可能会报告 ahead of extended-stable。JSON 失败结果 包含 registry.reason（selector_missing、selector_query_failed、 exact_package_mismatch 或 unsupported_git_channel）。

update repair

当核心包已发生更改，但后续修复工作未能顺利完成时， 重新运行更新收尾流程。如果 openclaw update 已安装新的核心包， 但核心更新后的插件同步、托管 npm 插件元数据、注册表刷新或 Doctor 修复 未能收敛，这是受支持的恢复路径。

openclaw update repairopenclaw update repair --channel betaopenclaw update repair --acknowledge-clawhub-riskopenclaw update repair --json

update repair 会运行 openclaw doctor --fix，重新加载修复后的配置和 安装记录，为当前更新渠道同步受跟踪的插件，更新 托管的 npm 插件安装，修复缺失的已配置插件载荷， 刷新插件注册表，并写入已收敛的安装记录元数据。 它不会安装新的核心包，也不会重启 Gateway 网关。

update wizard

通过交互式流程选择更新渠道，并确认随后是否重启 Gateway 网关（默认重启）。如果没有 git 检出，选择 dev 时会提供创建检出的选项。

工作原理

显式切换渠道（--channel ...）还会确保安装方式 保持一致：

• dev -> 确保存在 git 检出（默认为 ~/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。

重启交接

Gateway 网关核心自动更新程序（通过配置启用时）会在实时 Gateway 网关请求处理程序之外 启动 CLI 更新路径。控制平面的 update.run 包管理器更新和受监管的 git 检出更新使用 相同的托管服务交接机制，而不会在实时 Gateway 网关进程中替换包树或 重新构建 dist/：Gateway 网关会启动一个 分离的辅助进程并退出，该辅助进程随后从 Gateway 网关进程树之外运行 openclaw update --yes --json。 如果交接不可用， update.run 会返回结构化响应，其中包含可安全手动运行的 shell 命令。

启用 update.checkOnStart 后，已存储的扩展稳定版选择会在启动时获得只读提示，并每 24 小时获得一次更新提示。这些检查绝不会应用更新、启动交接、重启 Gateway 网关、使用稳定版延迟/抖动或采用测试版轮询频率。仍支持显式前台更新、带有已存储 update.channel: "extended-stable" 的无参数前台更新、按需状态查询及其托管式 Gateway 网关交接。

安装本地托管式 Gateway 网关服务并启用重启后，包管理器和 Git 检出更新会先停止正在运行的服务，再替换软件包目录树或修改检出目录/构建输出。然后，更新程序会刷新服务元数据、重启服务并验证重启后的 Gateway 网关，之后才报告 Gateway: restarted and verified.。 包管理器更新还会验证重启后的 Gateway 网关报告了预期的软件包版本；Git 检出更新则会在重新构建后验证 Gateway 健康和服务就绪状态。

包管理器更新通常会继续使用托管服务中记录的 Node 二进制文件。如果该 Node 无法运行目标版本，但当前 CLI 使用的 Node 可以运行，并且已证实该服务属于正在更新的软件包，则启用了重启的更新会使用当前 Node 完成收尾，并将服务元数据改写为使用该运行时。--no-restart 无法修复服务元数据，因此遇到相同的运行时不匹配时，会在修改软件包之前停止。

在 macOS 上，更新后检查还会验证 LaunchAgent 已针对活动配置文件加载并正在运行，且配置的环回端口处于健康状态。如果 plist 已安装，但 launchd 未对其进行监管，OpenClaw 会自动重新引导 LaunchAgent，并重新运行健康状况/版本/渠道就绪检查（全新引导会直接加载 RunAtLoad 作业，因此恢复过程不会立即 kickstart -k 新生成的 Gateway 网关）。如果 Gateway 网关仍未恢复健康，命令将以非零状态退出，并输出重启日志路径以及重启、重新安装和软件包回滚说明。

如果无法执行重启，命令会输出 Gateway: restart skipped (...) 或 Gateway: restart failed: ...，并附带手动执行 openclaw gateway restart 的提示。 使用 --no-restart 时，软件包替换或 Git 重新构建仍会执行，但托管服务不会停止或重启，因此正在运行的 Gateway 网关会继续使用旧代码，直到你手动重启它。

控制平面响应结构

当 update.run 通过 Gateway 网关控制平面在包管理器安装或受监管的 Git 检出中运行时，处理程序会将交接启动与 Gateway 网关退出后继续进行的 CLI 更新分别报告：

• ok: true、result.status: "skipped"、 result.reason: "managed-service-handoff-started" 和 handoff.status: "started"：Gateway 网关已创建托管服务交接并安排自身重启，以便分离的辅助程序能够在实时服务进程之外运行 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 载荷会在 Gateway 网关退出前写入，CLI 交接会在托管服务重启健康检查完成后更新同一个重启哨兵。交接期间，该哨兵可能包含 stats.reason: "restart-health-pending"，且没有成功续接；重启后的 Gateway 网关会轮询该哨兵，并且仅在 CLI 验证服务健康状况并用最终的 ok 结果改写哨兵后，才触发续接。 当该哨兵处于待处理或失败状态时，openclaw status 和 openclaw status --all 会显示一行 Update restart，而 update.status 会刷新并返回最新哨兵。

Git 检出流程

渠道选择

• stable：检出最新的非测试版标签，然后执行构建和 Doctor。
• beta：优先选择最新的 -beta 标签；如果测试版不存在或版本更旧，则回退到最新的稳定版标签。
• dev：检出 main，然后获取并变基。
• extended-stable：Git 检出不支持此项；不会修改检出目录。

更新步骤

插件同步详情

在测试版渠道中，遵循默认/最新版本线的受跟踪 npm 和 ClawHub 插件安装会先尝试插件 @beta 版本。如果插件没有测试版，OpenClaw 会回退到已记录的默认/最新规范并报告警告。对于 npm 插件，如果测试版软件包存在但未通过安装验证，OpenClaw 也会回退。这些回退警告不会导致核心更新失败。绝不会改写精确版本和显式标签。

扩展稳定版核心更新成功后，核心更新后的插件完整性和收敛会以符合条件的官方 npm 插件为目标，并使用已安装核心的精确版本。对于默认/latest 意图，OpenClaw 不会查询插件 @extended-stable，也不会回退到 npm latest；它会根据已安装的核心推导软件包版本。显式版本固定、显式的非 latest 标签、第三方软件包和非 npm 来源会保留其现有意图。

对于包管理器安装，openclaw update 会在调用包管理器之前解析目标软件包版本。npm 全局安装采用暂存式安装：OpenClaw 将新软件包安装到临时 npm 前缀中，让候选软件包在 preinstall 期间验证主机 Node 版本，并在那里验证打包的 dist 清单。在 preinstall 成功前，打包完成守卫始终位于该清单之外，因此跳过生命周期脚本的包管理器也会在激活前停止。在 npm 12 及更高版本中，更新程序仅批准候选 OpenClaw 的生命周期脚本；传递依赖项脚本仍会被阻止。然后，OpenClaw 会将干净的软件包目录树交换到实际的全局前缀中。如果验证失败，则不会从可疑目录树运行更新后 Doctor、插件同步和重启操作。即使已安装版本已与目标匹配，该命令仍会刷新全局软件包安装，然后运行插件同步、核心命令补全刷新和重启操作。这会使打包的附属组件和渠道所有的插件记录与已安装的 OpenClaw 构建保持一致，同时将完整的插件命令补全重新构建留给显式的 openclaw completion --write-state 运行。

相关内容

• openclaw doctor（在 Git 检出中会先提议运行更新）
• 开发渠道
• 更新
• CLI 参考