openclaw doctor --fix<\/code><\/a>, OpenClaw tries to repair old Matrix state automatically.
\nBefore any actionable Matrix migration step mutates on-disk state, OpenClaw creates or reuses a focused recovery snapshot.<\/p>\nWhen you use openclaw update<\/code>, the exact trigger depends on how OpenClaw is installed:<\/p>\n\n- source installs run
openclaw doctor --fix<\/code> during the update flow, then restart the gateway by default<\/li>\n- 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<\/li>\n
- if you use
openclaw update --no-restart<\/code>, startup-backed Matrix migration is deferred until you later run openclaw doctor --fix<\/code> and restart the gateway<\/li>\n<\/ul>\nAutomatic migration covers:<\/p>\n
\n- creating or reusing a pre-migration snapshot under
~\/Backups\/openclaw-migrations\/<\/code><\/li>\n- reusing your cached Matrix credentials<\/li>\n
- keeping the same account selection and
channels.matrix<\/code> config<\/li>\n- moving the oldest flat Matrix sync store into the current account-scoped location<\/li>\n
- moving the oldest flat Matrix crypto store into the current account-scoped location when the target account can be resolved safely<\/li>\n
- extracting a previously saved Matrix room-key backup decryption key from the old rust crypto store, when that key exists locally<\/li>\n
- reusing the most complete existing token-hash storage root for the same Matrix account, homeserver, and user when the access token changes later<\/li>\n
- scanning sibling token-hash storage roots for pending encrypted-state restore metadata when the Matrix access token changed but the account\/device identity stayed the same<\/li>\n
- restoring backed-up room keys into the new crypto store on the next Matrix startup<\/li>\n<\/ul>\n
Snapshot details:<\/p>\n
\n- OpenClaw writes a marker file at
~\/.openclaw\/matrix\/migration-snapshot.json<\/code> after a successful snapshot so later startup and repair passes can reuse the same archive.<\/li>\n- These automatic Matrix migration snapshots back up config + state only (
includeWorkspace: false<\/code>).<\/li>\n- If Matrix only has warning-only migration state, for example because
userId<\/code> or accessToken<\/code> is still missing, OpenClaw does not create the snapshot yet because no Matrix mutation is actionable.<\/li>\n- If the snapshot step fails, OpenClaw skips Matrix migration for that run instead of mutating state without a recovery point.<\/li>\n<\/ul>\n
About multi-account upgrades:<\/p>\n
\n- the oldest flat Matrix store (
~\/.openclaw\/matrix\/bot-storage.json<\/code> and ~\/.openclaw\/matrix\/crypto\/<\/code>) came from a single-store layout, so OpenClaw can only migrate it into one resolved Matrix account target<\/li>\n- already account-scoped legacy Matrix stores are detected and prepared per configured Matrix account<\/li>\n<\/ul>\n
What the migration cannot do automatically<\/h2>\n
The previous public Matrix plugin did not<\/strong> 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.<\/p>\nThat means some encrypted installs can only be migrated partially.<\/p>\n
OpenClaw cannot automatically recover:<\/p>\n
\n- local-only room keys that were never backed up<\/li>\n
- encrypted state when the target Matrix account cannot be resolved yet because
homeserver<\/code>, userId<\/code>, or accessToken<\/code> are still unavailable<\/li>\n- automatic migration of one shared flat Matrix store when multiple Matrix accounts are configured but
channels.matrix.defaultAccount<\/code> is not set<\/li>\n- custom plugin path installs that are pinned to a repo path instead of the standard Matrix package<\/li>\n
- a missing recovery key when the old store had backed-up keys but did not keep the decryption key locally<\/li>\n<\/ul>\n
Current warning scope:<\/p>\n
\n- custom Matrix plugin path installs are surfaced by both gateway startup and
openclaw doctor<\/code><\/li>\n<\/ul>\nIf your old installation had local-only encrypted history that was never backed up, some older encrypted messages may remain unreadable after the upgrade.<\/p>\n
推荐 upgrade flow<\/h2>\n\n- \n
Update OpenClaw and the Matrix plugin normally.
\n Prefer plain openclaw update<\/code> without --no-restart<\/code> so startup can finish the Matrix migration immediately.<\/p>\n<\/li>\n- \n
Run:<\/p>\n<\/li>\n<\/ol>\n
bash theme={\"theme\":{\"light\":\"min-light\",\"dark\":\"min-dark\"}}
\n openclaw doctor --fix<\/code><\/p>\nIf Matrix has actionable migration work, doctor will create or reuse the pre-migration snapshot first and print the archive path.<\/p>\n
\n- \n
Start or restart the gateway.<\/p>\n<\/li>\n
- \n
Check current verification and backup state:<\/p>\n<\/li>\n<\/ol>\n
bash theme={\"theme\":{\"light\":\"min-light\",\"dark\":\"min-dark\"}}
\n openclaw matrix verify status
\n openclaw matrix verify backup status<\/code><\/p>\n\n- If OpenClaw tells you a recovery key is needed, run:<\/li>\n<\/ol>\n
bash theme={\"theme\":{\"light\":\"min-light\",\"dark\":\"min-dark\"}}
\n openclaw matrix verify backup restore --recovery-key \"<your-recovery-key>\"<\/code><\/p>\n\n- If this device is still unverified, run:<\/li>\n<\/ol>\n
bash theme={\"theme\":{\"light\":\"min-light\",\"dark\":\"min-dark\"}}
\n openclaw matrix verify device \"<your-recovery-key>\"<\/code><\/p>\n\n- If you are intentionally abandoning unrecoverable old history and want a fresh backup baseline for future messages, run:<\/li>\n<\/ol>\n
bash theme={\"theme\":{\"light\":\"min-light\",\"dark\":\"min-dark\"}}
\n openclaw matrix verify backup reset --yes<\/code><\/p>\n\n- If no server-side key backup exists yet, create one for future recoveries:<\/li>\n<\/ol>\n
bash theme={\"theme\":{\"light\":\"min-light\",\"dark\":\"min-dark\"}}
\n openclaw matrix verify bootstrap<\/code><\/p>\nHow encrypted migration works<\/h2>\n
Encrypted migration is a two-stage process:<\/p>\n
\n- Startup or
openclaw doctor --fix<\/code> creates or reuses the pre-migration snapshot if encrypted migration is actionable.<\/li>\n- Startup or
openclaw doctor --fix<\/code> inspects the old Matrix crypto store through the active Matrix plugin install.<\/li>\n- If a backup decryption key is found, OpenClaw writes it into the new recovery-key flow and marks room-key restore as pending.<\/li>\n
- On the next Matrix startup, OpenClaw restores backed-up room keys into the new crypto store automatically.<\/li>\n<\/ol>\n
If the old store reports room keys that were never backed up, OpenClaw warns instead of pretending recovery succeeded.<\/p>\n
Common messages and what they mean<\/h2>\nUpgrade and detection messages<\/h3>\n
Matrix plugin upgraded in place.<\/code><\/p>\n\n- Meaning: the old on-disk Matrix state was detected and migrated into the current layout.<\/li>\n
- What to do: nothing unless the same output also includes warnings.<\/li>\n<\/ul>\n
Matrix migration snapshot created before applying Matrix upgrades.<\/code><\/p>\n\n- Meaning: OpenClaw created a recovery archive before mutating Matrix state.<\/li>\n
- What to do: keep the printed archive path until you confirm migration succeeded.<\/li>\n<\/ul>\n
Matrix migration snapshot reused before applying Matrix upgrades.<\/code><\/p>\n\n- Meaning: OpenClaw found an existing Matrix migration snapshot marker and reused that archive instead of creating a duplicate backup.<\/li>\n
- What to do: keep the printed archive path until you confirm migration succeeded.<\/li>\n<\/ul>\n
Legacy Matrix state detected at ... but channels.matrix is not configured yet.<\/code><\/p>\n\n- Meaning: old Matrix state exists, but OpenClaw cannot map it to a current Matrix account because Matrix is not configured.<\/li>\n
- What to do: configure
channels.matrix<\/code>, then rerun openclaw doctor --fix<\/code> or restart the gateway.<\/li>\n<\/ul>\nLegacy Matrix state detected at ... but the new account-scoped target could not be resolved yet (need homeserver, userId, and access token for channels.matrix...).<\/code><\/p>\n\n- Meaning: OpenClaw found old state, but it still cannot determine the exact current account\/device root.<\/li>\n
- What to do: start the gateway once with a working Matrix login, or rerun
openclaw doctor --fix<\/code> after cached credentials exist.<\/li>\n<\/ul>\nLegacy Matrix state detected at ... but multiple Matrix accounts are configured and channels.matrix.defaultAccount is not set.<\/code><\/p>\n\n- Meaning: OpenClaw found one shared flat Matrix store, but it refuses to guess which named Matrix account should receive it.<\/li>\n
- What to do: set
channels.matrix.defaultAccount<\/code> to the intended account, then rerun openclaw doctor --fix<\/code> or restart the gateway.<\/li>\n<\/ul>\nMatrix legacy sync store not migrated because the target already exists (...)<\/code><\/p>\n\n- Meaning: the new account-scoped location already has a sync or crypto store, so OpenClaw did not overwrite it automatically.<\/li>\n
- What to do: verify that the current account is the correct one before manually removing or moving the conflicting target.<\/li>\n<\/ul>\n
Failed migrating Matrix legacy sync store (...)<\/code> or Failed migrating Matrix legacy crypto store (...)<\/code><\/p>\n\n- Meaning: OpenClaw tried to move old Matrix state but the filesystem operation failed.<\/li>\n
- What to do: inspect filesystem permissions and disk state, then rerun
openclaw doctor --fix<\/code>.<\/li>\n<\/ul>\nLegacy Matrix encrypted state detected at ... but channels.matrix is not configured yet.<\/code><\/p>\n\n- Meaning: OpenClaw found an old encrypted Matrix store, but there is no current Matrix config to attach it to.<\/li>\n
- What to do: configure
channels.matrix<\/code>, then rerun openclaw doctor --fix<\/code> or restart the gateway.<\/li>\n<\/ul>\nLegacy Matrix encrypted state detected at ... but the account-scoped target could not be resolved yet (need homeserver, userId, and access token for channels.matrix...).<\/code><\/p>\n\n- Meaning: the encrypted store exists, but OpenClaw cannot safely decide which current account\/device it belongs to.<\/li>\n
- What to do: start the gateway once with a working Matrix login, or rerun
openclaw doctor --fix<\/code> after cached credentials are available.<\/li>\n<\/ul>\nLegacy Matrix encrypted state detected at ... but multiple Matrix accounts are configured and channels.matrix.defaultAccount is not set.<\/code><\/p>\n\n- Meaning: OpenClaw found one shared flat legacy crypto store, but it refuses to guess which named Matrix account should receive it.<\/li>\n
- What to do: set
channels.matrix.defaultAccount<\/code> to the intended account, then rerun openclaw doctor --fix<\/code> or restart the gateway.<\/li>\n<\/ul>\nMatrix migration warnings are present, but no on-disk Matrix mutation is actionable yet. No pre-migration snapshot was needed.<\/code><\/p>\n\n- Meaning: OpenClaw detected old Matrix state, but the migration is still blocked on missing identity or credential data.<\/li>\n
- What to do: finish Matrix login or config setup, then rerun
openclaw doctor --fix<\/code> or restart the gateway.<\/li>\n<\/ul>\nLegacy Matrix encrypted state was detected, but the Matrix plugin helper is unavailable. Install or repair @openclaw\/matrix so OpenClaw can inspect the old rust crypto store before upgrading.<\/code><\/p>\n\n- Meaning: OpenClaw found old encrypted Matrix state, but it could not load the helper entrypoint from the Matrix plugin that normally inspects that store.<\/li>\n
- What to do: reinstall or repair the Matrix plugin (
openclaw plugins install @openclaw\/matrix<\/code>, or openclaw plugins install .\/extensions\/matrix<\/code> for a repo checkout), then rerun openclaw doctor --fix<\/code> or restart the gateway.<\/li>\n<\/ul>\nMatrix plugin helper path is unsafe: ... Reinstall @openclaw\/matrix and try again.<\/code><\/p>\n\n- Meaning: OpenClaw found a helper file path that escapes the plugin root or fails plugin boundary checks, so it refused to import it.<\/li>\n
- What to do: reinstall the Matrix plugin from a trusted path, then rerun
openclaw doctor --fix<\/code> or restart the gateway.<\/li>\n<\/ul>\n- Failed creating a Matrix migration snapshot before repair: ...<\/code><\/p>\n- Skipping Matrix migration changes for now. Resolve the snapshot failure, then rerun \"openclaw doctor --fix\".<\/code><\/p>\n\n- Meaning: OpenClaw refused to mutate Matrix state because it could not create the recovery snapshot first.<\/li>\n
- What to do: resolve the backup error, then rerun
openclaw doctor --fix<\/code> or restart the gateway.<\/li>\n<\/ul>\nFailed migrating legacy Matrix client storage: ...<\/code><\/p>\n\n- Meaning: the Matrix client-side fallback found old flat storage, but the move failed. OpenClaw now aborts that fallback instead of silently starting with a fresh store.<\/li>\n
- What to do: inspect filesystem permissions or conflicts, keep the old state intact, and retry after fixing the error.<\/li>\n<\/ul>\n
Matrix is installed from a custom path: ...<\/code><\/p>\n\n- Meaning: Matrix is pinned to a path install, so mainline updates do not automatically replace it with the repo’s standard Matrix package.<\/li>\n
- What to do: reinstall with
openclaw plugins install @openclaw\/matrix<\/code> when you want to return to the default Matrix plugin.<\/li>\n<\/ul>\nEncrypted-state recovery messages<\/h3>\n
matrix: restored X\/Y room key(s) from legacy encrypted-state backup<\/code><\/p>\n\n- Meaning: backed-up room keys were restored successfully into the new crypto store.<\/li>\n
- What to do: usually nothing.<\/li>\n<\/ul>\n
matrix: N legacy local-only room key(s) were never backed up and could not be restored automatically<\/code><\/p>\n\n- Meaning: some old room keys existed only in the old local store and had never been uploaded to Matrix backup.<\/li>\n
- What to do: expect some old encrypted history to remain unavailable unless you can recover those keys manually from another verified client.<\/li>\n<\/ul>\n
Legacy Matrix encrypted state for account \"...\" has backed-up room keys, but no local backup decryption key was found. Ask the operator to run \"openclaw matrix verify backup restore --recovery-key <key>\" after upgrade if they have the recovery key.<\/code><\/p>\n\n- Meaning: backup exists, but OpenClaw could not recover the recovery key automatically.<\/li>\n
- What to do: run
openclaw matrix verify backup restore --recovery-key \"<your-recovery-key>\"<\/code>.<\/li>\n<\/ul>\nFailed inspecting legacy Matrix encrypted state for account \"...\" (...): ...<\/code><\/p>\n\n- Meaning: OpenClaw found the old encrypted store, but it could not inspect it safely enough to prepare recovery.<\/li>\n
- What to do: rerun
openclaw doctor --fix<\/code>. If it repeats, keep the old state directory intact and recover using another verified Matrix client plus openclaw matrix verify backup restore --recovery-key \"<your-recovery-key>\"<\/code>.<\/li>\n<\/ul>\nLegacy Matrix backup key was found for account \"...\", but ...\/recovery-key.json already contains a different recovery key. Leaving the existing file unchanged.<\/code><\/p>\n\n- Meaning: OpenClaw detected a backup key conflict and refused to overwrite the current recovery-key file automatically.<\/li>\n
- What to do: verify which recovery key is correct before retrying any restore command.<\/li>\n<\/ul>\n
Legacy Matrix encrypted state for account \"...\" cannot be fully converted automatically because the old rust crypto store does not expose all local room keys for export.<\/code><\/p>\n\n- Meaning: this is the hard limit of the old storage format.<\/li>\n
- What to do: backed-up keys can still be restored, but local-only encrypted history may remain unavailable.<\/li>\n<\/ul>\n
matrix: failed restoring room keys from legacy encrypted-state backup: ...<\/code><\/p>\n\n- Meaning: the new plugin attempted restore but Matrix returned an error.<\/li>\n
- What to do: run
openclaw matrix verify backup status<\/code>, then retry with openclaw matrix verify backup restore --recovery-key \"<your-recovery-key>\"<\/code> if needed.<\/li>\n<\/ul>\nManual recovery messages<\/h3>\n
Backup key is not loaded on this device. Run 'openclaw matrix verify backup restore' to load it and restore old room keys.<\/code><\/p>\n\n- Meaning: OpenClaw knows you should have a backup key, but it is not active on this device.<\/li>\n
- What to do: run
openclaw matrix verify backup restore<\/code>, or pass --recovery-key<\/code> if needed.<\/li>\n<\/ul>\nStore a recovery key with 'openclaw matrix verify device <key>', then run 'openclaw matrix verify backup restore'.<\/code><\/p>\n\n- Meaning: this device does not currently have the recovery key stored.<\/li>\n
- What to do: verify the device with your recovery key first, then restore the backup.<\/li>\n<\/ul>\n
Backup key mismatch on this device. Re-run 'openclaw matrix verify device <key>' with the matching recovery key.<\/code><\/p>\n\n- Meaning: the stored key does not match the active Matrix backup.<\/li>\n
- What to do: rerun
openclaw matrix verify device \"<your-recovery-key>\"<\/code> with the correct key.<\/li>\n<\/ul>\nIf you accept losing unrecoverable old encrypted history, you can instead reset the current backup baseline with openclaw matrix verify backup reset --yes<\/code>.<\/p>\nBackup trust chain is not verified on this device. Re-run 'openclaw matrix verify device <key>'.<\/code><\/p>\n\n- Meaning: the backup exists, but this device does not trust the cross-signing chain strongly enough yet.<\/li>\n
- What to do: rerun
openclaw matrix verify device \"<your-recovery-key>\"<\/code>.<\/li>\n<\/ul>\nMatrix recovery key is required<\/code><\/p>\n\n- Meaning: you tried a recovery step without supplying a recovery key when one was required.<\/li>\n
- What to do: rerun the command with your recovery key.<\/li>\n<\/ul>\n
Invalid Matrix recovery key: ...<\/code><\/p>\n\n- Meaning: the provided key could not be parsed or did not match the expected format.<\/li>\n
- What to do: retry with the exact recovery key from your Matrix client or recovery-key file.<\/li>\n<\/ul>\n
Matrix device is still unverified after applying recovery key. Verify your recovery key and ensure cross-signing is available.<\/code><\/p>\n\n- Meaning: the key was applied, but the device still could not complete verification.<\/li>\n
- What to do: confirm you used the correct key and that cross-signing is available on the account, then retry.<\/li>\n<\/ul>\n
Matrix key backup is not active on this device after loading from secret storage.<\/code><\/p>\n\n- Meaning: secret storage did not produce an active backup session on this device.<\/li>\n
- What to do: verify the device first, then recheck with
openclaw matrix verify backup status<\/code>.<\/li>\n<\/ul>\n