​

Matrix-Migration

• das Plugin bleibt @openclaw/matrix
• der Kanal bleibt matrix
• Ihre Konfiguration bleibt unter channels.matrix
• gecachte Anmeldeinformationen bleiben unter ~/.openclaw/credentials/matrix/
• der Laufzeitstatus bleibt unter ~/.openclaw/matrix/

​

Was die Migration automatisch macht

• Source-Installationen führen während des Update-Ablaufs openclaw doctor --fix aus und starten dann standardmäßig das Gateway neu
• Installationen über Paketmanager aktualisieren das Paket, führen einen nicht interaktiven Doctor-Durchlauf aus und verlassen sich dann auf den standardmäßigen Neustart des Gateways, damit der Matrix-Migrationsstart abgeschlossen werden 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 das Gateway neu starten

• Erstellen oder Wiederverwenden eines Snapshots vor der Migration unter ~/Backups/openclaw-migrations/
• Wiederverwenden Ihrer gecachten Matrix-Anmeldeinformationen
• Beibehalten derselben Account-Auswahl und Konfiguration channels.matrix
• Verschieben des ältesten flachen Matrix-Sync-Stores in den aktuellen accountbezogenen Speicherort
• Verschieben des ältesten flachen Matrix-Crypto-Stores in den aktuellen accountbezogenen Speicherort, wenn der Ziel-Account sicher aufgelöst werden kann
• Extrahieren eines zuvor gespeicherten Entschlüsselungsschlüssels für Matrix-Room-Key-Backups aus dem alten Rust-Crypto-Store, wenn dieser Schlüssel lokal vorhanden ist
• Wiederverwenden der vollständigsten vorhandenen Token-Hash-Speicherwurzel für denselben Matrix-Account, Homeserver und Benutzer, wenn sich das Access-Token später ändert
• Durchsuchen benachbarter Token-Hash-Speicherwurzeln nach ausstehenden Wiederherstellungsmetadaten für verschlüsselten Status, wenn sich das Matrix-Access-Token geändert hat, die Account-/Geräteidentität aber gleich geblieben ist
• Wiederherstellen gesicherter Room Keys in den neuen Crypto-Store beim nächsten Matrix-Start

• OpenClaw schreibt nach einem erfolgreichen Snapshot eine Marker-Datei unter ~/.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 + Status (includeWorkspace: false).
• Wenn Matrix nur warnungsbezogenen Migrationsstatus 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 den Status ohne Wiederherstellungspunkt zu verändern.

• 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 ihn nur in ein aufgelöstes Ziel eines Matrix-Accounts migrieren
• bereits accountbezogene Legacy-Matrix-Stores werden pro konfiguriertem Matrix-Account erkannt und vorbereitet

​

Was die Migration nicht automatisch tun kann

• nur lokal vorhandene Room Keys, die nie gesichert wurden
• verschlüsselten 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 über benutzerdefinierte Plugin-Pfade, die an einen Repo-Pfad statt an das Standard-Matrix-Paket gebunden sind
• einen fehlenden Recovery Key, wenn der alte Store gesicherte Keys hatte, den Entschlüsselungsschlüssel aber nicht lokal behalten hat

• Installationen über benutzerdefinierte Matrix-Plugin-Pfade werden sowohl beim Gateway-Start als auch durch openclaw doctor angezeigt

​

Empfohlener Upgrade-Ablauf

1. Aktualisieren Sie OpenClaw und das Matrix-Plugin normal. 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 oder verwendet Doctor zuerst den Snapshot vor der Migration erneut und gibt den Archivpfad aus.
3. Starten oder starten Sie das Gateway neu.
4. Prüfen Sie den aktuellen Verifizierungs- und Backup-Status:
   openclaw matrix verify status
   openclaw matrix verify backup status
   
5. Wenn OpenClaw Ihnen mitteilt, dass ein Recovery Key benötigt wird, führen Sie aus:
   openclaw matrix verify backup restore --recovery-key "<your-recovery-key>"
   
6. Wenn dieses Gerät noch nicht verifiziert ist, führen Sie aus:
   openclaw matrix verify device "<your-recovery-key>"
   
7. Wenn Sie absichtlich nicht wiederherstellbaren alten Verlauf aufgeben und eine frische Backup-Basis für zukünftige Nachrichten wollen, führen Sie aus:
   openclaw matrix verify backup reset --yes
   
8. Wenn noch kein serverseitiges Key-Backup existiert, erstellen Sie eines für zukünftige Wiederherstellungen:
   openclaw matrix verify bootstrap
   

​

Wie die Migration verschlüsselter Daten funktioniert

1. Start oder openclaw doctor --fix erstellt oder verwendet den Snapshot vor der Migration erneut, wenn die Migration verschlüsselter Daten ausführbar ist.
2. Start oder openclaw doctor --fix untersucht den alten Matrix-Crypto-Store über die aktive Installation des Matrix-Plugins.
3. Wenn ein Entschlüsselungsschlüssel für das Backup gefunden wird, schreibt OpenClaw ihn in den neuen Recovery-Key-Ablauf und markiert die Wiederherstellung von Room Keys als ausstehend.
4. Beim nächsten Matrix-Start stellt OpenClaw gesicherte Room Keys automatisch in den neuen Crypto-Store wieder her.

​

Häufige Meldungen und ihre Bedeutung

​

Upgrade- und Erkennungsmeldungen

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

• 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 Marker für einen Matrix-Migrations-Snapshot gefunden und dieses Archiv wiederverwendet, 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 existiert, aber OpenClaw kann ihn keinem aktuellen Matrix-Account zuordnen, weil Matrix nicht konfiguriert ist.
• Was zu tun ist: Konfigurieren Sie channels.matrix, und führen Sie dann openclaw doctor --fix erneut aus oder starten Sie das Gateway neu.

• Bedeutung: OpenClaw hat alten Status gefunden, kann aber die genaue aktuelle Account-/Gerätewurzel noch nicht bestimmen.
• Was zu tun ist: Starten Sie das Gateway einmal mit einem funktionierenden Matrix-Login oder führen Sie openclaw doctor --fix erneut aus, nachdem gecachte Anmeldeinformationen vorhanden sind.

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

• Bedeutung: Der neue accountbezogene Speicherort hat bereits einen Sync- oder Crypto-Store, daher hat OpenClaw ihn nicht automatisch überschrieben.
• Was zu tun ist: Verifizieren Sie, dass der aktuelle Account der richtige ist, bevor Sie das kollidierende 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 den Plattenstatus und führen Sie dann openclaw doctor --fix erneut aus.

• Bedeutung: OpenClaw hat einen alten verschlüsselten Matrix-Store 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 openclaw doctor --fix erneut aus oder starten Sie das Gateway neu.

• Bedeutung: Der verschlüsselte Store existiert, aber OpenClaw kann noch nicht sicher entscheiden, zu welchem aktuellen Account/Gerät er gehört.
• Was zu tun ist: Starten Sie das Gateway einmal mit einem funktionierenden Matrix-Login oder führen Sie openclaw doctor --fix erneut aus, nachdem gecachte Anmeldeinformationen verfügbar sind.

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

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

• Bedeutung: OpenClaw hat alten verschlüsselten Matrix-Status gefunden, konnte aber den Hilfseinstiegspunkt aus dem Matrix-Plugin, der diesen Store normalerweise untersucht, nicht laden.
• Was zu tun ist: Installieren Sie das Matrix-Plugin erneut oder reparieren Sie es (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 das Gateway neu.

• Bedeutung: OpenClaw hat einen unsicheren Hilfsdateipfad gefunden, der die Plugin-Wurzel verlässt oder Prüfungen an der Plugin-Grenze nicht besteht, und hat daher den Import verweigert.
• Was zu tun ist: Installieren Sie das Matrix-Plugin aus einem vertrauenswürdigen Pfad erneut und führen Sie dann openclaw doctor --fix erneut aus oder starten Sie das Gateway neu.

• Bedeutung: OpenClaw hat sich geweigert, Matrix-Status zu verändern, weil zuerst kein Wiederherstellungs-Snapshot erstellt werden konnte.
• Was zu tun ist: Beheben Sie den Backup-Fehler und führen Sie dann openclaw doctor --fix erneut aus oder starten Sie das 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 Store zu starten.
• Was zu tun ist: Prüfen Sie Dateisystemberechtigungen oder Konflikte, lassen Sie den alten Status intakt und versuchen Sie es nach der Fehlerbehebung erneut.

• Bedeutung: Matrix ist an eine Installation über einen Pfad gebunden, sodass Mainline-Updates es nicht automatisch durch das Standard-Matrix-Paket des Repos ersetzen.
• Was zu tun ist: Installieren Sie mit openclaw plugins install @openclaw/matrix erneut, wenn Sie zum Standard-Matrix-Plugin zurückkehren möchten.

​

Meldungen zur Wiederherstellung verschlüsselter Daten

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

• Bedeutung: Einige alte Room Keys existierten nur im alten lokalen Store und waren nie in das Matrix-Backup hochgeladen worden.
• Was zu tun ist: Rechnen Sie damit, dass ein Teil des alten verschlüsselten Verlaufs nicht verfügbar bleibt, sofern Sie diese Keys nicht manuell von einem anderen verifizierten Client wiederherstellen können.

• Bedeutung: Es gibt ein Backup, aber OpenClaw konnte den Recovery Key nicht automatisch wiederherstellen.
• Was zu tun ist: Führen Sie openclaw matrix verify backup restore --recovery-key "<your-recovery-key>" aus.

• Bedeutung: OpenClaw hat den alten verschlüsselten Store gefunden, konnte ihn aber nicht sicher genug untersuchen, um die Wiederherstellung vorzubereiten.
• Was zu tun ist: Führen Sie openclaw doctor --fix erneut aus. Wenn sich das wiederholt, lassen Sie das alte Statusverzeichnis intakt und stellen Sie mithilfe eines anderen verifizierten Matrix-Clients plus openclaw matrix verify backup restore --recovery-key "<your-recovery-key>" wieder her.

• Bedeutung: OpenClaw hat einen Konflikt beim Backup-Key erkannt und sich geweigert, die aktuelle Datei mit dem Recovery Key automatisch zu überschreiben.
• Was zu tun ist: Verifizieren Sie, welcher Recovery Key korrekt ist, bevor Sie einen Wiederherstellungsbefehl erneut ausführen.

• Bedeutung: Das ist die harte Grenze des alten Speicherformats.
• Was zu tun ist: Gesicherte Keys können weiterhin wiederhergestellt werden, aber nur lokal vorhandener verschlüsselter Verlauf bleibt möglicherweise nicht verfügbar.

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

​

Meldungen zur manuellen Wiederherstellung

• Bedeutung: OpenClaw weiß, dass Sie einen Backup-Key haben sollten, aber er ist auf diesem Gerät nicht aktiv.
• Was zu tun ist: Führen Sie openclaw matrix verify backup restore aus oder übergeben Sie bei Bedarf --recovery-key.

• Bedeutung: Dieses Gerät hat den Recovery Key derzeit nicht gespeichert.
• Was zu tun ist: Verifizieren Sie das Gerät zuerst mit Ihrem Recovery Key und stellen Sie dann das Backup wieder her.

• Bedeutung: Der gespeicherte Key stimmt nicht mit dem aktiven Matrix-Backup überein.
• Was zu tun ist: Führen Sie openclaw matrix verify device "<your-recovery-key>" erneut mit dem richtigen Key aus.

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

• Bedeutung: Sie haben einen Wiederherstellungsschritt versucht, ohne einen erforderlichen Recovery Key anzugeben.
• Was zu tun ist: Führen Sie den Befehl erneut mit Ihrem Recovery Key aus.

• Bedeutung: Der angegebene Key konnte nicht geparst werden oder entsprach nicht dem erwarteten Format.
• Was zu tun ist: Versuchen Sie es erneut mit dem exakten Recovery Key aus Ihrem Matrix-Client oder Ihrer Recovery-Key-Datei.

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

• Bedeutung: Secret Storage hat auf diesem Gerät keine aktive Backup-Sitzung erzeugt.
• Was zu tun ist: Verifizieren Sie das Gerät zuerst und prüfen Sie dann erneut mit openclaw matrix verify backup status.

• Bedeutung: Dieses Gerät kann erst aus Secret Storage wiederherstellen, wenn die Geräteverifizierung abgeschlossen ist.
• Was zu tun ist: Führen Sie zuerst openclaw matrix verify device "<your-recovery-key>" aus.

​

Meldungen zu benutzerdefinierten Plugin-Installationen

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

​

Wenn verschlüsselter Verlauf weiterhin nicht zurückkommt

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

​

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

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

​

Verwandte Seiten

• Matrix
• Doctor
• Migrating
• Plugins