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 网关、使用稳定版延迟/抖动，也不会使用 beta 版轮询频率。显式前台更新、已存储 update.channel: "extended-stable" 时不带参数的前台更新、按需状态检查及其托管 Gateway 网关移交仍受支持。

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

在 macOS 上，更新后检查还会验证当前配置文件对应的 LaunchAgent 已加载并正在运行，并且配置的回环端口处于健康状态。如果 plist 已安装，但 launchd 未对其进行监管，OpenClaw 会自动重新引导 LaunchAgent，并重新运行健康/版本/渠道就绪检查（全新引导会直接加载 RunAtLoad 作业，因此恢复过程不会立即对新启动的 Gateway 网关执行 kickstart -k）。如果 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：检出最新的非 beta 标签，然后执行构建和 Doctor。
• beta：优先使用最新的 -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 前缀中，在其中验证打包后的 dist 清单，然后将这个干净的软件包树替换到实际的全局前缀中。如果验证失败，则不会从可疑的软件包树中运行更新后的 Doctor、插件同步和重启操作。即使已安装版本与目标版本相同，该命令仍会刷新全局软件包安装，然后执行插件同步、核心命令补全刷新和重启操作。这样可以让打包的辅助文件和渠道所有的插件记录与已安装的 OpenClaw 构建保持一致，同时将完整的插件命令补全重建留给显式运行的 openclaw completion --write-state。

相关内容

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