Matrix-migratie

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

• de plugin blijft @openclaw/matrix
• het kanaal blijft matrix
• je configuratie blijft onder channels.matrix
• gecachte inloggegevens blijven onder ~/.openclaw/credentials/matrix/
• runtime-status blijft onder ~/.openclaw/matrix/

​

Wat de migratie automatisch doet

• broninstallaties voeren openclaw doctor --fix uit tijdens de updateflow en herstarten daarna standaard de gateway
• package-manager-installaties werken het pakket bij, voeren een niet-interactieve doctor-pass uit en vertrouwen daarna op de standaard gateway-herstart zodat het opstarten de Matrix-migratie kan afronden
• als je openclaw update --no-restart gebruikt, wordt opstartondersteunde Matrix-migratie uitgesteld totdat je later openclaw doctor --fix uitvoert en de gateway herstart

• het aanmaken of hergebruiken van een pre-migratie-snapshot onder ~/Backups/openclaw-migrations/
• het hergebruiken van je gecachte Matrix-inloggegevens
• het behouden van dezelfde accountselectie en channels.matrix-configuratie
• het verplaatsen van de oudste platte Matrix-syncstore naar de huidige accountspecifieke locatie
• het verplaatsen van de oudste platte Matrix-cryptostore naar de huidige accountspecifieke locatie wanneer het doelaccount veilig kan worden bepaald
• het extraheren van een eerder opgeslagen decryptiesleutel voor Matrix-room-key-back-ups uit de oude rust-cryptostore, wanneer die sleutel lokaal bestaat
• het hergebruiken van de meest complete bestaande opslagroot met token-hash voor hetzelfde Matrix-account, dezelfde homeserver en dezelfde gebruiker wanneer de access token later wijzigt
• het scannen van naastliggende opslagroots met token-hash op metadata voor herstel van versleutelde status in afwachting wanneer de Matrix-access token is gewijzigd maar de account-/apparaatidentiteit gelijk is gebleven
• het herstellen van geback-upte room keys naar de nieuwe cryptostore bij de volgende Matrix-start

• OpenClaw schrijft een markerbestand naar ~/.openclaw/matrix/migration-snapshot.json na een succesvolle snapshot, zodat latere opstart- en reparatiepasses hetzelfde archief kunnen hergebruiken.
• Deze automatische Matrix-migratiesnapshots maken alleen een back-up van configuratie + status (includeWorkspace: false).
• Als Matrix alleen migratiestatus met waarschuwingen heeft, bijvoorbeeld omdat userId of accessToken nog ontbreekt, maakt OpenClaw de snapshot nog niet aan omdat er geen Matrix-mutatie uitvoerbaar is.
• Als de snapshotstap mislukt, slaat OpenClaw Matrix-migratie voor die run over in plaats van status te wijzigen zonder herstelpunt.

• de oudste platte Matrix-store (~/.openclaw/matrix/bot-storage.json en ~/.openclaw/matrix/crypto/) kwam uit een lay-out met een enkele store, dus OpenClaw kan die alleen migreren naar een Matrix-accountdoel dat is bepaald
• legacy Matrix-stores die al accountspecifiek zijn, worden per geconfigureerd Matrix-account gedetecteerd en voorbereid

​

Wat de migratie niet automatisch kan doen

• room keys die alleen lokaal bestonden en nooit zijn geback-upt
• versleutelde status wanneer het doel-Matrix-account nog niet kan worden bepaald omdat homeserver, userId of accessToken nog niet beschikbaar zijn
• automatische migratie van een gedeelde platte Matrix-store wanneer meerdere Matrix-accounts zijn geconfigureerd maar channels.matrix.defaultAccount niet is ingesteld
• aangepaste pluginpad-installaties die zijn vastgepind op een repo-pad in plaats van het standaard Matrix-pakket
• een ontbrekende herstelsleutel wanneer de oude store geback-upte sleutels had maar de decryptiesleutel niet lokaal bewaarde

• aangepaste Matrix-pluginpad-installaties worden weergegeven door zowel het opstarten van de gateway als openclaw doctor

​

Aanbevolen upgradeflow

1. Werk OpenClaw en de Matrix-plugin normaal bij. Gebruik bij voorkeur gewoon openclaw update zonder --no-restart, zodat het opstarten de Matrix-migratie direct kan afronden.
2. Voer uit:
   openclaw doctor --fix
   
   Als Matrix uitvoerbaar migratiewerk heeft, maakt doctor eerst de pre-migratie-snapshot aan of hergebruikt die, en drukt het archiefpad af.
3. Start of herstart de gateway.
4. Controleer de huidige verificatie- en back-upstatus:
   openclaw matrix verify status
   openclaw matrix verify backup status
   
5. Plaats de herstelsleutel voor het Matrix-account dat je repareert in een accountspecifieke omgevingsvariabele. Voor een enkel standaardaccount is MATRIX_RECOVERY_KEY prima. Gebruik voor meerdere accounts een variabele per account, bijvoorbeeld MATRIX_RECOVERY_KEY_ASSISTANT, en voeg --account assistant toe aan de opdracht.
6. Als OpenClaw aangeeft dat een herstelsleutel nodig is, voer je de opdracht uit voor het bijbehorende account:
   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. Als dit apparaat nog steeds niet is geverifieerd, voer je de opdracht uit voor het bijbehorende account:
   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
   
   Als de herstelsleutel wordt geaccepteerd en de back-up bruikbaar is, maar Cross-signing verified nog steeds no is, voltooi je zelfverificatie vanuit een andere Matrix-client:
   openclaw matrix verify self
   
   Accepteer het verzoek in een andere Matrix-client, vergelijk de emoji of decimalen, en typ yes alleen wanneer ze overeenkomen. De opdracht sluit alleen succesvol af nadat Cross-signing verified yes wordt.
8. Als je bewust onherstelbare oude geschiedenis opgeeft en een nieuwe back-upbasislijn voor toekomstige berichten wilt, voer je uit:
   openclaw matrix verify backup reset --yes
   
9. Als er nog geen serverside sleutelback-up bestaat, maak er dan een voor toekomstige herstelacties:
   openclaw matrix verify bootstrap
   

​

Hoe versleutelde migratie werkt

1. Opstarten of openclaw doctor --fix maakt de pre-migratie-snapshot aan of hergebruikt die als versleutelde migratie uitvoerbaar is.
2. Opstarten of openclaw doctor --fix inspecteert de oude Matrix-cryptostore via de actieve Matrix-plugininstallatie.
3. Als een back-updecryptiesleutel wordt gevonden, schrijft OpenClaw die naar de nieuwe herstelsleutelflow en markeert room-key-herstel als in behandeling.
4. Bij de volgende Matrix-start herstelt OpenClaw geback-upte room keys automatisch naar de nieuwe cryptostore.

​

Veelvoorkomende berichten en wat ze betekenen

​

Upgrade- en detectieberichten

• Betekenis: de oude Matrix-status op schijf is gedetecteerd en gemigreerd naar de huidige lay-out.
• Wat te doen: niets, tenzij dezelfde uitvoer ook waarschuwingen bevat.

• Betekenis: OpenClaw heeft een herstelarchief aangemaakt voordat Matrix-status werd gewijzigd.
• Wat te doen: bewaar het afgedrukte archiefpad totdat je bevestigt dat de migratie is geslaagd.

• Betekenis: OpenClaw heeft een bestaande Matrix-migratiesnapshotmarker gevonden en dat archief hergebruikt in plaats van een dubbele back-up te maken.
• Wat te doen: bewaar het afgedrukte archiefpad totdat je bevestigt dat de migratie is geslaagd.

• Betekenis: oude Matrix-status bestaat, maar OpenClaw kan die niet koppelen aan een huidig Matrix-account omdat Matrix niet is geconfigureerd.
• Wat te doen: configureer channels.matrix en voer daarna opnieuw openclaw doctor --fix uit of herstart de gateway.

• Betekenis: OpenClaw heeft oude status gevonden, maar kan de exacte huidige account-/apparaatroot nog steeds niet bepalen.
• Wat te doen: start de gateway eenmaal met een werkende Matrix-login, of voer openclaw doctor --fix opnieuw uit nadat gecachte inloggegevens bestaan.

• Betekenis: OpenClaw heeft een gedeelde platte Matrix-store gevonden, maar weigert te raden welk benoemd Matrix-account die moet ontvangen.
• Wat te doen: stel channels.matrix.defaultAccount in op het bedoelde account en voer daarna opnieuw openclaw doctor --fix uit of herstart de gateway.

• Betekenis: de nieuwe accountspecifieke locatie heeft al een sync- of cryptostore, dus OpenClaw heeft die niet automatisch overschreven.
• Wat te doen: verifieer dat het huidige account het juiste is voordat je het conflicterende doel handmatig verwijdert of verplaatst.

• Betekenis: OpenClaw probeerde oude Matrix-status te verplaatsen, maar de bestandssysteembewerking is mislukt.
• Wat te doen: inspecteer bestandssysteemrechten en schijfstatus en voer daarna opnieuw openclaw doctor --fix uit.

• Betekenis: OpenClaw heeft een oude versleutelde Matrix-store gevonden, maar er is geen huidige Matrix-configuratie om die aan te koppelen.
• Wat te doen: configureer channels.matrix en voer daarna opnieuw openclaw doctor --fix uit of herstart de gateway.

• Betekenis: de versleutelde store bestaat, maar OpenClaw kan niet veilig bepalen bij welk huidig account/apparaat die hoort.
• Wat te doen: start de gateway eenmaal met een werkende Matrix-login, of voer openclaw doctor --fix opnieuw uit nadat gecachte inloggegevens beschikbaar zijn.

• Betekenis: OpenClaw heeft een gedeelde platte legacy-cryptostore gevonden, maar weigert te raden welk benoemd Matrix-account die moet ontvangen.
• Wat te doen: stel channels.matrix.defaultAccount in op het bedoelde account en voer daarna opnieuw openclaw doctor --fix uit of herstart de gateway.

• Betekenis: OpenClaw heeft oude Matrix-status gedetecteerd, maar de migratie wordt nog geblokkeerd door ontbrekende identiteits- of inloggegevens.
• Wat te doen: voltooi Matrix-login of configuratie-instelling en voer daarna opnieuw openclaw doctor --fix uit of herstart de gateway.

• Betekenis: OpenClaw heeft oude versleutelde Matrix-status gevonden, maar kon het helper-entrypoint niet laden uit de Matrix-plugin die deze opslag normaal inspecteert.
• Wat te doen: installeer of repareer de Matrix-plugin opnieuw (openclaw plugins install @openclaw/matrix, of openclaw plugins install ./path/to/local/matrix-plugin voor een repo-checkout), voer daarna openclaw doctor --fix opnieuw uit of start de gateway opnieuw.
• Als npm het OpenClaw-eigendom Matrix-pakket als verouderd meldt, gebruik dan de meegeleverde plugin uit een huidige verpakte OpenClaw-build of het lokale checkout-pad totdat een nieuwer npm-pakket is gepubliceerd.

• Betekenis: OpenClaw heeft een helperbestandspad gevonden dat buiten de plugin-root valt of niet door de plugin-grenscontroles komt, dus heeft het geweigerd dit te importeren.
• Wat te doen: installeer de Matrix-plugin opnieuw vanaf een vertrouwd pad, voer daarna openclaw doctor --fix opnieuw uit of start de gateway opnieuw.

• Betekenis: OpenClaw heeft geweigerd Matrix-status te wijzigen omdat het eerst geen herstelsnapshot kon maken.
• Wat te doen: los de back-upfout op en voer daarna openclaw doctor --fix opnieuw uit of start de gateway opnieuw.

• Betekenis: de client-side Matrix-fallback heeft oude platte opslag gevonden, maar het verplaatsen is mislukt. OpenClaw breekt die fallback nu af in plaats van stilzwijgend met een nieuwe opslag te starten.
• Wat te doen: inspecteer bestandssysteemrechten of conflicten, houd de oude status intact en probeer opnieuw nadat de fout is opgelost.

• Betekenis: Matrix is vastgezet op een padinstallatie, waardoor mainline-updates het niet automatisch vervangen door het standaard Matrix-pakket van de repo.
• Wat te doen: installeer opnieuw met openclaw plugins install @openclaw/matrix wanneer je wilt terugkeren naar de standaard Matrix-plugin.
• Als npm het OpenClaw-eigendom Matrix-pakket als verouderd meldt, gebruik dan de meegeleverde plugin uit een huidige verpakte OpenClaw-build totdat een nieuwer npm-pakket is gepubliceerd.

​

Herstelberichten voor versleutelde status

• Betekenis: geback-upte kamersleutels zijn succesvol hersteld naar de nieuwe crypto-opslag.
• Wat te doen: meestal niets.

• Betekenis: sommige oude kamersleutels bestonden alleen in de oude lokale opslag en waren nooit geüpload naar de Matrix-back-up.
• Wat te doen: verwacht dat een deel van de oude versleutelde geschiedenis niet beschikbaar blijft, tenzij je die sleutels handmatig kunt herstellen vanaf een andere geverifieerde client.

• Betekenis: de back-up bestaat, maar OpenClaw kon de herstelsleutel niet automatisch herstellen.
• Wat te doen: voer printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin uit.

• Betekenis: OpenClaw heeft de oude versleutelde opslag gevonden, maar kon deze niet veilig genoeg inspecteren om herstel voor te bereiden.
• Wat te doen: voer openclaw doctor --fix opnieuw uit. Als dit zich herhaalt, houd dan de oude statusdirectory intact en herstel met een andere geverifieerde Matrix-client plus printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin.

• Betekenis: OpenClaw heeft een conflict met back-upsleutels gedetecteerd en heeft geweigerd het huidige recovery-key-bestand automatisch te overschrijven.
• Wat te doen: verifieer welke herstelsleutel correct is voordat je een herstelopdracht opnieuw probeert.

• Betekenis: dit is de harde limiet van de oude opslagindeling.
• Wat te doen: geback-upte sleutels kunnen nog steeds worden hersteld, maar lokaal versleutelde geschiedenis kan onbeschikbaar blijven.

• Betekenis: de nieuwe plugin heeft herstel geprobeerd, maar Matrix gaf een fout terug.
• Wat te doen: voer openclaw matrix verify backup status uit en probeer daarna zo nodig opnieuw met printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin.

​

Handmatige herstelberichten

• Betekenis: OpenClaw weet dat je een back-upsleutel zou moeten hebben, maar deze is niet actief op dit apparaat.
• Wat te doen: voer openclaw matrix verify backup restore uit, of stel MATRIX_RECOVERY_KEY in en voer zo nodig printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin uit.

• Betekenis: op dit apparaat is momenteel geen herstelsleutel opgeslagen.
• Wat te doen: stel MATRIX_RECOVERY_KEY in, voer printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin uit en herstel daarna de back-up.

• Betekenis: de opgeslagen sleutel komt niet overeen met de actieve Matrix-back-up.
• Wat te doen: stel MATRIX_RECOVERY_KEY in op de juiste sleutel en voer printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin uit.

• Betekenis: de back-up bestaat, maar dit apparaat vertrouwt de cross-signing-keten nog niet sterk genoeg.
• Wat te doen: stel MATRIX_RECOVERY_KEY in en voer printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin uit.

• Betekenis: je hebt een herstelstap geprobeerd zonder een herstelsleutel mee te geven terwijl die vereist was.
• Wat te doen: voer de opdracht opnieuw uit met --recovery-key-stdin, bijvoorbeeld printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin.

• Betekenis: de opgegeven sleutel kon niet worden geparseerd of kwam niet overeen met de verwachte indeling.
• Wat te doen: probeer opnieuw met de exacte herstelsleutel uit je Matrix-client of recovery-key-bestand.

• Betekenis: OpenClaw kon de herstelsleutel toepassen, maar Matrix heeft nog geen volledig cross-signing-identiteitsvertrouwen voor dit apparaat vastgesteld. Controleer de opdrachtuitvoer op Recovery key accepted, Backup usable, Cross-signing verified en Device verified by owner.
• Wat te doen: voer openclaw matrix verify self uit, accepteer het verzoek in een andere Matrix-client, vergelijk de SAS en typ alleen yes wanneer deze overeenkomt. De opdracht wacht op volledig Matrix-identiteitsvertrouwen voordat succes wordt gemeld. Gebruik printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify bootstrap --recovery-key-stdin --force-reset-cross-signing alleen wanneer je bewust de huidige cross-signing-identiteit wilt vervangen.

• Betekenis: geheime opslag heeft geen actieve back-upsessie op dit apparaat opgeleverd.
• Wat te doen: verifieer eerst het apparaat en controleer daarna opnieuw met openclaw matrix verify backup status.

• Betekenis: dit apparaat kan niet herstellen vanuit geheime opslag totdat apparaatverificatie is voltooid.
• Wat te doen: voer eerst printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin uit.

​

Berichten voor aangepaste plugininstallatie

• Betekenis: je plugininstallatierecord verwijst naar een lokaal pad dat verdwenen is.
• Wat te doen: installeer opnieuw met openclaw plugins install @openclaw/matrix, of, als je vanuit een repo-checkout werkt, met openclaw plugins install ./path/to/local/matrix-plugin.
• Als npm het OpenClaw-eigendom Matrix-pakket als verouderd meldt, gebruik dan de meegeleverde plugin uit een huidige verpakte OpenClaw-build of het lokale checkout-pad totdat een nieuwer npm-pakket is gepubliceerd.

​

Als versleutelde geschiedenis nog steeds niet terugkomt

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

​

Als je opnieuw wilt beginnen voor toekomstige berichten

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

​

Gerelateerd

• Matrix: kanaalconfiguratie en instellingen.
• Matrix-pushregels: routering van meldingen.
• Doctor: statuscontrole en trigger voor automatische migratie.
• Migratiehandleiding: alle migratiepaden (machineverplaatsingen, imports tussen systemen).
• Plugins: installatie en registratie van plugins.