OpenClaw Matrix-Migration: Automatische Upgrades in Minuten

Was die Migration automatisch erledigt

Wenn das Gateway startet oder wenn du openclaw doctor --fix ausführst, versucht OpenClaw, den alten Matrix-Status automatisch zu reparieren. Bevor ein Schritt der Matrix-Migration den Status auf der Festplatte verändert, erstellt oder nutzt OpenClaw einen gezielten Recovery-Snapshot.

Wenn du openclaw update nutzt, hängt der genaue Auslöser davon ab, wie OpenClaw installiert ist:

Source-Installationen führen openclaw doctor --fix während des Updates aus und starten das Gateway danach standardmäßig neu.
Package-Manager-Installationen aktualisieren das Paket, führen einen nicht-interaktiven Doctor-Durchlauf aus und verlassen sich auf den Standard-Neustart des Gateways, damit die Matrix-Migration beim Start abgeschlossen werden kann.
Falls du openclaw update --no-restart verwendest, wird die startbasierte Matrix-Migration verschoben, bis du später openclaw doctor --fix ausführst und das Gateway neu startest.

Die automatische Migration umfasst:

Erstellen oder Wiederverwenden eines Pre-Migration-Snapshots unter ~/Backups/openclaw-migrations/.
Wiederverwendung deiner gespeicherten Matrix-Credentials.
Beibehalten der gleichen Account-Auswahl und channels.matrix Konfiguration.
Verschieben des ältesten flachen Matrix-Sync-Stores in den aktuellen Account-bezogenen Speicherort.
Verschieben des ältesten flachen Matrix-Crypto-Stores in den aktuellen Account-bezogenen Speicherort, sofern der Ziel-Account sicher aufgelöst werden kann.
Extrahieren eines zuvor gespeicherten Matrix-Room-Key-Backup-Decryption-Keys aus dem alten Rust-Crypto-Store, falls dieser Key lokal existiert.
Wiederverwendung des vollständigsten vorhandenen Token-Hash-Storage-Roots für denselben Matrix-Account, Homeserver und User, wenn sich das Access Token später ändert.
Scannen von benachbarten Token-Hash-Storage-Roots nach ausstehenden Metadaten zur Wiederherstellung des verschlüsselten Status, wenn sich das Matrix Access Token geändert hat, aber die Account- oder Geräte-Identität gleich geblieben ist.
Wiederherstellen von gesicherten Room-Keys in den neuen Crypto-Store beim nächsten Matrix-Start.

Details zum Snapshot:

OpenClaw schreibt nach einem erfolgreichen Snapshot eine Marker-Datei unter ~/.openclaw/matrix/migration-snapshot.json, damit spätere Start- und Reparaturdurchläufe dasselbe Archiv wiederverwenden können.
Diese automatischen Matrix-Migrations-Snapshots sichern nur Konfiguration und Status (includeWorkspace: false).
Wenn Matrix nur einen Status hat, der lediglich Warnungen auslöst – zum Beispiel weil userId oder accessToken noch fehlen – erstellt OpenClaw noch keinen Snapshot, da keine Matrix-Änderung durchführbar ist.
Falls der Snapshot-Schritt fehlschlägt, überspringt OpenClaw die Matrix-Migration für diesen Durchlauf, anstatt den Status ohne Wiederherstellungspunkt zu verändern.

Über Upgrades mit mehreren Accounts:

Der älteste flache Matrix-Store (~/.openclaw/matrix/bot-storage.json und ~/.openclaw/matrix/crypto/) stammt aus einem Layout mit nur einem Store. Daher kann OpenClaw diesen nur in ein aufgelöstes Matrix-Account-Ziel migrieren.
Bereits Account-bezogene Legacy-Matrix-Stores werden erkannt und pro konfiguriertem Matrix-Account vorbereitet.

Was die Migration nicht automatisch erledigt

Das vorherige öffentliche Matrix-Plugin hat Matrix-Room-Key-Backups nicht automatisch erstellt. Es hat den lokalen Crypto-Status gespeichert und eine Geräte-Verifizierung angefordert, aber es gab keine Garantie, dass deine Room-Keys auf dem Homeserver gesichert wurden.

Das bedeutet, dass einige verschlüsselte Installationen nur teilweise migriert werden können.

OpenClaw kann Folgendes nicht automatisch wiederherstellen:

Nur lokal vorhandene Room-Keys, die nie gesichert wurden.
Verschlüsselter Status, wenn der Ziel-Matrix-Account noch nicht aufgelöst werden kann, weil homeserver, userId oder accessToken noch nicht verfügbar sind.
Automatische Migration eines gemeinsam genutzten flachen Matrix-Stores, wenn mehrere Matrix-Accounts konfiguriert sind, aber channels.matrix.defaultAccount nicht gesetzt ist.
Installationen mit benutzerdefinierten Plugin-Pfaden, die auf einen Repo-Pfad statt auf das Standard-Matrix-Paket fixiert sind.
Ein fehlender Recovery-Key, wenn der alte Store zwar gesicherte Keys hatte, aber den Decryption-Key nicht lokal gespeichert hat.

Aktueller Umfang der Warnungen:

Installationen mit benutzerdefinierten Matrix-Plugin-Pfaden werden sowohl beim Gateway-Start als auch durch openclaw doctor angezeigt.

Falls deine alte Installation nur lokale verschlüsselte Verläufe hatte, die nie gesichert wurden, könnten einige ältere verschlüsselte Nachrichten nach dem Upgrade unlesbar bleiben.

Empfohlener Upgrade-Prozess

Aktualisiere OpenClaw und das Matrix-Plugin ganz normal. Ich empfehle dir ein einfaches openclaw update ohne --no-restart. So kann der Startup die Matrix-Migration sofort abschließen.
Führe diesen Befehl aus:
Terminal-Fenster
```
openclaw doctor --fix
```
Falls Matrix anstehende Migrationsaufgaben hat, erstellt doctor zuerst einen Snapshot vor der Migration oder verwendet einen vorhandenen und gibt den Pfad zum Archiv aus.
Starte das Gateway oder führe einen Restart durch.
Prüfe den aktuellen Status der Verifizierung und des Backups:
Terminal-Fenster
```
openclaw matrix verify status
openclaw matrix verify backup status
```
Wenn OpenClaw meldet, dass ein Recovery-Key benötigt wird, verwende diesen Befehl:
Terminal-Fenster
```
openclaw matrix verify backup restore --recovery-key "<your-recovery-key>"
```
Falls dieses Device noch nicht verifiziert ist, hilft dir dieser Befehl:
Terminal-Fenster
```
openclaw matrix verify device "<your-recovery-key>"
```
Wenn du alte, nicht wiederherstellbare Verläufe bewusst löschen willst und eine saubere Basis für zukünftige Nachrichten brauchst, verwende:
Terminal-Fenster
```
openclaw matrix verify backup reset --yes
```
Falls noch kein serverseitiges Key-Backup existiert, erstelle eines für zukünftige Wiederherstellungen:
Terminal-Fenster
```
openclaw matrix verify bootstrap
```

So funktioniert die verschlüsselte Migration

Die verschlüsselte Migration ist ein Prozess in zwei Phasen:

Der Startup oder openclaw doctor --fix erstellt einen Snapshot vor der Migration oder verwendet diesen wieder, sofern die verschlüsselte Migration möglich ist.
Startup oder openclaw doctor --fix prüfen den alten Matrix Crypto-Store über die aktive Matrix-Plugin-Installation.
Findet OpenClaw einen Backup-Decryption-Key, wird dieser in den neuen Recovery-Key-Flow geschrieben und die Wiederherstellung der Room-Keys als ausstehend markiert.
Beim nächsten Matrix-Startup stellt OpenClaw die gesicherten Room-Keys automatisch im neuen Crypto-Store wieder her.

Falls der alte Store Room-Keys meldet, die nie gesichert wurden, gibt OpenClaw eine Warnung aus, anstatt eine erfolgreiche Wiederherstellung vorzutäuschen.

AI Setup Assistant

Nächste Schritte

Häufige Meldungen und ihre Bedeutung

Upgrade- und Erkennungsmeldungen

Matrix plugin upgraded in place.

Bedeutung: Der alte Matrix-Status auf der Festplatte wurde erkannt und in das aktuelle Layout migriert.
Was zu tun ist: Nichts, es sei denn, die Ausgabe enthält zusätzlich Warnungen.

Matrix migration snapshot created before applying Matrix upgrades.

Bedeutung: OpenClaw hat ein Wiederherstellungsarchiv erstellt, bevor der Matrix-Status geändert wurde.
Was zu tun ist: Bewahre den ausgegebenen Archivpfad auf, bis du bestätigt hast, dass die Migration erfolgreich war.

Matrix migration snapshot reused before applying Matrix upgrades.

Bedeutung: OpenClaw hat eine vorhandene Markierung für einen Matrix-Migrations-Snapshot gefunden und dieses Archiv wiederverwendet, anstatt ein Duplikat zu erstellen.
Was zu tun ist: Bewahre den ausgegebenen Archivpfad auf, bis du bestätigt hast, dass die Migration erfolgreich war.

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

Bedeutung: Ein alter Matrix-Status existiert, aber OpenClaw kann ihn keinem aktuellen Matrix-Account zuordnen, da Matrix nicht konfiguriert ist.
Was zu tun ist: Konfiguriere channels.matrix, führe dann openclaw doctor --fix erneut aus oder starte das Gateway neu.

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

Bedeutung: OpenClaw hat einen alten Status gefunden, kann aber das genaue Ziel für den Account oder das Device-Root noch nicht bestimmen.
Was zu tun ist: Starte das Gateway einmal mit einem funktionierenden Matrix-Login oder führe openclaw doctor --fix erneut aus, sobald gespeicherte Credentials vorhanden sind.

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

Bedeutung: OpenClaw hat einen geteilten Matrix-Speicher gefunden, weigert sich aber zu raten, welcher benannte Matrix-Account diesen erhalten soll.
Was zu tun ist: Setze channels.matrix.defaultAccount auf den gewünschten Account und führe dann openclaw doctor --fix erneut aus oder starte das Gateway neu.

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

Bedeutung: Am neuen account-spezifischen Ort existiert bereits ein Sync- oder Crypto-Store, daher hat OpenClaw diesen nicht automatisch überschrieben.
Was zu tun ist: Überprüfe, ob der aktuelle Account korrekt ist, bevor du das kollidierende Ziel manuell entfernst oder verschiebst.

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

Bedeutung: OpenClaw hat versucht, den alten Matrix-Status zu verschieben, aber die Dateisystem-Operation ist fehlgeschlagen.
Was zu tun ist: Überprüfe die Dateisystemberechtigungen und den Festplattenstatus, führe dann openclaw doctor --fix erneut aus.

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

Bedeutung: OpenClaw hat einen alten verschlüsselten Matrix-Speicher gefunden, aber es gibt keine aktuelle Matrix-Konfiguration, mit der er verknüpft werden könnte.
Was zu tun ist: Konfiguriere channels.matrix, führe dann openclaw doctor --fix erneut aus oder starte das Gateway neu.

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

Bedeutung: Der verschlüsselte Speicher existiert, aber OpenClaw kann nicht sicher entscheiden, zu welchem aktuellen Account oder Device er gehört.
Was zu tun ist: Starte das Gateway einmal mit einem funktionierenden Matrix-Login oder führe openclaw doctor --fix erneut aus, sobald gespeicherte Credentials verfügbar sind.

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

Bedeutung: OpenClaw hat einen geteilten alten Crypto-Store gefunden, weigert sich aber zu raten, welcher benannte Matrix-Account diesen erhalten soll.
Was zu tun ist: Setze channels.matrix.defaultAccount auf den gewünschten Account und führe dann openclaw doctor --fix erneut aus oder starte das Gateway neu.

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

Bedeutung: OpenClaw hat einen alten Matrix-Status erkannt, aber die Migration wird noch durch fehlende Identitäts- oder Zugangsdaten blockiert.
Was zu tun ist: Schließe den Matrix-Login oder das Setup der Konfiguration ab, führe dann openclaw doctor --fix erneut aus oder starte das Gateway neu.

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.

Bedeutung: OpenClaw hat einen alten verschlüsselten Matrix-Status gefunden, konnte aber den Helper-Einstiegspunkt des Matrix-Plugins nicht laden, der normalerweise diesen Speicher prüft.
Was zu tun ist: Installiere oder repariere das Matrix-Plugin (openclaw plugins install @openclaw/matrix oder openclaw plugins install ./pfad/zum/lokalen/matrix-plugin bei einem Repo-Checkout), führe dann openclaw doctor --fix erneut aus oder starte das Gateway neu.

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

Bedeutung: OpenClaw hat einen Pfad für die Helper-Datei gefunden, der außerhalb des Plugin-Roots liegt oder Sicherheitsprüfungen nicht besteht, und hat den Import verweigert.
Was zu tun ist: Installiere das Matrix-Plugin von einem vertrauenswürdigen Pfad neu, führe dann openclaw doctor --fix erneut aus oder starte das Gateway neu.

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

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

Bedeutung: OpenClaw hat die Änderung des Matrix-Status verweigert, da kein Wiederherstellungs-Snapshot erstellt werden konnte.
Was zu tun ist: Behebe den Backup-Fehler und führe dann openclaw doctor --fix erneut aus oder starte das Gateway neu.

Failed migrating legacy Matrix client storage: ...

Bedeutung: Der clientseitige Matrix-Fallback hat einen alten Speicher gefunden, aber das Verschieben ist fehlgeschlagen. OpenClaw bricht diesen Fallback nun ab, anstatt stillschweigend mit einem leeren Speicher zu starten.
Was zu tun ist: Überprüfe Dateisystemberechtigungen oder Konflikte, lass den alten Status unverändert und versuche es nach der Fehlerbehebung erneut.

Matrix is installed from a custom path: ...

Bedeutung: Matrix ist an eine Pfad-Installation gebunden, sodass Standard-Updates es nicht automatisch durch das offizielle Matrix-Paket ersetzen.
Was zu tun ist: Installiere es mit openclaw plugins install @openclaw/matrix neu, wenn du zum Standard-Matrix-Plugin zurückkehren möchtest.

Meldungen zur Wiederherstellung verschlüsselter Zustände

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

Bedeutung: Gesicherte Room-Keys wurden erfolgreich in den neuen Crypto-Store wiederhergestellt.
Was zu tun ist: Normalerweise nichts.

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

Bedeutung: Einige alte Room-Keys existierten nur im alten lokalen Speicher und wurden nie in das Matrix-Backup hochgeladen.
Was zu tun ist: Stelle dich darauf ein, dass ein Teil des alten verschlüsselten Verlaufs nicht verfügbar bleibt, es sei denn, du kannst diese Keys manuell von einem anderen verifizierten Client wiederherstellen.

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.

Bedeutung: Ein Backup existiert, aber OpenClaw konnte den Recovery-Key nicht automatisch wiederherstellen.
Was zu tun ist: Führe openclaw matrix verify backup restore --recovery-key "<dein-recovery-key>" aus.

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

Bedeutung: OpenClaw hat den alten verschlüsselten Speicher gefunden, konnte ihn aber nicht sicher genug prüfen, um die Wiederherstellung vorzubereiten.
Was zu tun ist: Führe openclaw doctor --fix erneut aus. Falls der Fehler bleibt, behalte das alte Verzeichnis bei und nutze einen anderen verifizierten Matrix-Client zusammen mit openclaw matrix verify backup restore --recovery-key "<dein-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.

Bedeutung: OpenClaw hat einen Konflikt bei den Backup-Keys erkannt und sich geweigert, die aktuelle recovery-key-Datei automatisch zu überschreiben.
Was zu tun ist: Überprüfe, welcher Recovery-Key korrekt ist, bevor du einen Restore-Befehl erneut versuchst.

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.

Bedeutung: Dies ist eine technische Einschränkung des alten Speicherformats.
Was zu tun ist: Gesicherte Keys können weiterhin wiederhergestellt werden, aber lokal gespeicherter verschlüsselter Verlauf bleibt eventuell unerreichbar.

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

Bedeutung: Das neue Plugin hat die Wiederherstellung versucht, aber Matrix hat einen Fehler zurückgegeben.
Was zu tun ist: Führe openclaw matrix verify backup status aus und versuche es bei Bedarf mit openclaw matrix verify backup restore --recovery-key "<dein-recovery-key>" erneut.

Meldungen zur manuellen Wiederherstellung

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

Bedeutung: OpenClaw weiß, dass du einen Backup-Key haben solltest, aber er ist auf diesem Gerät nicht aktiv.
Was zu tun ist: Führe openclaw matrix verify backup restore aus oder übergib --recovery-key, falls nötig.

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

Bedeutung: Dieses Gerät hat aktuell keinen Recovery-Key gespeichert.
Was zu tun ist: Verifiziere das Gerät zuerst mit deinem Recovery-Key und stelle dann das Backup wieder her.

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

Bedeutung: Der gespeicherte Key passt nicht zum aktiven Matrix-Backup.
Was zu tun ist: Führe openclaw matrix verify device "<dein-recovery-key>" mit dem korrekten Key erneut aus.

Falls du den Verlust von nicht wiederherstellbarem verschlüsseltem Verlauf akzeptierst, kannst du stattdessen die aktuelle Backup-Basis mit openclaw matrix verify backup reset --yes zurücksetzen.

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

Bedeutung: Das Backup existiert, aber dieses Gerät vertraut der Cross-Signing-Kette noch nicht ausreichend.
Was zu tun ist: Führe openclaw matrix verify device "<dein-recovery-key>" erneut aus.

Matrix recovery key is required

Bedeutung: Du hast einen Wiederherstellungsschritt versucht, ohne einen erforderlichen Recovery-Key anzugeben.
Was zu tun ist: Führe den Befehl erneut mit deinem Recovery-Key aus.

Invalid Matrix recovery key: ...

Bedeutung: Der angegebene Key konnte nicht verarbeitet werden oder entspricht nicht dem erwarteten Format.
Was zu tun ist: Versuche es erneut mit dem exakten Recovery-Key aus deinem Matrix-Client oder deiner recovery-key-Datei.

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

Bedeutung: Der Key wurde angewendet, aber das Gerät konnte die Verifizierung trotzdem nicht abschließen.
Was zu tun ist: Bestätige, dass du den richtigen Key verwendet hast und Cross-Signing für den Account verfügbar ist, dann versuche es erneut.

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

Bedeutung: Secret Storage hat keine aktive Backup-Session auf diesem Gerät erzeugt.
Was zu tun ist: Verifiziere zuerst das Gerät und prüfe den Status dann erneut mit 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.

Bedeutung: Dieses Gerät kann keine Daten aus dem Secret Storage wiederherstellen, bis die Geräteverifizierung abgeschlossen ist.
Was zu tun ist: Führe zuerst openclaw matrix verify device "<dein-recovery-key>" aus.

Meldungen bei benutzerdefinierter Plugin-Installation

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

Bedeutung: Dein Plugin-Installationsdatensatz verweist auf einen lokalen Pfad, der nicht mehr existiert.
Was zu tun ist: Installiere es mit openclaw plugins install @openclaw/matrix neu, oder falls du einen Repo-Checkout nutzt, mit openclaw plugins install ./pfad/zum/lokalen/matrix-plugin.

Wenn der verschlüsselte Verlauf trotzdem nicht erscheint

Führe diese Prüfungen nacheinander aus:

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

Wenn das Backup erfolgreich wiederhergestellt wird, aber in einigen alten Räumen immer noch der Verlauf fehlt, wurden diese Keys wahrscheinlich nie vom vorherigen Plugin gesichert.

Wenn du für zukünftige Nachrichten neu anfangen willst

Wenn du damit einverstanden bist, den nicht wiederherstellbaren alten verschlüsselten Verlauf zu verlieren und ab jetzt nur noch eine saubere Backup-Basis haben möchtest, führe diese Befehle nacheinander aus:

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

Falls das Gerät danach immer noch nicht verifiziert ist, schließe die Verifizierung in deinem Matrix-Client ab. Vergleiche dazu die SAS-Emojis oder Dezimalcodes und bestätige, dass sie übereinstimmen.

Noch festgefahren?

Wenn diese Seite nicht hilft, frage OpenClaw Expert nach Schritt-fuer-Schritt-Loesungen.