Upgrade OpenClaw Matrix Plugin: Automatic Migration Guide

What the migration does automatically

When your gateway starts or when you run openclaw doctor --fix, OpenClaw works to repair your old Matrix state. Before the system changes any files on your disk, it creates or reuses a recovery snapshot to keep your data safe.

The way openclaw update triggers this depends on your installation:

• Source installs run openclaw doctor --fix during the update flow.
• These source installs then restart the gateway by default.
• Package-manager installs update the package and run a non-interactive doctor pass, then wait for a restart to finish the job.
• If you use openclaw update --no-restart, the migration stays pending until you run the doctor command and restart manually.

The automatic migration handles these tasks:

• Creating or reusing a pre-migration snapshot in ~/Backups/openclaw-migrations/.
• Reusing your cached Matrix credentials.
• Keeping the same account selection and channels.matrix config.
• Moving the oldest flat Matrix sync store into the current account-scoped location.
• Moving the oldest flat Matrix crypto store into the current account-scoped location when the target account can be resolved safely.
• Extracting a previously saved Matrix room-key backup decryption key from the old rust crypto store, when that key exists locally.
• Reusing the most complete existing token-hash storage root for the same Matrix account, homeserver, and user when the access token changes later.
• 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.
• Restoring backed-up room keys into the new crypto store on the next Matrix startup.

Here are the details on how snapshots work:

• OpenClaw writes a marker file at ~/.openclaw/matrix/migration-snapshot.json after a successful snapshot so later startup and repair passes can reuse the same archive.
• These automatic Matrix migration snapshots back up config + state only (includeWorkspace: false).
• If Matrix only has warning-only migration state, for example because userId or accessToken is still missing, OpenClaw does not create the snapshot yet because no Matrix mutation is actionable.
• If the snapshot step fails, OpenClaw skips Matrix migration for that run instead of mutating state without a recovery point.

If you use multiple accounts:

• 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 Matrix plugin did not automatically create Matrix room-key backups. It saved local crypto state and requested device verification, but it did not guarantee that your room keys were backed up to the homeserver.

Because of this, some encrypted installations can only be migrated partially.

OpenClaw cannot automatically recover:

• Local-only room keys that were never backed up.
• Encrypted state when the target Matrix account cannot be resolved yet because homeserver, userId, or accessToken are still unavailable.
• Automatic migration of one shared flat Matrix store when multiple Matrix accounts are configured but channels.matrix.defaultAccount is not set.
• Custom plugin path installs that are pinned to a repo path instead of the standard Matrix package.
• A missing recovery key when the old store had backed-up keys but did not keep the decryption key locally.

Regarding warnings:

• Custom Matrix plugin path installs are surfaced by both gateway startup and openclaw doctor.
• 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

Updating your setup is straightforward if you follow these steps. First, update OpenClaw and the Matrix plugin as you normally would. It is better to use the standard update command:

openclaw update

You should avoid using the --no-restart flag. This allows the startup process to finish the Matrix migration immediately.

Next, you need to run the doctor tool to handle the heavy lifting:

openclaw doctor --fix

If the Matrix plugin has migration work to do, the doctor will create or reuse a pre-migration snapshot and print the archive path for you.

After that, start or restart your gateway. You can then check the current state of your verification and backups using these commands:

openclaw matrix verify status
openclaw matrix verify backup status

If OpenClaw tells you that a recovery key is required, run this command:

openclaw matrix verify backup restore --recovery-key "<your-recovery-key>"

If your device still shows as unverified, you can fix it by running:

openclaw matrix verify device "<your-recovery-key>"

In cases where you want to abandon old history that cannot be recovered and start a fresh backup baseline for future messages, run:

openclaw matrix verify backup reset --yes

Finally, if no server-side key backup exists yet, you should create one to help with future recoveries:

openclaw matrix verify bootstrap

How encrypted migration works

The encrypted migration is a two-stage process designed to keep your keys safe.

First, either the system startup or the openclaw doctor --fix command creates or reuses a pre-migration snapshot. This only happens if the encrypted migration is actually ready to run. The process then inspects your old Matrix crypto store through the active Matrix plugin installation.

If a backup decryption key is found, OpenClaw writes it into the new recovery-key flow and marks the room-key restore as a pending task. On the next Matrix startup, OpenClaw automatically restores those backed-up room keys into your new crypto store.

If the old store reports room keys that were never backed up, OpenClaw will give you a warning. It won’t pretend the recovery succeeded if the keys are missing.

Common messages and what they mean

Upgrade and detection messages

Matrix plugin upgraded in place.

• Meaning: OpenClaw found your old on-disk Matrix state and moved it into the new layout.
• What to do: You don’t need to do anything unless you see warnings in the same output.

Matrix migration snapshot created before applying Matrix upgrades.

• Meaning: OpenClaw made a recovery archive before changing any Matrix state.
• What to do: Keep the printed archive path until you are sure the migration worked.

Matrix migration snapshot reused before applying Matrix upgrades.

• Meaning: OpenClaw found an existing migration marker and used that archive instead of making a duplicate.
• What to do: Keep the printed archive path until you confirm the migration succeeded.

Legacy Matrix state detected at ... but channels.matrix is not configured yet.

• Meaning: Old Matrix data exists, but OpenClaw can’t link it to an account because Matrix isn’t configured.
• What to do: Configure channels.matrix, then run openclaw doctor --fix or restart the gateway.

Legacy Matrix state detected at ... but the new account-scoped target could not be resolved yet (need homeserver, userId, and access token for channels.matrix...).

• Meaning: OpenClaw found old data, but it can’t determine the exact account or device root yet.
• What to do: Start the gateway once with a working Matrix login, or run openclaw doctor --fix after your credentials exist in the cache.

Legacy Matrix state detected at ... but multiple Matrix accounts are configured and channels.matrix.defaultAccount is not set.

• Meaning: OpenClaw found one old Matrix store, but it won’t guess which of your named accounts should receive it.
• What to do: Set channels.matrix.defaultAccount to the right account, then run openclaw doctor --fix or restart.

Matrix legacy sync store not migrated because the target already exists (...)

• Meaning: The new account-scoped location already has a store, so OpenClaw didn’t overwrite it.
• What to do: Check that the current account is correct before you manually remove or move the conflicting files.

Failed migrating Matrix legacy sync store (...) or Failed migrating Matrix legacy crypto store (...)

• Meaning: OpenClaw tried to move the old state but the filesystem operation failed.
• What to do: Check your filesystem permissions and disk state, then run openclaw doctor --fix again.

Legacy Matrix encrypted state detected at ... but channels.matrix is not configured yet.

• Meaning: OpenClaw found an old encrypted store, but there is no Matrix config to attach it to.
• What to do: Configure channels.matrix, then run openclaw doctor --fix or restart.

Legacy Matrix encrypted state detected at ... but the account-scoped target could not be resolved yet (need homeserver, userId, and access token for channels.matrix...).

• Meaning: The encrypted store exists, but OpenClaw can’t safely decide which account it belongs to.
• What to do: Start the gateway once with a working Matrix login, or run openclaw doctor --fix after credentials are available.

Legacy Matrix encrypted state detected at ... but multiple Matrix accounts are configured and channels.matrix.defaultAccount is not set.

• Meaning: OpenClaw found one old crypto store, but it won’t guess which account should get it.
• What to do: Set channels.matrix.defaultAccount to the intended account, then run openclaw doctor --fix.

Matrix migration warnings are present, but no on-disk Matrix mutation is actionable yet. No pre-migration snapshot was needed.

• Meaning: OpenClaw detected old state, but the migration is blocked by missing identity or credential data.
• What to do: Finish your Matrix login or config, then run openclaw doctor --fix or restart.

Legacy 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.

• Meaning: OpenClaw found old encrypted state, but it couldn’t load the helper from the Matrix plugin to inspect it.
• What to do: Reinstall or repair the Matrix plugin with openclaw plugins install @openclaw/matrix (or use the local path for a repo checkout), then run openclaw doctor --fix.

Matrix plugin helper path is unsafe: ... Reinstall @openclaw/matrix and try again.

• Meaning: OpenClaw found a helper path that failed security checks, so it refused to import it.
• What to do: Reinstall the Matrix plugin from a trusted path, then run openclaw doctor --fix.

- Failed creating a Matrix migration snapshot before repair: ...

- Skipping Matrix migration changes for now. Resolve the snapshot failure, then rerun "openclaw doctor --fix".

• Meaning: OpenClaw refused to change the Matrix state because it couldn’t create a recovery backup first.
• What to do: Fix the backup error, then run openclaw doctor --fix or restart.

Failed migrating legacy Matrix client storage: ...

• Meaning: The move for the old flat storage failed. OpenClaw stops the fallback instead of starting with a fresh store.
• What to do: Check filesystem permissions or conflicts, keep the old state, and try again after fixing the error.

Matrix is installed from a custom path: ...

• Meaning: Matrix is pinned to a specific path, so standard updates won’t replace it automatically.
• What to do: Reinstall with openclaw plugins install @openclaw/matrix if you want to go back to the standard package.

Encrypted-state recovery messages

matrix: restored X/Y room key(s) from legacy encrypted-state backup

• Meaning: Your backed-up room keys were moved successfully into the new crypto store.
• What to do: You usually don’t need to do anything.

matrix: N legacy local-only room key(s) were never backed up and could not be restored automatically

• Meaning: Some old keys only existed in your local store and were never uploaded to the Matrix backup.
• What to do: Some old history might stay unavailable unless you can recover those keys from another verified client.

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.

• Meaning: A backup exists, but OpenClaw couldn’t recover the key automatically.
• What to do: Run openclaw matrix verify backup restore --recovery-key "<your-recovery-key>".

Failed inspecting legacy Matrix encrypted state for account "..." (...): ...

• Meaning: OpenClaw found the old store but couldn’t check it safely to prepare for recovery.
• What to do: Run openclaw doctor --fix. If it keeps happening, keep the old directory and recover using another client plus openclaw matrix verify backup restore --recovery-key "<your-recovery-key>".

Legacy Matrix backup key was found for account "...", but .../recovery-key.json already contains a different recovery key. Leaving the existing file unchanged.

• Meaning: OpenClaw found a key conflict and didn’t want to overwrite your current recovery-key file.
• What to do: Check which recovery key is correct before you try any restore command.

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.

• Meaning: This is a hard limit of the old storage format.
• What to do: Backed-up keys can be restored, but local-only history might stay unavailable.

matrix: failed restoring room keys from legacy encrypted-state backup: ...

• Meaning: The new plugin tried a restore but Matrix returned an error.
• What to do: Run openclaw matrix verify backup status, then retry with openclaw matrix verify backup restore --recovery-key "<your-recovery-key>".

Manual recovery messages

Backup key is not loaded on this device. Run 'openclaw matrix verify backup restore' to load it and restore old room keys.

• Meaning: OpenClaw knows you have a backup key, but it isn’t active on this device.
• What to do: Run openclaw matrix verify backup restore, and pass --recovery-key if you need to.

Store a recovery key with 'openclaw matrix verify device <key>', then run 'openclaw matrix verify backup restore'.

• Meaning: This device doesn’t have the recovery key stored yet.
• What to do: Verify the device with your recovery key first, then run the restore.

Backup key mismatch on this device. Re-run 'openclaw matrix verify device <key>' with the matching recovery key.

• Meaning: The stored key doesn’t match the active Matrix backup.
• What to do: Run openclaw matrix verify device "<your-recovery-key>" again with the right key. If you are okay with losing old history, you can reset the backup with openclaw matrix verify backup reset --yes.

Backup trust chain is not verified on this device. Re-run 'openclaw matrix verify device <key>'.

• Meaning: The backup exists, but the device doesn’t trust the cross-signing chain enough yet.
• What to do: Run openclaw matrix verify device "<your-recovery-key>" again.

Matrix recovery key is required

• Meaning: You tried a recovery step but didn’t provide the required recovery key.
• What to do: Run the command again and include your recovery key.

Invalid Matrix recovery key: ...

• Meaning: The key you provided couldn’t be parsed or is in the wrong format.
• What to do: Try again with the exact key from your Matrix client or your recovery-key file.

Matrix device is still unverified after applying recovery key. Verify your recovery key and ensure cross-signing is available.

• Meaning: The key was applied, but the device couldn’t finish verification.
• What to do: Confirm the key is correct and that cross-signing is active on the account, then try again.

Matrix key backup is not active on this device after loading from secret storage.

• Meaning: Secret storage didn’t result in an active backup session here.
• What to do: Verify the device first, then check again with openclaw matrix verify backup status.

Matrix crypto backend cannot load backup keys from secret storage. Verify this device with 'openclaw matrix verify device <key>' first.

• Meaning: This device can’t restore from secret storage until it is verified.
• What to do: Run openclaw matrix verify device "<your-recovery-key>" first.

Custom plugin install messages

Matrix is installed from a custom path that no longer exists: ...

• Meaning: Your plugin record points to a local path that is gone.
• What to do: Reinstall with openclaw plugins install @openclaw/matrix, or use the local path if you are using a repo checkout.

If encrypted history still does not come back

Run these checks in order:

openclaw matrix verify status --verbose
openclaw matrix verify backup status --verbose
openclaw matrix verify backup restore --recovery-key "<your-recovery-key>" --verbose

If the backup restores but some old rooms still miss history, those keys were likely never backed up by the previous plugin.

AI Setup Assistant

If you want to start fresh for future messages

If you’re okay with losing old encrypted history that can’t be recovered and you just want a clean backup baseline for your future messages, run these commands in order:

openclaw matrix verify backup reset --yes
openclaw matrix verify backup status --verbose
openclaw matrix verify status

If your device is still unverified after that, finish the verification from your Matrix client. You can do this by comparing the SAS emoji or decimal codes and confirming that they match.

Related pages

You might want to look at these other guides to help with your project. They cover specific topics that will help you get everything running correctly.

If you are setting up communication, check out the Matrix page. It gives you the details on how that channel works.

When you need to check your system health, the Doctor tool is what you need. It finds errors in your setup so you can fix them quickly.

If you are moving your data or changing your environment, the Migrating guide shows you the right steps to take.

To add more features, visit the Plugins section. It explains how to use extra tools to make your setup do more.