Matrix Plugin Migration Guide

Upgrade from the earlier public matrix plugin to the current one.

For the majority of users, the upgrade happens in place:

the plugin remains @openclaw/matrix
the channel remains matrix
your configuration stays under channels.matrix
cached credentials are relocated into the shared state/openclaw.sqlite plugin state
runtime state continues to reside under ~/.openclaw/matrix/

There is no need to rename configuration keys or reinstall the plugin under a different name. The root openclaw package no longer ships Matrix runtime code or Matrix SDK dependencies. If openclaw channels status shows that Matrix is configured but the plugin is not installed, execute openclaw doctor --fix or openclaw plugins install @openclaw/matrix; avoid installing Matrix SDK packages into the root OpenClaw package.

What the migration does automatically

Matrix migration triggers when you run openclaw doctor --fix. File-based sidecars next to the dedicated Matrix store keep their client-start fallback, but credential-file import is only available through Doctor; runtime reads exclusively from the canonical SQLite credential state.

Doctor migration addresses:

importing and verifying deprecated ~/.openclaw/credentials/matrix/credentials*.json files before archiving them
preserving the same account selection and channels.matrix configuration
importing file-based sidecar state (bot-storage.json sync cache, recovery-key.json, legacy-crypto-migration.json, IndexedDB snapshots) into Matrix SQLite state; migrated files get archived with a .migrated suffix
reusing the most complete existing token-hash storage root for the same Matrix account, homeserver, user, and device when the access token changes later

Upgrading from OpenClaw releases older than 2026.4

Releases up to and including the 2026.6 train also migrated the original flat single-store Matrix layout (~/.openclaw/matrix/bot-storage.json plus ~/.openclaw/matrix/crypto/) and prepared encrypted-state recovery from the old rust crypto store. Current releases no longer include that migration.

If you are upgrading an installation that still uses the flat layout, first upgrade to a 2026.6 release, run openclaw doctor --fix, and start the gateway once so that the flat store and any recoverable room keys are migrated. Then update to the latest release.

The earlier public Matrix plugin did not automatically create Matrix room-key backups. If your old installation had local-only encrypted history that was never backed up, some older encrypted messages may remain unreadable after the upgrade regardless of the migration path.

Recommended upgrade flow

Update OpenClaw and the Matrix plugin normally.
Run:
```
openclaw doctor --fix
```
Start or restart the gateway.

Check current verification and backup state:

openclaw matrix verify status
openclaw matrix verify backup status

Place the recovery key for the Matrix account you are repairing in an account-specific environment variable. For a single default account, MATRIX_RECOVERY_KEY works. For multiple accounts, use one variable per account, for example MATRIX_RECOVERY_KEY_ASSISTANT, and add --account assistant to the command.

If OpenClaw indicates a recovery key is required, run the command for the matching account:

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

If this device remains unverified, run the command for the matching account:
```
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 Cross-signing verified is still no, complete self-verification from another Matrix client:
```
openclaw matrix verify self
```
Accept the request in another Matrix client, compare the emoji or decimals, and type yes only when they match. The command waits for full Matrix identity trust before reporting success.
If you are deliberately discarding unrecoverable old history and want a fresh backup baseline for future messages, run:
```
openclaw matrix verify backup reset --yes
```
Add --rotate-recovery-key only when the old recovery key should no longer unlock the fresh backup.
If no server-side key backup exists yet, create one for future recoveries:
```
openclaw matrix verify bootstrap
```

Common messages and what they mean

Failed migrating legacy Matrix client storage: ...

Meaning: the Matrix client-side fallback found file-based sidecar state, but the import into SQLite failed. OpenClaw rolls back completed moves and aborts that fallback instead of silently starting with a fresh store.
What to do: check filesystem permissions or conflicts, keep the old state intact, and retry after fixing the error.

Matrix is installed from a custom path: ...

Meaning: Matrix is pinned to a path install, so mainline updates do not automatically replace it with the default Matrix package.
What to do: reinstall with openclaw plugins install @openclaw/matrix when you want to return to the default Matrix plugin.

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

Meaning: your plugin install record points at a local path that is missing.
What to do: reinstall with openclaw plugins install @openclaw/matrix, or if you are running from a repo checkout, openclaw plugins install ./path/to/local/matrix-plugin. openclaw doctor --fix can also remove the stale Matrix plugin references for you.

Manual recovery messages

openclaw matrix verify status and openclaw matrix verify backup status output a Backup issue: line plus Next steps: guidance when the room-key backup is not healthy on this device.

Backup issue	Meaning	Fix
`no room-key backup exists on the homeserver`	No data is available for restoration	`openclaw matrix verify bootstrap` to generate a room key backup
`backup decryption key is not loaded on this device`	A key exists but is not currently active here	`openclaw matrix verify backup restore`; if the key still fails to load, feed the recovery key through `--recovery-key-stdin`
`backup decryption key could not be loaded from secret storage (...)`	Secret storage could not be loaded or is not supported	Provide the recovery key via: `printf '%s\n' "$MATRIX_RECOVERY_KEY" \| openclaw matrix verify backup restore --recovery-key-stdin`
`backup key mismatch (...)`	The stored key does not correspond to the active server backup	Execute `verify backup restore --recovery-key-stdin` again with the active server backup key, or use `verify backup reset --yes` to start a new baseline
`backup signature chain is not trusted by this device`	The device has not yet trusted the cross-signing chain	Run `verify device --recovery-key-stdin`, then if trust remains incomplete, run `verify self` from another verified client
`backup exists but is not active on this device`	A server backup exists but the local session is inactive	Verify the device first, then recheck using `openclaw matrix verify backup status`
`backup trust state could not be fully determined`	Diagnostics were not conclusive	`openclaw matrix verify status --verbose`

Other recovery errors:

Matrix recovery key is required

Meaning: you attempted a recovery step without providing a required recovery key.
What to do: repeat the command with --recovery-key-stdin, for instance printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin.

Invalid Matrix recovery key: ...

Meaning: the supplied key could not be parsed or did not match the expected format.
What to do: try again using the exact recovery key from your Matrix client or recovery key export.

Matrix recovery key was applied, but this device still lacks full Matrix identity trust.

Meaning: the recovery key unlocked usable backup material, but Matrix has not fully established cross-signing identity trust for this device. Look in the command output for Recovery key accepted, Backup usable, Cross-signing verified, and Device verified by owner.
What to do: execute openclaw matrix verify self, approve the request in another Matrix client, compare the SAS, and enter yes only when they match. Use printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify bootstrap --recovery-key-stdin --force-reset-cross-signing only when you deliberately want to replace the existing cross-signing identity.

If you are willing to lose unrecoverable old encrypted history, you can instead reset the current backup baseline with openclaw matrix verify backup reset --yes. When the stored backup secret is corrupted, that reset also fixes secret storage so the new backup key can load correctly after restart.

If encrypted history still does not come back

Perform these checks in order:

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 correctly but some old rooms still lack history, those missing keys were likely never backed up by the previous plugin.

If you want to start fresh for future messages

If you are willing to lose unrecoverable old encrypted history and want only a clean backup baseline going forward, run these commands in sequence:

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

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

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.