From 3d7e7d357bf5885b95e06341b013ec908d3d2789 Mon Sep 17 00:00:00 2001 From: Gustavo Madeira Santana Date: Sun, 8 Mar 2026 22:07:41 -0400 Subject: [PATCH] Docs: clarify Matrix migration update flow --- docs/cli/update.md | 13 ++++++++++++- docs/install/migrating-matrix.md | 17 +++++++++++++++++ docs/install/updating.md | 13 +++++++++++-- 3 files changed, 40 insertions(+), 3 deletions(-) diff --git a/docs/cli/update.md b/docs/cli/update.md index d1c61518b0c..c6f681a63c5 100644 --- a/docs/cli/update.md +++ b/docs/cli/update.md @@ -71,6 +71,8 @@ install method aligned: The Gateway core auto-updater (when enabled via config) reuses this same update path. +By default, `openclaw update` also restarts the gateway after the core and plugin update finishes. That matters for migrations that complete on startup, including the Matrix in-place upgrade flow. + ## Git checkout flow Channels: @@ -88,9 +90,18 @@ High-level: 5. Rebases onto the selected commit (dev only). 6. Installs deps (pnpm preferred; npm fallback). 7. Builds + builds the Control UI. -8. Runs `openclaw doctor` as the final “safe update” check. +8. Runs `openclaw doctor --fix` as the final “safe update” check. 9. Syncs plugins to the active channel (dev uses bundled extensions; stable/beta uses npm) and updates npm-installed plugins. +For package-manager installs, `openclaw update` updates the package, runs a non-interactive doctor pass when possible, syncs plugins, and restarts the gateway by default. + +If you use `--no-restart`, startup-backed migrations do not finish until you later restart the gateway yourself. For Matrix upgrades, the recommended follow-up is: + +```bash +openclaw doctor --fix +openclaw gateway restart +``` + ## `--update` shorthand `openclaw --update` rewrites to `openclaw update` (useful for shells and launcher scripts). diff --git a/docs/install/migrating-matrix.md b/docs/install/migrating-matrix.md index e0901bd1a7c..62352236e81 100644 --- a/docs/install/migrating-matrix.md +++ b/docs/install/migrating-matrix.md @@ -24,6 +24,12 @@ You do not need to rename config keys or reinstall the plugin under a new name. When the gateway starts, and when you run [`openclaw doctor --fix`](/gateway/doctor), OpenClaw tries to repair old Matrix state automatically. +When you use `openclaw update`, the exact trigger depends on how OpenClaw is installed: + +- source installs run `openclaw doctor --fix` during the update flow, then restart the gateway by default +- package-manager installs update the package, run a non-interactive doctor pass, then rely on the default gateway restart so startup can finish Matrix migration +- if you use `openclaw update --no-restart`, startup-backed Matrix migration is deferred until you later run `openclaw doctor --fix` and restart the gateway + Automatic migration covers: - reusing your cached Matrix credentials @@ -33,6 +39,11 @@ Automatic migration covers: - extracting a previously saved Matrix room-key backup decryption key from the old rust crypto store, when that key exists locally - restoring backed-up room keys into the new crypto store on the next Matrix startup +About multi-account upgrades: + +- the oldest flat Matrix store (`~/.openclaw/matrix/bot-storage.json` and `~/.openclaw/matrix/crypto/`) came from a single-store layout, so OpenClaw can only migrate it into one resolved Matrix account target +- already account-scoped legacy Matrix stores are detected and prepared per configured Matrix account + ## What the migration cannot do automatically The previous public Matrix plugin did **not** automatically create Matrix room-key backups. It persisted local crypto state and requested device verification, but it did not guarantee that your room keys were backed up to the homeserver. @@ -46,11 +57,17 @@ OpenClaw cannot automatically recover: - custom plugin path installs that now point at a missing directory - a missing recovery key when the old store had backed-up keys but did not keep the decryption key locally +Current warning scope: + +- stale custom Matrix plugin path installs are surfaced by `openclaw doctor` today +- gateway startup does not currently emit a separate Matrix-specific custom-path warning + If your old installation had local-only encrypted history that was never backed up, some older encrypted messages may remain unreadable after the upgrade. ## Recommended upgrade flow 1. Update OpenClaw and the Matrix plugin normally. + Prefer plain `openclaw update` without `--no-restart` so startup can finish the Matrix migration immediately. 2. Run: ```bash diff --git a/docs/install/updating.md b/docs/install/updating.md index dd3128c553e..336a3983158 100644 --- a/docs/install/updating.md +++ b/docs/install/updating.md @@ -141,10 +141,19 @@ It runs a safe-ish update flow: - Requires a clean worktree. - Switches to the selected channel (tag or branch). - Fetches + rebases against the configured upstream (dev channel). -- Installs deps, builds, builds the Control UI, and runs `openclaw doctor`. +- Installs deps, builds, builds the Control UI, and runs `openclaw doctor --fix`. - Restarts the gateway by default (use `--no-restart` to skip). -If you installed via **npm/pnpm** (no git metadata), `openclaw update` will try to update via your package manager. If it can’t detect the install, use “Update (global install)” instead. +That default restart matters for migrations that complete on startup. If you skip restart, run: + +```bash +openclaw doctor --fix +openclaw gateway restart +``` + +For Matrix upgrades specifically, startup is what finishes the in-place Matrix state migration and any pending backed-up room-key restore. See [Matrix migration](/install/migrating-matrix). + +If you installed via **npm/pnpm** (no git metadata), `openclaw update` will try to update via your package manager, run a non-interactive doctor pass when possible, and restart the gateway by default. If it can’t detect the install, use “Update (global install)” instead. ## Update (Control UI / RPC)