Matrix-Migration

Aktualisieren Sie vom vorherigen öffentlichen matrix-Plugin auf die aktuelle Implementierung.

Für die meisten Benutzer erfolgt das Upgrade direkt:

• das Plugin bleibt @openclaw/matrix
• der Kanal bleibt matrix
• Ihre Konfiguration bleibt unter channels.matrix
• zwischengespeicherte Anmeldedaten werden in den gemeinsamen Plugin-Status state/openclaw.sqlite verschoben
• der Laufzeitstatus bleibt unter ~/.openclaw/matrix/

Sie müssen weder Konfigurationsschlüssel umbenennen noch das Plugin unter einem neuen Namen neu installieren. Das Root-Paket openclaw enthält weder Matrix-Laufzeitcode noch Abhängigkeiten des Matrix SDK mehr. Wenn openclaw channels status anzeigt, dass Matrix konfiguriert, das Plugin jedoch nicht installiert ist, führen Sie openclaw doctor --fix oder openclaw plugins install @openclaw/matrix aus; installieren Sie keine Matrix-SDK-Pakete im Root-Paket von OpenClaw.

Was die Migration automatisch erledigt

Die Matrix-Migration wird ausgeführt, wenn Sie openclaw doctor --fix ausführen. Dateibasierte Sidecars neben dem dedizierten Matrix-Speicher behalten ihren Fallback beim Clientstart bei, der Import von Anmeldedatendateien erfolgt jedoch ausschließlich durch Doctor; die Laufzeit liest nur den kanonischen SQLite-Anmeldedatenstatus.

Die Doctor-Migration umfasst:

• Importieren und Überprüfen eingestellter ~/.openclaw/credentials/matrix/credentials*.json-Dateien vor ihrer Archivierung
• Beibehalten derselben Kontoauswahl und channels.matrix-Konfiguration
• Importieren des dateibasierten Sidecar-Status (bot-storage.json-Synchronisierungscache, recovery-key.json, legacy-crypto-migration.json, IndexedDB-Snapshots) in den Matrix-SQLite-Status; migrierte Dateien werden mit dem Suffix .migrated archiviert
• Wiederverwenden des vollständigsten vorhandenen Speicherstammverzeichnisses für Token-Hashes für dasselbe Matrix-Konto, denselben Homeserver, Benutzer und dasselbe Gerät, wenn sich das Zugriffstoken später ändert

Upgrade von OpenClaw-Versionen vor 2026.4

Versionen bis einschließlich der 2026.6-Reihe migrierten außerdem das ursprüngliche flache Matrix-Layout mit einem einzigen Speicher (~/.openclaw/matrix/bot-storage.json plus ~/.openclaw/matrix/crypto/) und bereiteten die Wiederherstellung des verschlüsselten Status aus dem alten Rust-Kryptospeicher vor. Aktuelle Versionen enthalten diese Migration nicht mehr.

Wenn Sie eine Installation aktualisieren, die noch das flache Layout verwendet, führen Sie zunächst ein Upgrade auf eine 2026.6-Version durch, führen Sie openclaw doctor --fix aus und starten Sie das Gateway einmal, damit der flache Speicher und alle wiederherstellbaren Raumschlüssel migriert werden. Aktualisieren Sie anschließend auf die neueste Version.

Das vorherige öffentliche Matrix-Plugin erstellte nicht automatisch Sicherungen von Matrix-Raumschlüsseln. Wenn Ihre alte Installation ausschließlich lokal gespeicherten verschlüsselten Verlauf enthielt, der nie gesichert wurde, können einige ältere verschlüsselte Nachrichten nach dem Upgrade unabhängig vom Migrationspfad unlesbar bleiben.

Empfohlener Upgrade-Ablauf

1. Aktualisieren Sie OpenClaw und das Matrix-Plugin wie gewohnt.

2. Führen Sie Folgendes aus:

   openclaw doctor --fix

3. Starten Sie das Gateway oder starten Sie es neu.

4. Prüfen Sie den aktuellen Verifizierungs- und Sicherungsstatus:

   openclaw matrix verify statusopenclaw matrix verify backup status

5. Legen Sie den Wiederherstellungsschlüssel für das zu reparierende Matrix-Konto in einer kontospezifischen Umgebungsvariable ab. Für ein einzelnes Standardkonto ist MATRIX_RECOVERY_KEY ausreichend. Verwenden Sie für mehrere Konten jeweils eine Variable pro Konto, beispielsweise MATRIX_RECOVERY_KEY_ASSISTANT, und fügen Sie dem Befehl --account assistant hinzu.

6. Wenn OpenClaw meldet, dass ein Wiederherstellungsschlüssel erforderlich ist, führen Sie den Befehl für das entsprechende Konto aus:

   printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdinprintf '%s\n' "$MATRIX_RECOVERY_KEY_ASSISTANT" | openclaw matrix verify backup restore --recovery-key-stdin --account assistant

7. Wenn dieses Gerät weiterhin nicht verifiziert ist, führen Sie den Befehl für das entsprechende Konto aus:

   printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdinprintf '%s\n' "$MATRIX_RECOVERY_KEY_ASSISTANT" | openclaw matrix verify device --recovery-key-stdin --account assistant

   Wenn der Wiederherstellungsschlüssel akzeptiert wird und die Sicherung verwendbar ist, Cross-signing verified jedoch weiterhin no lautet, schließen Sie die Selbstverifizierung über einen 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 wartet auf vollständiges Vertrauen in die Matrix- Identität, bevor er Erfolg meldet.

8. Wenn Sie nicht wiederherstellbaren alten Verlauf bewusst aufgeben und eine neue Sicherungsbasis für zukünftige Nachrichten erstellen möchten, führen Sie Folgendes aus:

   openclaw matrix verify backup reset --yes

   Fügen Sie --rotate-recovery-key nur hinzu, wenn der alte Wiederherstellungsschlüssel die neue Sicherung nicht mehr entsperren soll.

9. Wenn noch keine serverseitige Schlüsselsicherung vorhanden ist, erstellen Sie eine für zukünftige Wiederherstellungen:

   openclaw matrix verify bootstrap

Häufige Meldungen und ihre Bedeutung

Failed migrating legacy Matrix client storage: ...

• Bedeutung: Der clientseitige Matrix-Fallback hat dateibasierten Sidecar-Status gefunden, der Import in SQLite ist jedoch fehlgeschlagen. OpenClaw macht abgeschlossene Verschiebungen rückgängig und bricht diesen Fallback ab, anstatt unbemerkt mit einem neuen Speicher zu starten.
• Vorgehensweise: Prüfen Sie Dateisystemberechtigungen oder Konflikte, lassen Sie den alten Status unverändert und versuchen Sie es nach Behebung des Fehlers erneut.

Matrix is installed from a custom path: ...

• Bedeutung: Matrix ist an eine pfadbasierte Installation gebunden, daher ersetzen reguläre Updates es nicht automatisch durch das standardmäßige Matrix-Paket.
• Vorgehensweise: Installieren Sie es mit openclaw plugins install @openclaw/matrix neu, wenn Sie zum standardmäßigen Matrix-Plugin zurückkehren möchten.

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

• Bedeutung: Der Installationseintrag Ihres Plugins verweist auf einen lokalen Pfad, der nicht mehr vorhanden ist.
• Vorgehensweise: Installieren Sie es mit openclaw plugins install @openclaw/matrix neu oder, wenn Sie aus einem Repository-Checkout arbeiten, mit openclaw plugins install ./path/to/local/matrix-plugin. openclaw doctor --fix kann außerdem die veralteten Verweise auf das Matrix-Plugin für Sie entfernen.

Meldungen zur manuellen Wiederherstellung

openclaw matrix verify status und openclaw matrix verify backup status geben eine Zeile Backup issue: sowie Hinweise zu Next steps: aus, wenn die Raumschlüsselsicherung auf diesem Gerät nicht fehlerfrei ist:

Weitere Wiederherstellungsfehler:

Matrix recovery key is required

• Bedeutung: Sie haben einen Wiederherstellungsschritt ohne Angabe eines erforderlichen Wiederherstellungsschlüssels versucht.
• Vorgehensweise: Führen Sie den Befehl erneut mit --recovery-key-stdin aus, beispielsweise printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin.

Invalid Matrix recovery key: ...

• Bedeutung: Der angegebene Schlüssel konnte nicht geparst werden oder entsprach nicht dem erwarteten Format.
• Vorgehensweise: Versuchen Sie es erneut mit dem exakten Wiederherstellungsschlüssel aus Ihrem Matrix-Client oder dem Export des Wiederherstellungsschlüssels.

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

• Bedeutung: Der Wiederherstellungsschlüssel hat verwendbares Sicherungsmaterial entsperrt, Matrix hat für dieses Gerät jedoch noch kein vollständiges Vertrauen in die Cross-Signing-Identität hergestellt. Prüfen Sie die Befehlsausgabe auf Recovery key accepted, Backup usable, Cross-signing verified und Device verified by owner.
• Vorgehensweise: Führen Sie openclaw matrix verify self aus, akzeptieren Sie die Anfrage in einem anderen Matrix-Client, vergleichen Sie die SAS und geben Sie yes nur ein, wenn sie übereinstimmt. 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 bewusst ersetzen möchten.

Wenn Sie den Verlust nicht wiederherstellbaren alten verschlüsselten Verlaufs akzeptieren, können Sie stattdessen die aktuelle Sicherungsbasis mit openclaw matrix verify backup reset --yes zurücksetzen. Wenn das gespeicherte Sicherungsgeheimnis beschädigt ist, repariert dieses Zurücksetzen auch den Geheimnisspeicher, damit der neue Sicherungsschlüssel nach dem Neustart korrekt geladen werden kann.

Wenn der verschlüsselte Verlauf weiterhin nicht wiederhergestellt wird

Führen Sie diese Prüfungen der Reihe nach aus:

openclaw matrix verify status --verboseopenclaw matrix verify backup status --verboseprintf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin --verbose

Wenn die Sicherung erfolgreich wiederhergestellt wird, in einigen alten Räumen aber weiterhin Verlauf fehlt, wurden diese fehlenden Schlüssel wahrscheinlich nie vom vorherigen Plugin gesichert.

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

Wenn Sie den Verlust nicht wiederherstellbaren alten verschlüsselten Verlaufs akzeptieren und künftig nur eine saubere Sicherungsbasis wünschen, führen Sie diese Befehle der Reihe nach aus:

openclaw matrix verify backup reset --yesopenclaw matrix verify backup status --verboseopenclaw matrix verify status

Wenn das Gerät danach weiterhin nicht verifiziert ist, schließen Sie die Verifizierung in Ihrem Matrix-Client ab, indem Sie die SAS-Emojis oder Dezimalcodes vergleichen und bestätigen, dass sie übereinstimmen.

Verwandte Themen

• Matrix: Kanaleinrichtung und Konfiguration.
• Matrix-Push-Regeln: Benachrichtigungsrouting.
• Doctor: Zustandsprüfung und automatischer Migrationsauslöser.
• Migrationsleitfaden: alle Migrationspfade (Rechnerumzüge, systemübergreifende Importe).
• Plugins: Installation und Registrierung von Plugins.