企业官网建设流程全解析

OpenClaw 如何用 openclaw update 安全升级并回滚？

【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 🦞项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw

如果你已经在机器上装好了 OpenClaw（npm、pnpm、Bun 全局安装或 git checkout），想升级到新版本又不担心升坏后救不回来，openclaw update就是文档推荐的升级入口：它会自动识别安装类型（npm、pnpm、Bun 或 git），在旧 Gateway 继续服务的前提下验证候选版本，通过验证后才停机激活并做升级后校验，失败时还能自动恢复上一代包。本文按「升级前备份 → 预览 → 升级 → 验证 → 回滚/收尾」的路径整理，全部命令来自 Updating 与openclaw updateCLI 参考。

升级前先建一个经过校验的备份

openclaw update会自动保留一份升级前的配置副本，但文档明确说明：自动配置副本和迁移恢复原始文件都不是完整状态备份。重大升级前应显式创建一次经校验的归档（归档里会包含凭据、auth profiles、频道状态等，要按与线上状态目录相同的权限保护存放）：

mkdir -p ~/Backups/openclaw openclaw backup create --output ~/Backups/openclaw --verify

--verify会在写完归档后立即执行校验；归档清单会记录 OpenClaw 版本和被包含的源路径，具体覆盖范围见 Backup。如果回滚后发现当前状态已被迁移、旧版本读不了，文档给出的受支持恢复方式就是用这份升级前备份连同匹配的 OpenClaw 版本一起恢复，而不是指望回滚命令撤销迁移。

用 --dry-run 预览升级动作

真正执行前，先预览计划动作。--dry-run不会写配置、不会安装、不会同步插件、不会重启：

openclaw update --dry-run

对 git checkout，--dry-run连 Git refs 都不会 fetch，也不检查工作区改动；真实的更新会在修改 checkout 前检查未提交变更。想看当前通道、可用性和最近一次升级报告，用：

openclaw update status openclaw update status --json

注意openclaw update没有--verbose标志（那是安装器的），诊断就靠--dry-run和--json。

执行 openclaw update

openclaw update

运行过程的阶段与 Control UI 一致：requested→staging→validating→（可选repairing）→activating→restarting→verifying→finished。几个影响实际操作的事实：

• 旧 Gateway 在staging和validating全程保持服务；候选验证包含候选 Doctor lint、配置校验、插件规划，以及用复制的配置和已校验的 SQLite 快照在隔离临时状态目录里做 canary 启动。只有activating阶段才会停受管服务。
• 如果目标版本就是已装版本（或 Git 目标 SHA 等于HEAD），运行以skipped/already-current结束，不会停或重启 Gateway。
• 验证失败时，更新器可以进入有边界的repairing阶段，用已配置的推理修复候选并重跑失败检查；只有检查通过才允许激活，否则丢弃候选、旧 Gateway 原样不动。
• 激活后的验证包含：受管服务在运行且持有自己的端口、12 探针健康稳定、Gateway hello 握手匹配预期版本和 Git 构建标识、插件激活无错误、频道就绪、/readyz返回 200。
• 本地受管服务且启用重启时，只有重启后的服务通过验证，命令才会报告Gateway: restarted and verified.，最终报告记录停机时长（downtimeMs）和验证结果。

如果当前版本已满足需求但想切换通道，或想一次性指定版本，常用变体：

openclaw update --channel beta openclaw update --channel extended-stable # 仅包安装，git checkout 上会被拒绝 openclaw update --channel dev # 切到 git checkout 并构建 openclaw update --tag beta # 一次性钉住 npm beta dist-tag

--channel的选择会被持久化，成为后续手动检查和自动升级的通道；--tag只影响这一次升级。包更新还会在停掉服务之前检查已启用插件在 npm 上的可用性，缺失版本或注册表错误会以plugin-target-unavailable拒绝升级，此时等注册表恢复重试，或用openclaw update --tag <version>换一个可用版本。

升级后怎么确认成功

成功的受管openclaw update已经完成重启和验证，不需要再做「After updating」那套；以下命令用于手动安装之后或检查报告的问题：

openclaw doctor openclaw gateway restart openclaw health

openclaw doctor会迁移配置、审计 DM 策略并检查 Gateway 健康，还会比较活动官方插件与受管服务重启后将加载的 OpenClaw 包，出现插件重启就绪警告要先处理。无论哪种方式，都建议用openclaw update status读一次活动或最近一次的持久化报告（重启后仍在），报告包含结果、各阶段耗时、失败步骤和验证事实；--json暴露activeRun/lastRun记录。

回滚：先看它是否已经自动做了

当新激活的包没通过验证时，openclaw update会先做「schema 中立」检查：比较共享库和受影响的 per-agent SQLiteuser_version与激活前的值，并确认配置文件仍与候选激活 Doctor 写入的内容一致。两项检查都通过且保留的旧包此前已被验证过，更新器就停掉候选、恢复上一代包、命令 shim、服务定义和激活前的精确配置字节，然后重新验证恢复后的 Gateway。恢复成功时运行以rolled-back结束，报告标题形如↩️ OpenClaw update rolled back to <previous>: <reason>（文档示例格式），命令仍以非零码退出——恢复不会把被拒绝的候选变成成功升级。用openclaw update status看记录的原因，openclaw triage诊断失败的检查。

自动回滚拒绝的几种情形要认得：

• state-migrated-no-rollback：激活 Doctor 之后配置被改过，或数据库不是 schema 中立。此时更新器会在已安装的候选上进入repairing，用openclaw triage或打印的修复命令处理，不要直接考虑旧版本。
• rollback-state-unverified：schema 比较无法完成，或激活期间新建的数据库旧包不支持。
• pnpm/Bun 上 staging 之后全局兄弟包有变化会触发rollback-project-changed，不会恢复共享工程。

要点：代码回滚不能撤销状态迁移。如果数据库已经被迁移到旧版本读不了的格式，受支持的恢复路径是恢复升级前备份（连同匹配的包版本），见 Downgrade 一节。

需要手动降级时怎么做

文档建议升级和恢复都优先走openclaw update——它会校验目标、跑必要的 Doctor 迁移并验证激活后的 Gateway；裸npm i -g替换既不保留旧包也不执行恢复流程。对能读取当前状态的目标版本：

openclaw update --tag <known-good-version> --dry-run openclaw update --tag <known-good-version>

<known-good-version>替换为你确认过能读当前状态的版本。更新器会做兼容性检查并请求降级确认（降级需要确认，因为旧版本可能破坏配置）；如果保存的通道是extended-stable，一次性精确 tag 要加--channel stable。如果激活被拒绝，按打印的恢复指引走，不要绕过「更新的 schema / 更新的配置」这类拒绝。回滚完成后的验证序列：

openclaw --version openclaw health openclaw gateway status --deep --json openclaw doctor --lint --json openclaw update cleanup --dry-run

恢复期间，在 Gateway 环境里设置OPENCLAW_NO_AUTO_UPDATE=1，防止已启用的自动更新器立刻把新版本重新装回去。

收尾：清理迁移恢复原始文件

验证过新版本、也确认会话历史没问题之后，再退役保留的迁移原始文件。先预览（只读配置和恢复元数据，Gateway 运行时也能跑）：

openclaw update cleanup --dry-run

确认报告中打印的 state 目录就是你预期的那套安装，然后停掉对应 Gateway、等其他 SQLite 维护结束、停掉数据库读取方（包括反复跑openclaw sessions --all-agents --json的 watcher，只读连接也会改动 WAL/SHM 边车并使校验失效），再执行：

openclaw update cleanup

交互确认默认是No；自动化必须显式传--yes（JSON 模式也如此）。注意 cleanup 会永久放弃向这些原始文件回滚的能力，它管理的也不包括包、命令 shim 和 Git 运行时的备份，更不是升级前备份的替代品——所以前面那步备份不能省。

卡住时的排查入口

• 升级状态一直显示 in progress 但 Gateway 健康：确认没有更新还在跑，然后在更新后的安装上执行openclaw update repair和openclaw update status。repair 会核对运行的 Gateway 与已装版本/构建是否一致，然后清理超过 30 分钟不活跃的遗留行，且不需要维护模式或服务重启。
• 完全卡住：在 Gateway 主机终端跑openclaw triage（可用--agent codex指定 agent），它会把本地诊断和记录的失败升级结果交给 coding agent 修复；只收集诊断不启动 agent 用openclaw triage --non-interactive。
• 修复原则文档写得很明确：没通过验证的 Gateway 保持停止，保留已迁移状态；失败的更新即使被修好也保留非零退出码。
• 更多 reason code 和引导式恢复见 Update troubleshooting，通用问题见 Troubleshooting。

边界提醒

• 自动回滚恢复的是代码和被捕获的配置，不是完整状态快照；候选的临时迁移演练快照在验证后会被删除，不能替代备份。
• 容器镜像（Docker/Podman/K8s）的替换走 升级容器镜像 的流程，不在本文范围内。
• 2026.9.2 这类跨越 schema bump 的升级有专门的手动更新命令路径（openclaw gateway stop→ 指定版本安装 →openclaw doctor --fix→openclaw gateway start，逐条成功再执行下一条），细节见 Updating from 2026.9.2 across a schema bump。

【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 🦞项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw