Matrix migration

Upgrade from the previous public

plugin to the current implementation.

For most users, the upgrade is in place:

• the plugin stays
  text

  Copy

  @openclaw/matrix
• the channel stays
  text

  Copy

  matrix
• your config stays under
  text

  Copy

  channels.matrix
• cached credentials stay under
  text

  Copy

  ~/.openclaw/credentials/matrix/
• runtime state stays under
  text

  Copy

  ~/.openclaw/matrix/

You do not need to rename config keys or reinstall the plugin under a new name.

What the migration does automatically

When the gateway starts, and when you run

, OpenClaw tries to repair old Matrix state automatically. Before any actionable Matrix migration step mutates on-disk state, OpenClaw creates or reuses a focused recovery snapshot.

When you use

, the exact trigger depends on how OpenClaw is installed:

• source installs run
  text

  Copy

  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
  text

  Copy

  openclaw update --no-restart
  , startup-backed Matrix migration is deferred until you later run
  text

  Copy

  openclaw doctor --fix
  and restart the gateway

Automatic migration covers:

• creating or reusing a pre-migration snapshot under
  text

  Copy

  ~/Backups/openclaw-migrations/
• reusing your cached Matrix credentials
• keeping the same account selection and
  text

  Copy

  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

Snapshot details:

• OpenClaw writes a marker file at
  text

  Copy

  ~/.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 (
  text

  Copy

  includeWorkspace: false
  ).
• If Matrix only has warning-only migration state, for example because
  text

  Copy

  userId
  or
  text

  Copy

  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.

About multi-account upgrades:

• the oldest flat Matrix store (
  text

  Copy

  ~/.openclaw/matrix/bot-storage.json
  and
  text

  Copy

  ~/.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.

That means some encrypted installs 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
  text

  Copy

  homeserver
  ,
  text

  Copy

  userId
  , or
  text

  Copy

  accessToken
  are still unavailable
• automatic migration of one shared flat Matrix store when multiple Matrix accounts are configured but
  text

  Copy

  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

Current warning scope:

• custom Matrix plugin path installs are surfaced by both gateway startup and
  text

  Copy

  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

1. Update OpenClaw and the Matrix plugin normally. Prefer plain

   text

   Copy

   openclaw update
   without
   text

   Copy

   --no-restart
   so startup can finish the Matrix migration immediately.

2. Run:

   bash
   Copy
   openclaw doctor --fix
   

   If Matrix has actionable migration work, doctor will create or reuse the pre-migration snapshot first and print the archive path.

3. Start or restart the gateway.

4. Check current verification and backup state:

   bash
   Copy
   openclaw matrix verify status
   openclaw matrix verify backup status
   

5. Put the recovery key for the Matrix account you are repairing in an account-specific environment variable. For a single default account,

   text

   Copy

   MATRIX_RECOVERY_KEY
   is fine. For multiple accounts, use one variable per account, for example
   text

   Copy

   MATRIX_RECOVERY_KEY_ASSISTANT
   , and add
   text

   Copy

   --account assistant
   to the command.

6. If OpenClaw tells you a recovery key is needed, run the command for the matching account:

   bash
   Copy
   printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin
   printf '%s\n' "$MATRIX_RECOVERY_KEY_ASSISTANT" | openclaw matrix verify backup restore --recovery-key-stdin --account assistant
   

7. If this device is still unverified, run the command for the matching account:

   bash
   Copy
   printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin
   printf '%s\n' "$MATRIX_RECOVERY_KEY_ASSISTANT" | openclaw matrix verify device --recovery-key-stdin --account assistant
   

   If the recovery key is accepted and backup is usable, but

   text

   Copy

   Cross-signing verified
   is still
   text

   Copy

   no
   , complete self-verification from another Matrix client:

   bash
   Copy
   openclaw matrix verify self
   

   Accept the request in another Matrix client, compare the emoji or decimals, and type

   text

   Copy

   yes
   only when they match. The command exits successfully only after
   text

   Copy

   Cross-signing verified
   becomes
   text

   Copy

   yes
   .

8. If you are intentionally abandoning unrecoverable old history and want a fresh backup baseline for future messages, run:

   bash
   Copy
   openclaw matrix verify backup reset --yes
   

9. If no server-side key backup exists yet, create one for future recoveries:

   bash
   Copy
   openclaw matrix verify bootstrap
   

How encrypted migration works

Encrypted migration is a two-stage process:

1. Startup or
   text

   Copy

   openclaw doctor --fix
   creates or reuses the pre-migration snapshot if encrypted migration is actionable.
2. Startup or
   text

   Copy

   openclaw doctor --fix
   inspects the old Matrix crypto store through the active Matrix plugin install.
3. If a backup decryption key is found, OpenClaw writes it into the new recovery-key flow and marks room-key restore as pending.
4. On the next Matrix startup, OpenClaw restores backed-up room keys into the new crypto store automatically.

If the old store reports room keys that were never backed up, OpenClaw warns instead of pretending recovery succeeded.

Common messages and what they mean

Upgrade and detection messages

• Meaning: the old on-disk Matrix state was detected and migrated into the current layout.
• What to do: nothing unless the same output also includes warnings.

• Meaning: OpenClaw created a recovery archive before mutating Matrix state.
• What to do: keep the printed archive path until you confirm migration succeeded.

• Meaning: OpenClaw found an existing Matrix migration snapshot marker and reused that archive instead of creating a duplicate backup.
• What to do: keep the printed archive path until you confirm migration succeeded.

• Meaning: old Matrix state exists, but OpenClaw cannot map it to a current Matrix account because Matrix is not configured.
• What to do: configure
  text

  Copy

  channels.matrix
  , then rerun
  text

  Copy

  openclaw doctor --fix
  or restart the gateway.

• Meaning: OpenClaw found old state, but it still cannot determine the exact current account/device root.
• What to do: start the gateway once with a working Matrix login, or rerun
  text

  Copy

  openclaw doctor --fix
  after cached credentials exist.

• Meaning: OpenClaw found one shared flat Matrix store, but it refuses to guess which named Matrix account should receive it.
• What to do: set
  text

  Copy

  channels.matrix.defaultAccount
  to the intended account, then rerun
  text

  Copy

  openclaw doctor --fix
  or restart the gateway.

• Meaning: the new account-scoped location already has a sync or crypto store, so OpenClaw did not overwrite it automatically.
• What to do: verify that the current account is the correct one before manually removing or moving the conflicting target.

or

• Meaning: OpenClaw tried to move old Matrix state but the filesystem operation failed.
• What to do: inspect filesystem permissions and disk state, then rerun
  text

  Copy

  openclaw doctor --fix
  .

• Meaning: OpenClaw found an old encrypted Matrix store, but there is no current Matrix config to attach it to.
• What to do: configure
  text

  Copy

  channels.matrix
  , then rerun
  text

  Copy

  openclaw doctor --fix
  or restart the gateway.

• Meaning: the encrypted store exists, but OpenClaw cannot safely decide which current account/device it belongs to.
• What to do: start the gateway once with a working Matrix login, or rerun
  text

  Copy

  openclaw doctor --fix
  after cached credentials are available.

• Meaning: OpenClaw found one shared flat legacy crypto store, but it refuses to guess which named Matrix account should receive it.
• What to do: set
  text

  Copy

  channels.matrix.defaultAccount
  to the intended account, then rerun
  text

  Copy

  openclaw doctor --fix
  or restart the gateway.

• Meaning: OpenClaw detected old Matrix state, but the migration is still blocked on missing identity or credential data.
• What to do: finish Matrix login or config setup, then rerun
  text

  Copy

  openclaw doctor --fix
  or restart the gateway.

• Meaning: OpenClaw found old encrypted Matrix state, but it could not load the helper entrypoint from the Matrix plugin that normally inspects that store.
• What to do: reinstall or repair the Matrix plugin (
  text

  Copy

  openclaw plugins install @openclaw/matrix
  , or
  text

  Copy

  openclaw plugins install ./path/to/local/matrix-plugin
  for a repo checkout), then rerun
  text

  Copy

  openclaw doctor --fix
  or restart the gateway.
• If npm reports the OpenClaw-owned Matrix package as deprecated, use the bundled plugin from a current packaged OpenClaw build or the local checkout path until a newer npm package is published.

• Meaning: OpenClaw found a helper file path that escapes the plugin root or fails plugin boundary checks, so it refused to import it.
• What to do: reinstall the Matrix plugin from a trusted path, then rerun
  text

  Copy

  openclaw doctor --fix
  or restart the gateway.

• Meaning: OpenClaw refused to mutate Matrix state because it could not create the recovery snapshot first.
• What to do: resolve the backup error, then rerun
  text

  Copy

  openclaw doctor --fix
  or restart the gateway.

• 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.
• What to do: inspect filesystem permissions or conflicts, keep the old state intact, and retry after fixing the error.

• Meaning: Matrix is pinned to a path install, so mainline updates do not automatically replace it with the repo's standard Matrix package.
• What to do: reinstall with
  text

  Copy

  openclaw plugins install @openclaw/matrix
  when you want to return to the default Matrix plugin.
• If npm reports the OpenClaw-owned Matrix package as deprecated, use the bundled plugin from a current packaged OpenClaw build until a newer npm package is published.

Encrypted-state recovery messages

• Meaning: backed-up room keys were restored successfully into the new crypto store.
• What to do: usually nothing.

• Meaning: some old room keys existed only in the old local store and had never been uploaded to Matrix backup.
• What to do: expect some old encrypted history to remain unavailable unless you can recover those keys manually from another verified client.

• Meaning: backup exists, but OpenClaw could not recover the recovery key automatically.
• What to do: run
  text

  Copy

  printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin
  .

• Meaning: OpenClaw found the old encrypted store, but it could not inspect it safely enough to prepare recovery.
• What to do: rerun
  text

  Copy

  openclaw doctor --fix
  . If it repeats, keep the old state directory intact and recover using another verified Matrix client plus
  text

  Copy

  printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin
  .

• Meaning: OpenClaw detected a backup key conflict and refused to overwrite the current recovery-key file automatically.
• What to do: verify which recovery key is correct before retrying any restore command.

• Meaning: this is the hard limit of the old storage format.
• What to do: backed-up keys can still be restored, but local-only encrypted history may remain unavailable.

• Meaning: the new plugin attempted restore but Matrix returned an error.
• What to do: run
  text

  Copy

  openclaw matrix verify backup status
  , then retry with
  text

  Copy

  printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin
  if needed.

Manual recovery messages

• Meaning: OpenClaw knows you should have a backup key, but it is not active on this device.
• What to do: run
  text

  Copy

  openclaw matrix verify backup restore
  , or set
  text

  Copy

  MATRIX_RECOVERY_KEY
  and run
  text

  Copy

  printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin
  if needed.

• Meaning: this device does not currently have the recovery key stored.
• What to do: set
  text

  Copy

  MATRIX_RECOVERY_KEY
  , run
  text

  Copy

  printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin
  , then restore the backup.

• Meaning: the stored key does not match the active Matrix backup.
• What to do: set
  text

  Copy

  MATRIX_RECOVERY_KEY
  to the correct key and run
  text

  Copy

  printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin
  .

If you accept losing unrecoverable old encrypted history, you can instead reset the current backup baseline with

. When the stored backup secret is broken, that reset may also recreate secret storage so the new backup key can load correctly after restart.

• Meaning: the backup exists, but this device does not trust the cross-signing chain strongly enough yet.
• What to do: set
  text

  Copy

  MATRIX_RECOVERY_KEY
  and run
  text

  Copy

  printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin
  .

• Meaning: you tried a recovery step without supplying a recovery key when one was required.
• What to do: rerun the command with
  text

  Copy

  --recovery-key-stdin
  , for example
  text

  Copy

  printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin
  .

• Meaning: the provided key could not be parsed or did not match the expected format.
• What to do: retry with the exact recovery key from your Matrix client or recovery-key file.

• Meaning: OpenClaw could apply the recovery key, but Matrix still has not established full cross-signing identity trust for this device. Check the command output for
  text

  Copy

  Recovery key accepted
  ,
  text

  Copy

  Backup usable
  ,
  text

  Copy

  Cross-signing verified
  , and
  text

  Copy

  Device verified by owner
  .
• What to do: run
  text

  Copy

  openclaw matrix verify self
  , accept the request in another Matrix client, compare the SAS, and type
  text

  Copy

  yes
  only when it matches. The command waits for full Matrix identity trust before reporting success. Use
  text

  Copy

  printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify bootstrap --recovery-key-stdin --force-reset-cross-signing
  only when you intentionally want to replace the current cross-signing identity.

• Meaning: secret storage did not produce an active backup session on this device.
• What to do: verify the device first, then recheck with
  text

  Copy

  openclaw matrix verify backup status
  .

• Meaning: this device cannot restore from secret storage until device verification is complete.
• What to do: run
  text

  Copy

  printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin
  first.

Custom plugin install messages

• Meaning: your plugin install record points at a local path that is gone.
• What to do: reinstall with
  text

  Copy

  openclaw plugins install @openclaw/matrix
  , or if you are running from a repo checkout,
  text

  Copy

  openclaw plugins install ./path/to/local/matrix-plugin
  .
• If npm reports the OpenClaw-owned Matrix package as deprecated, use the bundled plugin from a current packaged OpenClaw build or the local checkout path until a newer npm package is published.

If encrypted history still does not come back

Run these checks in order:

bash
Copy
openclaw matrix verify status --verbose
openclaw matrix verify backup status --verbose
printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin --verbose

If the backup restores successfully but some old rooms are still missing history, those missing keys were probably never backed up by the previous plugin.

If you want to start fresh for future messages

If you accept losing unrecoverable old encrypted history and only want a clean backup baseline going forward, run these commands in order:

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

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

Related

• Matrix: channel setup and config.
• Matrix push rules: notification routing.
• Doctor: health check and automatic migration trigger.
• Migration guide: all migration paths (machine moves, cross-system imports).
• Plugins: plugin install and registration.