From 63aafd003d687e04bf4398bbd6f2abb583357bfa Mon Sep 17 00:00:00 2001 From: Hannes Rudolph Date: Wed, 15 Jul 2026 02:29:29 -0600 Subject: [PATCH] docs: explain snapshots and rollback (#108159) --- docs/docs_map.md | 8 ++- docs/install/updating.md | 119 ++++++++++++++++++++++++++++++++++++--- 2 files changed, 116 insertions(+), 11 deletions(-) diff --git a/docs/docs_map.md b/docs/docs_map.md index f322566d0d56..165a2081cb9d 100644 --- a/docs/docs_map.md +++ b/docs/docs_map.md @@ -4710,8 +4710,12 @@ Do not edit it by hand; run `pnpm docs:map:gen`. - H3: Restart the gateway - H3: Verify - H2: Rollback - - H3: Pin a version (npm) - - H3: Pin a commit (source) + - H3: Before updating: create a verified backup + - H3: Roll back a package install + - H3: Roll back a source checkout + - H3: Downgrading across the session SQLite migration + - H3: Restore state only when necessary + - H3: Verify the rollback - H2: If you are stuck - H2: Related diff --git a/docs/install/updating.md b/docs/install/updating.md index e782283d3843..74ca2d0f3d29 100644 --- a/docs/install/updating.md +++ b/docs/install/updating.md @@ -293,29 +293,130 @@ openclaw health ## Rollback -### Pin a version (npm) +Rollback has two layers: + +1. Reinstall older OpenClaw code while keeping the current state. +2. Restore pre-update state only when the older code cannot use a migrated + config or database. + +Start with a code-only rollback. Restoring state discards changes made after +the backup. + +### Before updating: create a verified backup + +`openclaw update` preserves an automatic pre-update config copy, but it does not +create a full state recovery point. Before a significant update, create one +explicitly: ```bash -npm i -g openclaw@ -openclaw doctor +mkdir -p ~/Backups/openclaw +openclaw backup create --output ~/Backups/openclaw --verify +``` + +The archive manifest records the OpenClaw version and the source paths included +in the backup. The archive can contain credentials, auth profiles, and channel +state, so store it with owner-only permissions and the same protection as the +live state directory. See [Backup](/cli/backup) for included and intentionally +omitted files. + +For a byte-for-byte recovery point that includes volatile artifacts omitted by +the portable archive, stop the Gateway and use a filesystem, volume, or VM +snapshot provided by your platform. + +### Roll back a package install + +List published versions, then preview and install the known-good version: + +```bash +npm view openclaw versions --json +openclaw update --tag --dry-run +openclaw update --tag +``` + +`openclaw update --tag` is preferred over a direct package-manager install. It +detects the downgrade, asks for confirmation, runs managed plugin convergence +and compatibility checks against the installed target, refreshes service +metadata, restarts the Gateway, and verifies the running version. If the stored +channel is `extended-stable`, use +`--channel stable --tag ` because exact one-off tags cannot +be combined with the `extended-stable` selector. + +Package updates stage and verify the candidate before activation. If the +filesystem swap or command-shim replacement fails, OpenClaw restores the old +package automatically. After a successful swap, a later Gateway health failure +reports the previous version and manual rollback instructions instead of +automatically replacing the package again. + +If the CLI update path is unavailable, use the same package manager and install +scope that own the current Gateway: + +```bash +openclaw gateway stop +npm i -g openclaw@ +openclaw gateway install --force openclaw gateway restart ``` - -`npm view openclaw version` shows the current published version. - +Replace `npm` with `pnpm` or `bun` when that manager owns the install. During +incident recovery, prevent an enabled auto-updater from immediately applying a +newer release by setting `OPENCLAW_NO_AUTO_UPDATE=1` in the Gateway environment. -### Pin a commit (source) +### Roll back a source checkout + +Use a clean checkout and select a known-good tag or commit: ```bash -git fetch origin -git checkout "$(git rev-list -n 1 --before=\"2026-01-01\" origin/main)" +git fetch --all --tags +git checkout --detach pnpm install && pnpm build openclaw gateway restart ``` To return to latest: `git checkout main && git pull`. +The updater automatically returns a git checkout to its previous branch and +SHA when dependency installation, build, UI build, or doctor fails after a git +update starts. Manual checkout is still required when you intentionally choose +an older commit. + +### Downgrading across the session SQLite migration + +Before starting an older file-backed OpenClaw release, use the current CLI to +restore archived legacy transcript artifacts: + +```bash +openclaw gateway stop +openclaw doctor --session-sqlite restore --session-sqlite-all-agents +``` + +This does not delete SQLite data. Sessions created after the SQLite migration +exist only in SQLite and will not appear to the older runtime. See +[Downgrading after session SQLite migration](/cli/doctor#downgrading-after-session-sqlite-migration). + +### Restore state only when necessary + +If the older code cannot read a newer config or database schema, stop the +Gateway and restore the verified pre-update filesystem, volume, or VM snapshot. +Preserve the current state separately before restoring because this removes +changes made after the snapshot. + +Broad `openclaw backup create` archives support creation and verification, but +not in-place whole-archive activation. Extract a broad archive into a staging +directory and use its `manifest.json` source-to-archive mapping for an offline +restore. `openclaw backup sqlite restore` likewise writes a verified database +to a fresh target; activating that target remains an explicit offline operator +step. + +### Verify the rollback + +```bash +openclaw --version +openclaw health +openclaw plugins list --json +openclaw gateway status --deep --json +openclaw doctor --lint --json +``` + ## If you are stuck - Run `openclaw doctor` again and read the output carefully.