OpenClaw Matrix migration

Upgrading a Matrix installation from the previous public plugin to the current one is an in-place move for most people, but the docs are careful about the one thing that cannot be migrated: encrypted history that was never backed up. Here is what the migration does on its own, the recommended flow, the messages you may see and the recovery ladder when encrypted rooms stay dark.

What stays where

• The plugin stays the same Matrix plugin package, the channel stays matrix and the config stays under channels.matrix, so there is nothing to rename; cached credentials move into the shared SQLite plugin state while runtime state stays under the Matrix directory in the OpenClaw home.
• The root openclaw package no longer bundles Matrix runtime code or SDK dependencies: if channels status shows Matrix configured but the plugin not installed, run doctor --fix or install the Matrix plugin package with plugins install, and never install Matrix SDK packages into the root package.
• Doctor migration imports and verifies the retired credential files under credentials/matrix before archiving them, keeps the same account selection and config, and imports the file sidecars (the bot-storage sync cache, the recovery key file, the legacy crypto migration marker and IndexedDB snapshots) into Matrix SQLite state, archiving the files with a .migrated suffix.
• When the access token changes later, the migration reuses the most complete existing token-hash storage root for the same account, homeserver, user and device; credential-file import is Doctor-only, because the runtime reads only the canonical SQLite credential state.

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.

Older than 2026.4

Releases through the 2026.6 train also migrated the original flat single-store layout, the bot-storage file plus the crypto directory directly under the Matrix directory, and prepared encrypted-state recovery from the old rust crypto store. Current releases no longer carry that migration, so an installation still on the flat layout upgrades to a 2026.6 release first, runs doctor --fix, starts the gateway once so the flat store and any recoverable room keys migrate, and only then moves to the latest release. The previous plugin did not create room-key backups automatically, which is why local-only encrypted history that was never backed up may remain unreadable after the upgrade regardless of the path.

The recommended flow

• Update OpenClaw and the Matrix plugin normally, run doctor --fix, start or restart the gateway, then check the state with matrix verify status and matrix verify backup status.
• Put the recovery key in an account-specific environment variable (MATRIX_RECOVERY_KEY for a single default account, one variable per account such as MATRIX_RECOVERY_KEY_ASSISTANT with --account assistant otherwise) and pipe it into verify backup restore --recovery-key-stdin when OpenClaw says a key is needed, then into verify device --recovery-key-stdin if the device is still unverified.
• If the key is accepted and the backup usable but cross-signing still reads no, run matrix verify self, accept the request in another Matrix client, compare the emoji or decimals and type yes only when they match; verify backup reset --yes starts a fresh baseline when you abandon unrecoverable history, and verify bootstrap creates a server-side backup when none exists.

OpenClaw on Matrix is the channel post this migration belongs to and OpenClaw Matrix encryption explains the verification, backup and cross-signing model the commands above operate on.

Reading the messages

A failed migration of legacy client storage stops startup, keeps completed SQLite imports and archived sidecars in place and leaves unarchived files available for a retry once the permission or conflict is fixed. A custom-path install message means Matrix is pinned to a path, so mainline updates do not replace it; reinstall from the default package to return. The verify commands print a backup issue line with next steps: no backup on the homeserver means bootstrap, a key not loaded on this device means restore with the recovery key, a key mismatch means restore with the active server key or reset, an untrusted signature chain means verify the device and then verify self, and inconclusive trust diagnostics mean the verbose status. OpenClaw Matrix setup and OpenClaw Matrix accounts and homeservers cover the fresh-install side and the multi-account layout these variables name.

On Diali

Matrix is on Diali’s connectable list, alongside WhatsApp, Telegram, Discord, Slack, Mattermost, SMS and voice: the homeserver account and the room allowlist are yours, the Gateway is ours. Hosted OpenClaw on Diali is the hosted assistant and Diali security describes how state, including plugin state, is kept on a persistent volume, with daily snapshots and one-click restore available through the Backups add-on (included on Max).

• Same plugin, same channel id, same config keys.
• Flat layouts go through 2026.6 before the latest release.
• Never backed-up history stays unreadable; bootstrap a backup now.