openclaw update
更新 OpenClaw，并在 stable/extended-stable/beta/dev 频道之间切换。
如果你是通过 npm/pnpm/bun 安装的（全局安装，没有 git 元数据），
更新会走 更新 中描述的包管理器流程。
用法
openclaw --update 会重写为 openclaw update（对 shell 和启动器脚本很有用）。
选项
没有
--verbose 标志。使用 --dry-run 预览计划中的操作，
使用 --json 获取机器可读结果，并使用 openclaw update status --json
仅查看渠道/可用性。Gateway 控制台详细程度（--verbose）和
文件日志级别（logging.level: "debug"/"trace"）是彼此独立的开关；请参见
Gateway 日志。
在 Nix 模式（
OPENCLAW_NIX_MODE=1）下，不允许会修改状态的 openclaw update 运行。请改为更新本次安装的 Nix source 或 flake input；对于 nix-openclaw，请使用 agent-first 的 快速开始。openclaw update status 和 openclaw update --dry-run 仍然是只读的。update status
显示当前活动的更新通道、git tag/branch/SHA（仅适用于源代码检出），以及更新可用性。
对于 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 修复未能收敛时，可使用此命令。
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-> 解析公开的 npmextended-stable选择器，验证所选中的确切包，并安装该精确版本。它不会回退到其他选择器，也不允许用于 Git 检出版本。beta-> 优先使用 npm dist-tagbeta，当 beta 缺失或比当前稳定版更旧时回退到latest。
重启交接
Gateway 核心自动更新器（在配置中启用时）会在实时 Gateway 请求处理程序之外启动 CLI 更新路径。控制平面update.run 的包管理器更新和受监管的 git 检出更新使用相同的受管服务交接方式，而不是替换包树或在实时 Gateway 进程内重建 dist/：Gateway 会启动一个分离的辅助进程并退出，然后该辅助进程从 Gateway 进程树之外运行 openclaw update --yes --json。如果交接不可用，update.run 会返回一个结构化响应，其中包含可手动执行的安全 shell 命令。
存储的 extended-stable 选择在启用 update.checkOnStart 时会收到只读启动和 24 小时更新提示。这些检查绝不会应用更新、启动交接、重启 Gateway、使用 stable 延迟/抖动，或使用 beta 轮询频率。显式前台更新、带有存储 update.channel: "extended-stable" 的裸前台更新、按需状态检查，以及它们受管的 Gateway 交接仍然受支持。
当本地安装了受管 Gateway 服务并启用了重启时，包管理器和 git 检出更新会先停止正在运行的服务，然后再替换包树或修改检出/构建输出。随后更新器会刷新服务元数据，重启服务，并在报告 Gateway: restarted and verified. 之前验证重启后的 Gateway。包管理器更新还会额外验证重启后的 Gateway 报告了预期的包版本；git 检出更新会在重建后验证 gateway 健康状况和服务就绪状态。
包管理器更新通常会继续使用记录在受管服务中的 Node 二进制文件。如果该 Node 无法运行目标版本，但当前 CLI 使用的 Node 可以，并且已确认该服务确实属于正在更新的包，那么启用重启的更新会在最终完成时使用当前 Node，并将服务元数据重写为该运行时。--no-restart 无法修复服务元数据，因此同样的运行时不匹配会在包变更之前停止。
在 macOS 上，更新后的检查还会验证当前配置文件对应的 LaunchAgent 已加载/运行，并且已配置的 loopback 端口健康。如果 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 检出上运行时，处理程序会单独报告交接启动，而 CLI 更新会在 Gateway 退出后继续执行：
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 交接更新会在受管服务重启健康检查完成后更新同一个重启 sentinel。在交接期间，sentinel 可以携带 stats.reason: "restart-health-pending"，且不会有成功的后续继续；重启后的 Gateway 会轮询它，并且只会在 CLI 验证了服务健康并将 sentinel 以最终 ok 结果重写之后才触发后续继续。openclaw status 和 openclaw status --all 会在该 sentinel 处于待定或失败状态时显示一行 Update restart，而 update.status 会刷新并返回最新的 sentinel。
Git 检出流程
渠道选择
stable: 检出最新的非 beta 标签，然后构建并运行 doctor。beta: 优先选择最新的-beta标签；如果 beta 缺失或更旧，则回退到最新的稳定标签。dev: 检出main，然后获取并 rebase。extended-stable: 不支持 Git 检出；不会发生任何 checkout 变更。
更新步骤
1
验证工作区干净
需要没有未提交的更改。
2
切换渠道
切换到所选渠道（tag 或 branch）。
3
获取上游
仅 dev。
4
预检构建（仅 dev）
在临时工作树中运行 TypeScript 构建。如果当前 tip 构建失败，则最多向前回溯 10 个提交，以查找最新的可构建提交。成功候选提交中按内容寻址的声明文件输出会被最终检出构建复用；rebase 后的源代码更改会自动使受影响的缓存组失效。设置
OPENCLAW_UPDATE_PREFLIGHT_LINT=1 还会在此预检阶段运行 lint；由于用户更新主机通常比 CI runner 更小，lint 会以受限的串行模式运行。5
Rebase
在所选提交上执行 rebase（仅 dev）。
6
Install dependencies
使用仓库的包管理器。对于 pnpm 检出，更新器会按需引导
pnpm（先通过 corepack，再回退到临时的 npm install pnpm@11），而不是在 pnpm 工作区内运行 npm run build。如果 pnpm 引导仍然失败，更新器会尽早停止，并返回特定于包管理器的错误，而不是尝试在该检出中运行 npm run build。7
构建检出
在最终检出中构建 Gateway 和 Control UI，各执行一次。仅当目标构建缺少这些资源，或 doctor 随后将其移除时，更新器才会运行独立的 Control UI 构建。
8
运行 doctor
openclaw doctor 作为最终的安全更新检查运行。9
同步插件
将插件同步到当前渠道。dev 使用捆绑插件；stable 和 beta 使用 npm。更新已跟踪的插件安装。
插件同步详情
在 beta 渠道上，跟踪的 npm 和 ClawHub 插件安装如果遵循 默认/最新分支，会先尝试插件的@beta 发布版本。如果该插件没有
beta 发布版本，OpenClaw 会回退到记录的默认/最新规格并
报告警告。对于 npm 插件，当 beta 包存在但安装验证失败时，
OpenClaw 也会回退。这些回退警告不会
使核心更新失败。精确版本和显式标签绝不会被重写。
更新后、针对受管插件且同步路径能够绕开的同步失败（例如某个非关键插件的 npm 注册表不可达）会在核心更新成功后作为警告报告。JSON 结果会保留顶层更新
status: "ok"，并报告 postUpdate.plugins.status: "warning"，同时给出 openclaw update repair 和 openclaw plugins inspect <id> --runtime --json 的指引。意外的更新器或同步异常仍会使更新结果失败。先修复插件安装或更新错误，然后重新运行 openclaw update repair。当一次失败的更新使某个受管插件不可用时，OpenClaw 会禁用其运行时条目并重置活动槽位，但不会更改操作员编写的 plugins.allow 或 plugins.deny 策略。在逐个插件同步步骤之后、Gateway 重启之前，openclaw update 会运行强制性的核心更新后收敛流程：修复缺失的已配置插件载荷，验证磁盘上每个_活动的_受跟踪安装记录，并静态验证其 package.json 可解析，且其中声明的 openclaw.extensions 条目可加载。当软件包未声明 OpenClaw 扩展时，该检查会改为验证其显式声明的 npm main。此流程中的失败以及无效的配置快照会返回 postUpdate.plugins.status: "error"，并将顶层更新 status 切换为 "error"，因此 openclaw update 会以非零状态退出，Gateway 也_不会_使用未经验证的插件集重启。错误信息会包含结构化的 postUpdate.plugins.warnings[].guidance 行，指向 openclaw update repair 和 openclaw plugins inspect <id> --runtime --json。已禁用的插件条目，以及未与受信任来源关联的官方同步目标记录，会在此处跳过（与缺失载荷检查所使用的 skipDisabledPlugins 策略一致），因此过时的已禁用插件记录不会阻止其他有效的更新。当更新后的 Gateway 启动时，插件加载仅进行验证：启动过程不会运行包管理器，也不会修改依赖树。包管理器的 update.run 重启会交给 CLI 托管服务路径处理，因此包替换发生在旧 Gateway 进程之外，而服务健康检查会决定该更新是否可以被报告为完成。latest 意图，OpenClaw 不会查询插件 @extended-stable，也不会回退到 npm latest；它会根据已安装的核心推导包版本。显式版本固定、显式非 latest 标签、第三方包以及非 npm 来源会保留其现有意图。
对于包管理器安装，openclaw update 会在调用包管理器之前解析目标包版本。npm 全局安装使用分阶段安装：OpenClaw 会先将新包安装到临时 npm 前缀中，让候选包在 preinstall 期间验证主机 Node 版本，并在那里验证打包后的 dist 清单。一个打包完成保护机制会在 preinstall 成功之前保持在该清单之外，因此会跳过生命周期脚本的包管理器也会在激活前停止。在 npm 12 及更新版本上，更新器只批准候选 OpenClaw 生命周期；传递性依赖脚本仍会被阻止。随后 OpenClaw 会将干净的包树交换到真实的全局前缀中。如果验证失败，后更新 doctor、插件同步和重启工作都不会从可疑树中运行。即使已安装版本已经与目标版本匹配，命令也会刷新全局包安装，然后运行插件同步、核心命令完成刷新以及重启工作。这样可以让打包的 sidecar 和渠道拥有的插件记录与已安装的 OpenClaw 构建保持一致，同时将完整的插件命令完成重建留给显式的 openclaw completion --write-state 运行。