Matrix-Migration

• das Plugin bleibt @openclaw/matrix
• der Channel bleibt matrix
• Ihre Konfiguration bleibt unter channels.matrix
• zwischengespeicherte Anmeldedaten bleiben unter ~/.openclaw/credentials/matrix/
• Laufzeitstatus bleibt unter ~/.openclaw/matrix/

​

Was die Migration automatisch erledigt

• Quellinstallationen führen während des Update-Ablaufs openclaw doctor --fix aus und starten den Gateway anschließend standardmäßig neu
• Paketmanager-Installationen aktualisieren das Paket, führen einen nicht interaktiven Doctor-Durchlauf aus und verlassen sich dann auf den standardmäßigen Gateway-Neustart, damit der Start die Matrix-Migration abschließen kann
• wenn Sie openclaw update --no-restart verwenden, wird die startgestützte Matrix-Migration verschoben, bis Sie später openclaw doctor --fix ausführen und den Gateway neu starten

• Erstellen oder erneutes Verwenden eines Vorab-Migrations-Snapshots unter ~/Backups/openclaw-migrations/
• erneutes Verwenden Ihrer zwischengespeicherten Matrix-Anmeldedaten
• Beibehalten derselben Kontoauswahl und channels.matrix-Konfiguration
• Verschieben des ältesten flachen Matrix-Sync-Speichers an den aktuellen kontobezogenen Speicherort
• Verschieben des ältesten flachen Matrix-Crypto-Speichers an den aktuellen kontobezogenen Speicherort, wenn das Zielkonto sicher aufgelöst werden kann
• Extrahieren eines zuvor gespeicherten Entschlüsselungsschlüssels für Matrix-Room-Key-Backups aus dem alten Rust-Crypto-Speicher, wenn dieser Schlüssel lokal vorhanden ist
• erneutes Verwenden des vollständigsten bestehenden Token-Hash-Speicher-Roots für dasselbe Matrix-Konto, denselben Homeserver und denselben Benutzer, wenn sich das Zugriffstoken später ändert
• Scannen benachbarter Token-Hash-Speicher-Roots nach ausstehenden Wiederherstellungsmetadaten für verschlüsselten Status, wenn sich das Matrix-Zugriffstoken geändert hat, die Konto-/Geräteidentität aber gleich geblieben ist
• Wiederherstellen gesicherter Room Keys in den neuen Crypto-Speicher beim nächsten Matrix-Start

• OpenClaw schreibt nach einem erfolgreichen Snapshot eine Markerdatei nach ~/.openclaw/matrix/migration-snapshot.json, damit spätere Start- und Reparaturdurchläufe dasselbe Archiv erneut verwenden können.
• Diese automatischen Matrix-Migrations-Snapshots sichern nur Konfiguration und Status (includeWorkspace: false).
• Wenn Matrix nur Migrationsstatus mit Warnungen hat, zum Beispiel weil userId oder accessToken noch fehlen, erstellt OpenClaw den Snapshot noch nicht, weil keine Matrix-Mutation ausführbar ist.
• Wenn der Snapshot-Schritt fehlschlägt, überspringt OpenClaw die Matrix-Migration für diesen Lauf, statt Status ohne Wiederherstellungspunkt zu verändern.

• der älteste flache Matrix-Speicher (~/.openclaw/matrix/bot-storage.json und ~/.openclaw/matrix/crypto/) stammt aus einem Einzel-Speicher-Layout, daher kann OpenClaw ihn nur in ein aufgelöstes Matrix-Zielkonto migrieren
• bereits kontobezogene alte Matrix-Speicher werden pro konfiguriertem Matrix-Konto erkannt und vorbereitet

​

Was die Migration nicht automatisch erledigen kann

• nur lokal vorhandene Room Keys, die nie gesichert wurden
• verschlüsselten Status, wenn das Ziel-Matrix-Konto noch nicht aufgelöst werden kann, weil homeserver, userId oder accessToken noch nicht verfügbar sind
• automatische Migration eines gemeinsam genutzten flachen Matrix-Speichers, wenn mehrere Matrix-Konten konfiguriert sind, aber channels.matrix.defaultAccount nicht gesetzt ist
• benutzerdefinierte Plugin-Pfadinstallationen, die an einen Repository-Pfad statt an das Standard-Matrix-Paket gebunden sind
• einen fehlenden Wiederherstellungsschlüssel, wenn der alte Speicher gesicherte Schlüssel hatte, den Entschlüsselungsschlüssel aber nicht lokal behalten hat

• benutzerdefinierte Matrix-Plugin-Pfadinstallationen werden sowohl beim Gateway-Start als auch von openclaw doctor gemeldet

​

Empfohlener Upgrade-Ablauf

1. Aktualisieren Sie OpenClaw und das Matrix-Plugin wie gewohnt. Bevorzugen Sie einfaches openclaw update ohne --no-restart, damit der Start die Matrix-Migration sofort abschließen kann.
2. Führen Sie aus:
   openclaw doctor --fix
   
   Wenn Matrix ausführbare Migrationsarbeit hat, erstellt der Doctor zuerst den Vorab-Migrations-Snapshot oder verwendet ihn erneut und gibt den Archivpfad aus.
3. Starten Sie den Gateway oder starten Sie ihn neu.
4. Prüfen Sie den aktuellen Verifizierungs- und Backup-Status:
   openclaw matrix verify status
   openclaw matrix verify backup status
   
5. Legen Sie den Wiederherstellungsschlüssel für das Matrix-Konto, das Sie reparieren, in einer kontospezifischen Umgebungsvariable ab. Für ein einzelnes Standardkonto ist MATRIX_RECOVERY_KEY ausreichend. Für mehrere Konten verwenden Sie eine Variable pro Konto, zum Beispiel MATRIX_RECOVERY_KEY_ASSISTANT, und fügen Sie dem Befehl --account assistant hinzu.
6. Wenn OpenClaw Ihnen mitteilt, dass ein Wiederherstellungsschlüssel erforderlich ist, führen Sie den Befehl für das passende Konto aus:
   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. Wenn dieses Gerät noch unverifiziert ist, führen Sie den Befehl für das passende Konto aus:
   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
   
   Wenn der Wiederherstellungsschlüssel akzeptiert wird und das Backup nutzbar ist, Cross-signing verified aber weiterhin no ist, schließen Sie die Selbstverifizierung in einem anderen Matrix-Client ab:
   openclaw matrix verify self
   
   Akzeptieren Sie die Anfrage in einem anderen Matrix-Client, vergleichen Sie die Emojis oder Dezimalzahlen und geben Sie yes nur ein, wenn sie übereinstimmen. Der Befehl wird erst erfolgreich beendet, nachdem Cross-signing verified zu yes wird.
8. Wenn Sie nicht wiederherstellbare alte Historie bewusst aufgeben und eine neue Backup-Basis für zukünftige Nachrichten erstellen möchten, führen Sie aus:
   openclaw matrix verify backup reset --yes
   
9. Wenn noch kein serverseitiges Schlüsselbackup vorhanden ist, erstellen Sie eines für zukünftige Wiederherstellungen:
   openclaw matrix verify bootstrap
   

​

Wie verschlüsselte Migration funktioniert

1. Start oder openclaw doctor --fix erstellt den Vorab-Migrations-Snapshot oder verwendet ihn erneut, wenn verschlüsselte Migration ausführbar ist.
2. Start oder openclaw doctor --fix prüft den alten Matrix-Crypto-Speicher über die aktive Matrix-Plugin-Installation.
3. Wenn ein Backup-Entschlüsselungsschlüssel gefunden wird, schreibt OpenClaw ihn in den neuen Wiederherstellungsschlüssel-Ablauf und markiert die Room-Key-Wiederherstellung als ausstehend.
4. Beim nächsten Matrix-Start stellt OpenClaw gesicherte Room Keys automatisch im neuen Crypto-Speicher wieder her.

​

Häufige Meldungen und ihre Bedeutung

​

Upgrade- und Erkennungsmeldungen

• Bedeutung: Der alte Matrix-Status auf dem Datenträger wurde erkannt und in das aktuelle Layout migriert.
• Was zu tun ist: nichts, sofern dieselbe Ausgabe nicht auch Warnungen enthält.

• Bedeutung: OpenClaw hat ein Wiederherstellungsarchiv erstellt, bevor Matrix-Status verändert wurde.
• Was zu tun ist: Bewahren Sie den ausgegebenen Archivpfad auf, bis Sie bestätigt haben, dass die Migration erfolgreich war.

• Bedeutung: OpenClaw hat einen bestehenden Matrix-Migrations-Snapshot-Marker gefunden und dieses Archiv erneut verwendet, statt ein doppeltes Backup zu erstellen.
• Was zu tun ist: Bewahren Sie den ausgegebenen Archivpfad auf, bis Sie bestätigt haben, dass die Migration erfolgreich war.

• Bedeutung: Alter Matrix-Status ist vorhanden, aber OpenClaw kann ihn keinem aktuellen Matrix-Konto zuordnen, weil Matrix nicht konfiguriert ist.
• Was zu tun ist: Konfigurieren Sie channels.matrix und führen Sie dann erneut openclaw doctor --fix aus oder starten Sie den Gateway neu.

• Bedeutung: OpenClaw hat alten Status gefunden, kann aber den genauen aktuellen Konto-/Geräte-Root noch nicht bestimmen.
• Was zu tun ist: Starten Sie den Gateway einmal mit einer funktionierenden Matrix-Anmeldung oder führen Sie openclaw doctor --fix erneut aus, nachdem zwischengespeicherte Anmeldedaten vorhanden sind.

• Bedeutung: OpenClaw hat einen gemeinsam genutzten flachen Matrix-Speicher gefunden, weigert sich aber zu raten, welches benannte Matrix-Konto ihn erhalten soll.
• Was zu tun ist: Setzen Sie channels.matrix.defaultAccount auf das vorgesehene Konto und führen Sie dann erneut openclaw doctor --fix aus oder starten Sie den Gateway neu.

• Bedeutung: Der neue kontobezogene Speicherort enthält bereits einen Sync- oder Crypto-Speicher, daher hat OpenClaw ihn nicht automatisch überschrieben.
• Was zu tun ist: Prüfen Sie, dass das aktuelle Konto das richtige ist, bevor Sie das widersprüchliche Ziel manuell entfernen oder verschieben.

• Bedeutung: OpenClaw hat versucht, alten Matrix-Status zu verschieben, aber der Dateisystemvorgang ist fehlgeschlagen.
• Was zu tun ist: Prüfen Sie Dateisystemberechtigungen und Datenträgerstatus und führen Sie dann erneut openclaw doctor --fix aus.

• Bedeutung: OpenClaw hat einen alten verschlüsselten Matrix-Speicher gefunden, aber es gibt keine aktuelle Matrix-Konfiguration, an die er angehängt werden kann.
• Was zu tun ist: Konfigurieren Sie channels.matrix und führen Sie dann erneut openclaw doctor --fix aus oder starten Sie den Gateway neu.

• Bedeutung: Der verschlüsselte Speicher existiert, aber OpenClaw kann nicht sicher entscheiden, zu welchem aktuellen Konto/Gerät er gehört.
• Was zu tun ist: Starten Sie den Gateway einmal mit einer funktionierenden Matrix-Anmeldung oder führen Sie openclaw doctor --fix erneut aus, nachdem zwischengespeicherte Anmeldedaten verfügbar sind.

• Bedeutung: OpenClaw hat einen gemeinsam genutzten flachen alten Crypto-Speicher gefunden, weigert sich aber zu raten, welches benannte Matrix-Konto ihn erhalten soll.
• Was zu tun ist: Setzen Sie channels.matrix.defaultAccount auf das vorgesehene Konto und führen Sie dann erneut openclaw doctor --fix aus oder starten Sie den Gateway neu.

• Bedeutung: OpenClaw hat alten Matrix-Status erkannt, aber die Migration ist noch durch fehlende Identitäts- oder Anmeldedaten blockiert.
• Was zu tun ist: Schließen Sie die Matrix-Anmeldung oder Konfigurationseinrichtung ab und führen Sie dann erneut openclaw doctor --fix aus oder starten Sie den Gateway neu.

• Bedeutung: OpenClaw hat alten verschlüsselten Matrix-Zustand gefunden, konnte aber den Helper-Einstiegspunkt aus dem Matrix-Plugin, der diesen Speicher normalerweise prüft, nicht laden.
• Vorgehen: Installieren oder reparieren Sie das Matrix-Plugin erneut (openclaw plugins install @openclaw/matrix, oder openclaw plugins install ./path/to/local/matrix-plugin für einen Repo-Checkout), und führen Sie dann openclaw doctor --fix erneut aus oder starten Sie den Gateway neu.

• Bedeutung: OpenClaw hat einen Helper-Dateipfad gefunden, der den Plugin-Root verlässt oder Plugin-Grenzprüfungen nicht besteht, und hat deshalb den Import verweigert.
• Vorgehen: Installieren Sie das Matrix-Plugin aus einem vertrauenswürdigen Pfad erneut, und führen Sie dann openclaw doctor --fix erneut aus oder starten Sie den Gateway neu.

• Bedeutung: OpenClaw hat Änderungen am Matrix-Zustand verweigert, weil zuerst kein Wiederherstellungs-Snapshot erstellt werden konnte.
• Vorgehen: Beheben Sie den Backup-Fehler, und führen Sie dann openclaw doctor --fix erneut aus oder starten Sie den Gateway neu.

• Bedeutung: Der clientseitige Matrix-Fallback hat alten flachen Speicher gefunden, aber das Verschieben ist fehlgeschlagen. OpenClaw bricht diesen Fallback jetzt ab, statt stillschweigend mit einem frischen Speicher zu starten.
• Vorgehen: Prüfen Sie Dateisystemberechtigungen oder Konflikte, lassen Sie den alten Zustand intakt und versuchen Sie es nach Behebung des Fehlers erneut.

• Bedeutung: Matrix ist an eine Pfadinstallation gebunden, daher ersetzen Mainline-Updates es nicht automatisch durch das Standard-Matrix-Paket des Repos.
• Vorgehen: Installieren Sie mit openclaw plugins install @openclaw/matrix neu, wenn Sie zum standardmäßigen Matrix-Plugin zurückkehren möchten.

​

Wiederherstellungsmeldungen für verschlüsselten Zustand

• Bedeutung: Gesicherte Raumschlüssel wurden erfolgreich im neuen Crypto-Speicher wiederhergestellt.
• Vorgehen: In der Regel nichts.

• Bedeutung: Einige alte Raumschlüssel existierten nur im alten lokalen Speicher und wurden nie in ein Matrix-Backup hochgeladen.
• Vorgehen: Rechnen Sie damit, dass ein Teil der alten verschlüsselten Historie nicht verfügbar bleibt, sofern Sie diese Schlüssel nicht manuell von einem anderen verifizierten Client wiederherstellen können.

• Bedeutung: Ein Backup ist vorhanden, aber OpenClaw konnte den Wiederherstellungsschlüssel nicht automatisch wiederherstellen.
• Vorgehen: Führen Sie printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin aus.

• Bedeutung: OpenClaw hat den alten verschlüsselten Speicher gefunden, konnte ihn aber nicht sicher genug prüfen, um die Wiederherstellung vorzubereiten.
• Vorgehen: Führen Sie openclaw doctor --fix erneut aus. Wenn sich der Fehler wiederholt, lassen Sie das alte Zustandsverzeichnis intakt und stellen Sie mit einem anderen verifizierten Matrix-Client plus printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin wieder her.

• Bedeutung: OpenClaw hat einen Konflikt bei Backup-Schlüsseln erkannt und sich geweigert, die aktuelle Recovery-Key-Datei automatisch zu überschreiben.
• Vorgehen: Prüfen Sie, welcher Wiederherstellungsschlüssel korrekt ist, bevor Sie einen Wiederherstellungsbefehl erneut versuchen.

• Bedeutung: Dies ist die harte Grenze des alten Speicherformats.
• Vorgehen: Gesicherte Schlüssel können weiterhin wiederhergestellt werden, aber rein lokale verschlüsselte Historie bleibt möglicherweise nicht verfügbar.

• Bedeutung: Das neue Plugin hat die Wiederherstellung versucht, aber Matrix hat einen Fehler zurückgegeben.
• Vorgehen: Führen Sie openclaw matrix verify backup status aus, und versuchen Sie es bei Bedarf erneut mit printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin.

​

Manuelle Wiederherstellungsmeldungen

• Bedeutung: OpenClaw weiß, dass Sie einen Backup-Schlüssel haben sollten, aber er ist auf diesem Gerät nicht aktiv.
• Vorgehen: Führen Sie openclaw matrix verify backup restore aus, oder setzen Sie bei Bedarf MATRIX_RECOVERY_KEY und führen Sie printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin aus.

• Bedeutung: Auf diesem Gerät ist derzeit kein Wiederherstellungsschlüssel gespeichert.
• Vorgehen: Setzen Sie MATRIX_RECOVERY_KEY, führen Sie printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin aus, und stellen Sie dann das Backup wieder her.

• Bedeutung: Der gespeicherte Schlüssel stimmt nicht mit dem aktiven Matrix-Backup überein.
• Vorgehen: Setzen Sie MATRIX_RECOVERY_KEY auf den richtigen Schlüssel und führen Sie printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin aus.

• Bedeutung: Das Backup ist vorhanden, aber dieses Gerät vertraut der Cross-Signing-Kette noch nicht stark genug.
• Vorgehen: Setzen Sie MATRIX_RECOVERY_KEY und führen Sie printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin aus.

• Bedeutung: Sie haben einen Wiederherstellungsschritt versucht, ohne einen erforderlichen Wiederherstellungsschlüssel bereitzustellen.
• Vorgehen: Führen Sie den Befehl erneut mit --recovery-key-stdin aus, zum Beispiel printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin.

• Bedeutung: Der bereitgestellte Schlüssel konnte nicht geparst werden oder entsprach nicht dem erwarteten Format.
• Vorgehen: Versuchen Sie es erneut mit dem exakten Wiederherstellungsschlüssel aus Ihrem Matrix-Client oder Ihrer Recovery-Key-Datei.

• Bedeutung: OpenClaw konnte den Wiederherstellungsschlüssel anwenden, aber Matrix hat weiterhin kein vollständiges Cross-Signing-Identitätsvertrauen für dieses Gerät hergestellt. Prüfen Sie die Befehlsausgabe auf Recovery key accepted, Backup usable, Cross-signing verified und Device verified by owner.
• Vorgehen: Führen Sie openclaw matrix verify self aus, akzeptieren Sie die Anfrage in einem anderen Matrix-Client, vergleichen Sie den SAS und geben Sie yes nur ein, wenn er übereinstimmt. Der Befehl wartet auf vollständiges Matrix-Identitätsvertrauen, bevor er Erfolg meldet. Verwenden Sie printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify bootstrap --recovery-key-stdin --force-reset-cross-signing nur, wenn Sie die aktuelle Cross-Signing-Identität absichtlich ersetzen möchten.

• Bedeutung: Der Secret-Speicher hat auf diesem Gerät keine aktive Backup-Sitzung erzeugt.
• Vorgehen: Verifizieren Sie zuerst das Gerät, und prüfen Sie dann erneut mit openclaw matrix verify backup status.

• Bedeutung: Dieses Gerät kann erst aus dem Secret-Speicher wiederherstellen, wenn die Geräteverifizierung abgeschlossen ist.
• Vorgehen: Führen Sie zuerst printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin aus.

​

Meldungen zu benutzerdefinierten Plugin-Installationen

• Bedeutung: Ihr Plugin-Installationsdatensatz verweist auf einen lokalen Pfad, der nicht mehr existiert.
• Vorgehen: Installieren Sie mit openclaw plugins install @openclaw/matrix neu, oder, wenn Sie aus einem Repo-Checkout arbeiten, mit openclaw plugins install ./path/to/local/matrix-plugin.

​

Wenn die verschlüsselte Historie weiterhin nicht zurückkehrt

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

​

Wenn Sie für künftige Nachrichten neu beginnen möchten

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

​

Verwandt

• Matrix: Kanaleinrichtung und Konfiguration.
• Matrix-Push-Regeln: Benachrichtigungsrouting.
• Doctor: Zustandsprüfung und automatischer Migrationstrigger.
• Migrationsanleitung: alle Migrationspfade (Maschinenumzüge, systemübergreifende Importe).
• Plugins: Plugin-Installation und Registrierung.