Appearance
openclaw update 是安全更新 OpenClaw 并切换更新通道的命令。支持 stable/beta/dev 三个通道，在 git 源码安装时执行预检构建、rebase 和 doctor 验证。包管理器安装时采用暂存区交换和托管服务交接，重启后验证 Gateway 版本。Nix 模式（OPENCLAW_NIX_MODE=1）下 update 操作为只读，只能执行 status 和 --dry-run。降级需要确认。常用子命令：status（查看当前通道和可用更新）、wizard（交互式向导）。可通过 --json 获取机器可读输出，包括插件同步后的警告和完整性漂移信息。
openclaw update：安全更新 OpenClaw 并切换版本通道
如果你是通过 npm/pnpm/bun 全局安装的（没有 git 元数据），更新方式请参考包管理器流程：更新指南。
用法
bash
openclaw update
openclaw update status
openclaw update wizard
openclaw update --channel beta
openclaw update --channel dev
openclaw update --tag beta
openclaw update --dry-run
openclaw update --no-restart
openclaw update --yes
openclaw update --json
openclaw --update选项说明
--no-restart：更新成功后跳过 Gateway 服务重启。包管理器更新默认会重启 Gateway 并验证重启后的版本是否匹配预期。如果跳过重启，运行中的 Gateway 可能继续使用旧代码，需手动重启。--channel <stable|beta|dev>：设置更新通道（git 和 npm 安装均支持，会持久化到配置文件）。--tag <dist-tag|version|spec>：仅针对本次更新覆盖包目标，不修改配置。要切换到移动的 GitHubmaincheckout 请使用--channel dev，而不是--tag main。--dry-run：预览计划中的更新操作（通道/标签/目标/重启流程），不实际写入配置、安装、同步插件或重启。--json：输出机器可读的UpdateRunResultJSON，包含：postUpdate.plugins.warnings：核心更新成功后，如果有损坏或无法加载的托管插件需要修复时列出。postUpdate.plugins.integrityDrifts：npm 插件在更新后同步时检测到制品完整性漂移时列出。- beta 通道下插件无 beta 版本时的回退细节。
--timeout <seconds>：每个步骤的超时时间（默认 1800 秒）。--yes：跳过确认提示（例如降级确认）。
openclaw update 没有 --verbose 标志。要预览计划的操作，使用 --dry-run；要机器可读输出，使用 --json；仅需查看通道和可用性细节，使用 openclaw update status --json。如果调试 Gateway 日志，终端的详细程度和文件日志级别是分开的，Gateway --verbose 影响终端/WebSocket 输出，文件日志需要配置 logging.level: "debug" 或 "trace"。参见 Gateway 日志。
INFO
在 Nix 模式（OPENCLAW_NIX_MODE=1）下，openclaw update 的变异运行被禁用。对于 Nix 安装，更新 Nix 源或 flake 输入；对于 nix-openclaw，使用 agent-first 的 Quick Start。openclaw update status 和 openclaw update --dry-run 仍为只读操作。
WARNING
降级需要确认，因为旧版本可能导致配置格式不兼容。
update status：查看当前更新通道和可用更新
显示当前更新通道、git 标签/分支/SHA（仅限源码安装），以及是否有可用更新。
bash
openclaw update status
openclaw update status --json
openclaw update status --timeout 10选项：
--json：输出机器可读的状态 JSON。--timeout <seconds>：检查超时时间（默认 3 秒）。
update wizard：交互式更新向导
交互式流程：选择更新通道，确认是否在更新后重启 Gateway（默认重启）。如果选择 dev 通道但没有 git checkout，向导会提示你创建一个。
选项：
--timeout <seconds>：每个更新步骤的超时时间（默认 1800 秒）。
更新流程详解
通道切换时的安装方式对齐
显式切换通道（--channel ...）时，OpenClaw 会同步对齐安装方式：
dev→ 确保存在 git checkout（默认路径：~/openclaw，可通过OPENCLAW_GIT_DIR覆盖），更新后从该 checkout 安装全局 CLI。stable→ 从 npm 使用latest安装。beta→ 优先使用 npm dist-tagbeta，但如果 beta 缺失或比当前 stable 版本旧，则回退到latest。
包管理器安装的更新流程
对于包管理器安装，openclaw update 先解析目标包版本，再调用包管理器。npm 全局安装使用暂存区安装：OpenClaw 将新包安装到临时 npm 前缀，验证打包的 dist 清单，然后将干净的包树交换到真正的全局前缀。如果验证失败，后置的 doctor、插件同步和重启工作不会从可疑的包树运行。即使已安装版本与目标匹配，命令也会刷新全局包安装，然后运行插件同步、核心命令补全刷新和重启工作。这确保打包的 sidecar 和渠道拥有的插件记录与已安装的 OpenClaw 构建保持一致，而完整的插件命令补全重建留给显式 openclaw completion --write-state 执行。
当本地托管 Gateway 服务已安装且重启启用时，包管理器更新会先停止运行中的服务，替换包树，刷新服务元数据，重启服务，并验证重启后的 Gateway 报告预期的版本，然后输出 Gateway: restarted and verified.。在 macOS 上，后置更新检查还会验证 LaunchAgent 是否已加载/运行（针对活动 profile），以及配置的 loopback 端口是否健康。如果 plist 已安装但 launchd 没有监督它，OpenClaw 会自动重新引导 LaunchAgent，然后重新运行健康/版本/通道就绪检查。新的引导直接加载 RunAtLoad 任务，因此更新恢复不会立即 kickstart -k 新生成的 Gateway。如果 Gateway 仍未健康，命令以非零退出，并打印重启日志路径及显式的重启、重新安装和包回滚指令。如果无法重启，命令打印 Gateway: restart skipped (...) 或 Gateway: restart failed: ...，并提示手动 openclaw gateway restart。使用 --no-restart 时，包替换仍然执行，但托管服务不会被停止或重启，因此运行中的 Gateway 可能继续使用旧代码，直到手动重启。
控制面响应格式
当通过 Gateway 控制面在包管理器安装上调用 update.run 时，处理程序会将交接启动与 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 找不到安全的交接服务边界。响应中包含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 在哨兵处于 pending 或 failed 状态时会显示 Update restart 行，update.status 返回最新的缓存哨兵。
Git checkout 更新流程
通道选择
stable：检出最新的非 beta 标签，然后构建并运行 doctor。beta：优先检出最新的-beta标签，但如果 beta 缺失或比最新 stable 标签旧，则回退到最新 stable 标签。dev：检出main分支，然后 fetch 并 rebase。
更新步骤
- 验证工作区干净：要求没有未提交的更改。
- 切换通道：切换到所选通道（标签或分支）。
- 拉取上游：仅 dev 通道。
- 预检构建（仅 dev 通道）：在临时 worktree 中运行 TypeScript 构建。如果最新提交构建失败，最多回溯 10 个提交，找到最新的可构建提交。设置
OPENCLAW_UPDATE_PREFLIGHT_LINT=1以在预检中也运行 lint；lint 以受限的串行模式运行，因为用户更新主机通常比 CI runner 小。 - Rebase：rebase 到所选提交（仅 dev 通道）。
- 安装依赖：使用仓库包管理器。对于 pnpm 仓库，更新程序按需引导
pnpm（先尝试corepack，然后回退到临时npm install pnpm@11），而不是在 pnpm workspace 中运行npm run build。 - 构建 Control UI：构建 Gateway 和 Control UI。
- 运行 doctor：
openclaw doctor作为最终的"安全更新"检查。 - 同步插件：将插件同步到当前通道。dev 使用捆绑插件；stable 和 beta 使用 npm。更新跟踪的插件安装。
在 beta 通道上，跟踪的 npm 和 ClawHub 插件安装（遵循 default/latest 行）会先尝试插件的 @beta 版本。如果插件没有 beta 版本，OpenClaw 回退到记录的 default/latest spec 并报告为警告。对于 npm 插件，当 beta 包存在但安装验证失败时，也会回退。这些插件回退警告不会导致核心更新失败。精确版本和显式标签不会被重写。
WARNING
如果精确锁定的 npm 插件更新解析出的制品与存储的安装记录完整性不一致，openclaw update 会中止该插件制品的更新而非安装它。只有在确认信任新制品后，才显式重新安装或更新该插件。
INFO
更新后插件同步失败（限于托管插件且同步路径可以绕过的情况，例如非必要插件的 npm 注册表不可达）会报告为警告，核心更新成功。JSON 结果保持顶层更新 status: "ok"，并报告 postUpdate.plugins.status: "warning"，附带 openclaw doctor --fix 和 openclaw plugins inspect <id> --runtime --json 指导。意外的更新程序或同步异常仍会导致更新失败。修复插件安装或更新错误，然后重新运行 openclaw doctor --fix 或 openclaw update。
在每个插件同步步骤之后，openclaw update 在重启 Gateway 之前会执行一次强制性的后核心收敛阶段：修复缺失的已配置插件负载，验证磁盘上每个_活动_跟踪安装记录，并静态验证其 package.json 可解析（以及任何显式声明的 main 存在）。该阶段的失败（以及无效的 OpenClaw 配置快照）会返回 postUpdate.plugins.status: "error" 并将顶层更新 status 翻转为 "error"，因此 openclaw update 以非零退出，Gateway 不会用未经验证的插件集重启。错误包含结构化的 postUpdate.plugins.warnings[].guidance 行，指向 openclaw doctor --fix 和 openclaw plugins inspect <id> --runtime --json 进行后续操作。已禁用的插件条目和不受信任来源链接的官方同步目标会被跳过，这与缺失负载检查中使用的 skipDisabledPlugins 策略一致，因此一个过期的已禁用插件记录不会阻塞有效的更新。
更新后的 Gateway 启动时，插件加载仅为验证模式：启动时不运行包管理器或变更依赖树。包管理器 update.run 重启交接给 CLI 托管服务路径，因此包交换发生在旧 Gateway 进程外部，服务健康检查决定更新是否可报告为完成。
如果 pnpm 引导仍然失败，更新程序会停止并给出特定于包管理器的错误，而不会尝试在仓库中运行 npm run build。
--update 简写
openclaw --update 等价于 openclaw update，方便在 shell 脚本和启动器中使用。
相关命令
常见问题
openclaw update --dry-run 做了什么？
只预览计划的操作（通道/标签/目标/重启流程），不实际写入配置、安装、同步插件或重启。可用于检查更新会做什么而不实际执行。
openclaw update 更新后 Gateway 没有重启怎么办？
检查是否使用了 --no-restart 选项。如果未使用，更新成功后应该自动重启。如果重启失败，命令会输出 Gateway: restart failed: ... 并提示手动执行 openclaw gateway restart。在 macOS 上，还会检查 LaunchAgent 状态，如果 plist 安装但 launchd 未监督，会尝试自动重新引导。
降级时为什么需要确认？
因为旧版本可能导致配置文件格式不兼容，OpenClaw 要求手动确认降级操作，防止意外破坏配置。使用 --yes 可以跳过确认。