Matrix-migratie

• de plugin blijft @openclaw/matrix
• het kanaal blijft matrix
• je configuratie blijft onder channels.matrix
• gecachte referenties 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
• installaties via pakketbeheerders 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 voltooien
• als je openclaw update --no-restart gebruikt, wordt opstart-ondersteunde 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-referenties
• het behouden van dezelfde accountselectie en channels.matrix-configuratie
• het verplaatsen van de oudste platte Matrix-syncopslag naar de huidige account-gescopeerde locatie
• het verplaatsen van de oudste platte Matrix-crypto-opslag naar de huidige account-gescopeerde 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-crypto-opslag, wanneer die sleutel lokaal bestaat
• het hergebruiken van de meest volledige bestaande token-hash-opslagroot voor hetzelfde Matrix-account, dezelfde homeserver en dezelfde gebruiker wanneer het toegangstoken later verandert
• het scannen van sibling-token-hash-opslagroots op metadata voor herstel van versleutelde status in afwachting wanneer het Matrix-toegangstoken is gewijzigd maar de account-/apparaatidentiteit hetzelfde is gebleven
• het herstellen van geback-upte roomsleutels in de nieuwe crypto-opslag bij de volgende Matrix-start

• OpenClaw schrijft een markerbestand naar ~/.openclaw/matrix/migration-snapshot.json na een geslaagde snapshot, zodat latere opstart- en herstelpasses 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 omdat er geen uitvoerbare Matrix-mutatie 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-opslag (~/.openclaw/matrix/bot-storage.json en ~/.openclaw/matrix/crypto/) kwam uit een single-store-indeling, dus OpenClaw kan die alleen migreren naar een bepaald Matrix-accountdoel
• al account-gescopeerde legacy Matrix-opslag wordt per geconfigureerd Matrix-account gedetecteerd en voorbereid

​

Wat de migratie niet automatisch kan doen

• alleen lokaal aanwezige roomsleutels die 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-opslag wanneer meerdere Matrix-accounts zijn geconfigureerd maar channels.matrix.defaultAccount niet is ingesteld
• aangepaste pluginpadinstallaties die aan een repo-pad zijn vastgezet in plaats van aan het standaard Matrix-pakket
• een ontbrekende herstelsleutel wanneer de oude opslag geback-upte sleutels had maar de decryptiesleutel niet lokaal bewaarde

• aangepaste Matrix-pluginpadinstallaties worden gemeld door zowel het opstarten van de Gateway als openclaw doctor

​

Aanbevolen upgradeflow

1. Werk OpenClaw en de Matrix-plugin normaal bij. Geef de voorkeur aan gewone openclaw update zonder --no-restart, zodat het opstarten de Matrix-migratie direct kan voltooien.
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 herstelt 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 dan de opdracht uit voor het overeenkomende 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 dan de opdracht uit voor het overeenkomende 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 dan zelfverificatie vanuit een andere Matrix-client:
   openclaw matrix verify self
   
   Accepteer de aanvraag in een andere Matrix-client, vergelijk de emoji of decimalen, en typ alleen yes 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 dan uit:
   openclaw matrix verify backup reset --yes
   
9. Als er nog geen server-side sleutelback-up bestaat, maak er dan een aan 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-crypto-opslag via de actieve Matrix-plugininstallatie.
3. Als er een back-updecryptiesleutel wordt gevonden, schrijft OpenClaw die naar de nieuwe herstelsleutelflow en markeert roomsleutelherstel als in afwachting.
4. Bij de volgende Matrix-start herstelt OpenClaw geback-upte roomsleutels automatisch in de nieuwe crypto-opslag.

​

Veelvoorkomende berichten en wat ze betekenen

​

Upgrade- en detectieberichten

• Betekenis: de oude Matrix-status op schijf is gedetecteerd en naar de huidige indeling gemigreerd.
• 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 hebt bevestigd dat de migratie is geslaagd.

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

• Betekenis: oude Matrix-status bestaat, maar OpenClaw kan die niet aan een huidig Matrix-account koppelen omdat Matrix niet is geconfigureerd.
• Wat te doen: configureer channels.matrix en voer daarna openclaw doctor --fix opnieuw 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 een keer met een werkende Matrix-login, of voer openclaw doctor --fix opnieuw uit nadat gecachte referenties bestaan.

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

• Betekenis: de nieuwe account-gescopeerde locatie heeft al een sync- of crypto-opslag, dus OpenClaw heeft die niet automatisch overschreven.
• Wat te doen: controleer of 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 bestandssysteemmachtigingen en schijfstatus, en voer daarna openclaw doctor --fix opnieuw uit.

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

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

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

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

• Betekenis: OpenClaw heeft oude versleutelde Matrix-state gevonden, maar kon het helper-entrypoint uit de Matrix-Plugin dat die store normaal inspecteert niet laden.
• Wat te doen: installeer of herstel de Matrix-Plugin opnieuw (openclaw plugins install @openclaw/matrix, of openclaw plugins install ./path/to/local/matrix-plugin voor een repo-checkout), en voer daarna openclaw doctor --fix opnieuw uit of herstart de gateway.

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

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

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

• Betekenis: Matrix is vastgezet op een padinstallatie, dus mainline-updates vervangen het niet automatisch 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.

​

Herstelberichten voor versleutelde state

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

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

• Betekenis: er bestaat een back-up, 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 store gevonden, maar kon die niet veilig genoeg inspecteren om herstel voor te bereiden.
• Wat te doen: voer openclaw doctor --fix opnieuw uit. Als dit zich herhaalt, laat de oude state-directory 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 een back-upsleutel gedetecteerd en geweigerd het huidige recovery-key-bestand automatisch te overschrijven.
• Wat te doen: controleer welke herstelsleutel juist is voordat je een herstelopdracht opnieuw probeert.

• Betekenis: dit is de harde limiet van het oude opslagformaat.
• Wat te doen: geback-upte sleutels kunnen nog steeds worden hersteld, maar lokaal-only 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 die 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: dit apparaat heeft momenteel geen opgeslagen herstelsleutel.
• 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 op 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 geparsed of kwam niet overeen met de verwachte indeling.
• Wat te doen: probeer het opnieuw met de exacte herstelsleutel uit je Matrix-client of recovery-key-bestand.

• Betekenis: OpenClaw kon de herstelsleutel toepassen, maar Matrix heeft nog geen volledige 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 die 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: secret storage heeft op dit apparaat geen actieve back-upsessie opgeleverd.
• Wat te doen: verifieer eerst het apparaat en controleer daarna opnieuw met openclaw matrix verify backup status.

• Betekenis: dit apparaat kan pas herstellen vanuit secret storage nadat 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, openclaw plugins install ./path/to/local/matrix-plugin.

​

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: channel-instelling en configuratie.
• Matrix-pushregels: notificatierouting.
• Doctor: gezondheidscontrole en automatische migratietrigger.
• Migratiehandleiding: alle migratiepaden (machineverplaatsingen, cross-system imports).
• Plugins: plugininstallatie en registratie.