openclaw update
更新 OpenClaw，并在 stable/extended-stable/beta/dev 频道之间切换。
如果你通过 npm/pnpm/bun 安装（全局安装，没有 git 元数据），更新会走 Updating 中描述的包管理器流程。
用法
openclaw --update 会重写为 openclaw update（对 shell 和启动器脚本有用）。
选项
| 标志 | 描述 |
|---|---|
--no-restart | 成功更新后跳过重启 Gateway 网关服务。会重启的包管理器更新会先验证重启后的服务报告预期版本，然后命令才会成功。 |
--channel <stable|extended-stable|beta|dev> | 设置更新频道，并在核心更新成功后持久保存。Extended-stable 仅适用于包安装。 |
--tag <dist-tag|version|spec> | 仅为本次更新覆盖包目标。它不能与有效的 extended-stable 频道组合使用，因为该频道必须使用已验证的精确目标。对于其他包安装，main 映射到 github:openclaw/openclaw#main；GitHub/git 源规格会在暂存的全局 npm 安装之前打包成临时 tarball。 |
--dry-run | 预览计划执行的操作（频道/tag/目标/重启流程），不写入配置、不安装、不同步插件，也不重启。 |
--json | 打印机器可读的 UpdateRunResult JSON。当托管插件需要修复时包含 postUpdate.plugins.warnings，包含 beta 频道插件回退详情，并在更新后同步期间检测到 npm 插件产物漂移时包含 postUpdate.plugins.integrityDrifts。 |
--timeout <seconds> | 每个步骤的超时时间。默认值为 1800。 |
--yes | 跳过确认提示（例如降级确认）。 |
--acknowledge-clawhub-risk | 允许更新后插件同步在遇到社区 ClawHub 信任警告时继续执行，而不显示交互式提示。没有它时，如果 OpenClaw 无法提示，存在风险的社区发布会被跳过并保持不变。官方 ClawHub 包和内置插件源会绕过此提示。 |
--verbose 标志。使用 --dry-run 预览计划执行的操作，使用 --json 获取机器可读结果，并使用 openclaw update status --json 仅查看频道/可用性。Gateway 网关控制台详细程度（--verbose）和文件日志级别（logging.level: "debug"/"trace"）是彼此独立的旋钮；参见 Gateway 日志。
在 Nix 模式（
OPENCLAW_NIX_MODE=1）下，会变更状态的 openclaw update 运行会被禁用。请改为更新此安装的 Nix 源或 flake 输入；对于 nix-openclaw，请使用以智能体优先的 快速开始。openclaw update status 和 openclaw update --dry-run 仍保持只读。update status
显示当前活动的更新频道、git tag/branch/SHA（仅源代码检出），以及更新可用性。
| 标志 | 默认值 | 描述 |
|---|---|---|
--json | false | 打印机器可读的状态 JSON。 |
--timeout <seconds> | 3 | 检查超时时间。 |
ahead of extended-stable。JSON 失败包含 registry.reason（selector_missing、selector_query_failed、exact_package_mismatch 或 unsupported_git_channel）。
update repair
在核心包已经更改但后续修复工作未干净完成时，重新运行更新收尾。这是在 openclaw update 已安装新的核心包，但核心后插件同步、托管 npm 插件元数据、注册表刷新或 Doctor 修复未收敛时支持的恢复路径。
| 标志 | 描述 |
|---|---|
--channel <stable|extended-stable|beta|dev> | 在修复前持久保存核心更新频道。对于 extended-stable，符合条件且遵循 bare/default 或 latest 意图的官方 npm 插件会以精确的已安装核心版本为目标。Extended-stable 修复在 Git 检出上会被拒绝，且不会更改配置。 |
--json | 打印机器可读的收尾 JSON。 |
--timeout <seconds> | 修复步骤的超时时间。默认值为 1800。 |
--yes | 跳过确认提示。 |
--acknowledge-clawhub-risk | 与 openclaw update 上的行为相同。 |
--no-restart | 为保持一致性而接受；修复永远不会重启 Gateway 网关。 |
update repair 会运行 openclaw doctor --fix，重新加载修复后的配置和安装记录，为活动更新频道同步已跟踪插件，更新托管 npm 插件安装，修复缺失的已配置插件载荷，刷新插件注册表，并写入已收敛的安装记录元数据。它不会安装新的核心包，也不会重启 Gateway 网关。
update wizard
用于选择更新频道并确认之后是否重启 Gateway 网关的交互式流程（默认重启）。在没有 git 检出的情况下选择 dev 会提供创建检出的选项。
| 标志 | 默认值 | 描述 |
|---|---|---|
--timeout <seconds> | 1800 | 每个更新步骤的超时时间。 |
它会做什么
显式切换频道（--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.channel: "extended-stable" 的 bare 前台更新、按需状态，以及托管 Gateway 网关交接仍然受支持。
当安装了本地托管的 Gateway 网关服务并启用重启时，
包管理器和 Git checkout 更新会先停止正在运行的服务，然后再
替换包目录树或修改 checkout/build 输出。更新程序随后会
刷新服务元数据、重启服务，并在报告 Gateway: restarted and verified. 之前验证
重启后的 Gateway 网关。
包管理器更新还会验证重启后的 Gateway 网关报告的是
预期包版本；Git checkout 更新会在重新构建后验证 Gateway 网关健康状况和
服务就绪状态。
在 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 在包管理器安装或受监管的 Git checkout 上通过 Gateway 网关控制平面
运行时，处理程序会将交接启动与 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
交接会在托管服务重启健康检查完成后更新同一个重启 sentinel。
在交接期间，sentinel 可以携带
stats.reason: "restart-health-pending"，且没有成功延续；重启后的
Gateway 网关会轮询它，并且只有在 CLI 验证服务健康状况并用最终 ok 结果
重写 sentinel 后才触发延续。
openclaw status 和 openclaw status --all 会在该 sentinel 待处理或失败时显示
Update restart 行，update.status 会刷新并返回最新 sentinel。
Git checkout 流程
渠道选择
stable：checkout 最新的非 beta 标签，然后构建并运行 Doctor。beta：优先使用最新的-beta标签；当 beta 缺失或更旧时， 回退到最新稳定标签。dev：checkoutmain，然后 fetch 并 rebase。extended-stable：Git checkout 不支持；不会发生 checkout 修改。
更新步骤
Preflight build (dev only)
在临时 worktree 中运行 TypeScript 构建。如果 tip 构建失败，会向前回退最多 10 个提交，以找到最新的可构建提交。设置
OPENCLAW_UPDATE_PREFLIGHT_LINT=1 还会在此预检期间运行 lint；lint 会以受限串行模式运行，因为用户更新主机通常比 CI runner 更小。Install dependencies
使用仓库包管理器。对于 pnpm checkout，更新程序会按需引导
pnpm（先通过 corepack，然后回退到临时 npm install pnpm@11），而不是在 pnpm workspace 内运行 npm run build。如果 pnpm 引导仍然失败，更新程序会提前停止并给出包管理器特定错误，而不是尝试在 checkout 中运行 npm run build。插件同步详情
在 beta 渠道上，遵循 default/latest 线的已跟踪 npm 和 ClawHub 插件安装会先尝试插件@beta 发布。如果插件没有 beta 发布，OpenClaw 会回退到记录的 default/latest 规范并
报告警告。对于 npm 插件，当 beta 包存在但安装验证失败时，OpenClaw 也会回退。这些回退警告不会
导致核心更新失败。精确版本和显式标签永远不会被重写。
更新后插件同步失败如果仅限于某个托管插件，并且同步路径可以绕过它（例如非必要插件的 npm registry 不可达），会在核心更新成功后报告为警告。JSON 结果会保持顶层更新
status: "ok"，并报告 postUpdate.plugins.status: "warning"，同时给出 openclaw update repair 和 openclaw plugins inspect <id> --runtime --json 指引。意外的更新程序或同步异常仍会导致更新结果失败。修复插件安装或更新错误，然后重新运行 openclaw update repair。在逐插件同步步骤之后，openclaw update 会在 Gateway 网关重启前运行强制性的 核心后收敛 过程：它会修复缺失的已配置插件载荷、验证磁盘上每条_活动_的已跟踪安装记录，并静态验证其 package.json 可解析（以及任何显式声明的 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 前缀中，
在那里验证打包的 dist 清单，然后将干净的包目录树交换到真实全局前缀。
如果验证失败，更新后 Doctor、
插件同步和重启工作不会从可疑目录树运行。即使
已安装版本已经匹配目标，命令也会刷新
全局包安装，然后运行插件同步、核心命令补全刷新
和重启工作。这会让打包的 sidecar 和渠道拥有的
插件记录与已安装的 OpenClaw 构建保持一致，同时将完整的
插件命令补全重建留给显式
openclaw completion --write-state 运行。