# openclaw update

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

如果你通过 npm/pnpm/bun 安装（全局安装，没有 git 元数据）， 更新会通过 更新中的包管理器流程进行。

# 用法

openclaw update
openclaw update status
openclaw update wizard
openclaw update --channel beta
openclaw update --channel dev
openclaw update --tag beta
openclaw update --tag main
openclaw update --dry-run
openclaw update --no-restart
openclaw update --yes
openclaw update --json
openclaw --update

# 选项

• --no-restart：成功更新后跳过重启 Gateway 网关服务。会重启 Gateway 网关的包管理器更新会先验证重启后的服务报告预期的更新版本，然后命令才会成功。
• --channel <stable|beta|dev>：设置更新渠道（git + npm；持久化到配置中）。
• --tag <dist-tag|version|spec>：仅为本次更新覆盖包目标。对于包安装，main 映射到 github:openclaw/openclaw#main。
• --dry-run：预览计划的更新操作（渠道/标签/目标/重启流程），不写入配置、不安装、不同步插件，也不重启。
• --json：打印机器可读的 UpdateRunResult JSON，包括 核心更新成功后存在损坏或无法加载的托管插件需要修复时的 postUpdate.plugins.warnings，以及更新后插件同步期间检测到 npm 插件工件漂移时的 postUpdate.plugins.integrityDrifts。
• --timeout <seconds>：每个步骤的超时时间（默认 1800s）。
• --yes：跳过确认提示（例如降级确认）。

openclaw update 没有 --verbose 标志。使用 --dry-run 预览 计划的渠道/标签/安装/重启操作，使用 --json 获取机器可读结果， 当你只需要渠道和可用性详情时，使用 openclaw update status --json。 如果你正在调试更新相关的 Gateway 网关日志， 控制台详细程度和文件日志级别是分开的：Gateway 网关 --verbose 会影响 终端/WebSocket 输出，而文件日志需要在配置中设置 logging.level: "debug" 或 "trace"。参见 Gateway 网关日志。

# update status

显示活动更新渠道 + git 标签/分支/SHA（适用于源码检出），以及更新可用性。

openclaw update status
openclaw update status --json
openclaw update status --timeout 10

选项：

• --json：打印机器可读的状态 JSON。
• --timeout <seconds>：检查超时时间（默认 3s）。

# update wizard

用于选择更新渠道并确认更新后是否重启 Gateway 网关的交互式流程 （默认会重启）。如果你选择 dev 但没有 git 检出，它会提议创建一个。

选项：

• --timeout <seconds>：每个更新步骤的超时时间（默认 1800）

# 它会做什么

当你显式切换渠道（--channel ...）时，OpenClaw 也会保持安装方式一致：

• dev → 确保存在一个 git checkout（默认：~/openclaw，可用 OPENCLAW_GIT_DIR 覆盖），更新它，并从该 checkout 安装全局 CLI。
• stable → 使用 latest 从 npm 安装。
• beta → 优先使用 npm dist-tag beta，但当 beta 缺失或早于当前 stable 版本时，会回退到 latest。

OpenClaw 目前还没有 LTS 或月度支持渠道。我们正在朝月度支持线推进，但 --channel 目前只接受 stable、beta 和 dev。当你需要某个特定包产物作为一次性目标时，请使用 --tag <version-or-dist-tag>。

Gateway 网关核心自动更新器（通过配置启用时）会在实时 Gateway 网关请求处理程序之外启动 CLI 更新路径。控制平面 update.run package-manager 更新会在包替换后强制执行一次非延迟、无冷却的更新重启，因为旧 Gateway 网关进程可能仍有内存中的分块指向已被新包移除的文件。

对于 package-manager 安装，openclaw update 会先解析目标包版本，再调用 package manager。npm 全局安装使用分阶段安装：OpenClaw 会把新包安装到临时 npm 前缀中，在那里验证打包的 dist 清单，然后将这个干净的包树替换到真实全局前缀中。如果验证失败，更新后的 Doctor、插件同步和重启工作不会从可疑树运行。即使已安装版本已经匹配目标，命令也会刷新全局包安装，然后运行插件同步、核心命令补全刷新和重启工作。这样会让打包的 sidecar 和渠道拥有的插件记录与已安装的 OpenClaw 构建保持一致，同时把完整的插件命令补全重建留给显式的 openclaw completion --write-state 运行。

当本地托管的 Gateway 网关服务已安装并且启用了重启时，package-manager 更新会先停止正在运行的服务，再替换包树，然后从更新后的安装刷新服务元数据、重启服务，并在报告成功前验证重启后的 Gateway 网关报告预期版本。在 macOS 上，更新后检查还会验证 LaunchAgent 是否已为当前配置文件加载/运行，以及配置的 loopback 端口是否健康。如果 plist 已安装但 launchd 没有监管它，OpenClaw 会自动重新引导 LaunchAgent，然后重新运行健康状态、版本和渠道就绪检查。新的引导会直接加载 RunAtLoad 作业，因此更新恢复不会立即对新生成的 Gateway 网关执行 kickstart -k。如果 Gateway 网关仍未变为健康状态，命令会以非零状态退出，并打印重启日志路径以及明确的重启、重新安装和包回滚说明。使用 --no-restart 时，包替换仍会运行，但托管服务不会被停止或重启，因此正在运行的 Gateway 网关可能会继续使用旧代码，直到你手动重启它。

# Git checkout 流程

# 渠道选择

• stable：checkout 最新的非 beta 标签，然后构建并运行 Doctor。
• beta：优先使用最新的 -beta 标签，但当 beta 缺失或早于最新 stable 标签时，会回退到最新 stable 标签。
• dev：checkout main，然后 fetch 并 rebase。

# 更新步骤

在 beta 更新渠道上，跟随 default/latest 线路的已跟踪 npm 和 ClawHub 插件安装会先尝试插件 @beta 版本。如果插件没有 beta 版本，OpenClaw 会回退到记录的 default/latest spec。对于 npm 插件，如果 beta 包存在但安装验证失败，OpenClaw 也会回退。精确版本和显式标签不会被重写。

# --update 简写

openclaw --update 会重写为 openclaw update（对 shell 和启动器脚本很有用）。

# 相关

• openclaw doctor（在 git checkout 上会提议先运行 update）
• 开发渠道
• 更新
• CLI 参考