Migration de Matrix

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.

• le plugin reste @openclaw/matrix
• le canal reste matrix
• votre configuration reste sous channels.matrix
• les identifiants mis en cache restent sous ~/.openclaw/credentials/matrix/
• l’état d’exécution reste sous ~/.openclaw/matrix/

​

Ce que la migration fait automatiquement

• les installations depuis les sources exécutent openclaw doctor --fix pendant le flux de mise à jour, puis redémarrent le Gateway par défaut
• les installations via gestionnaire de paquets mettent à jour le paquet, exécutent une passe doctor non interactive, puis s’appuient sur le redémarrage par défaut du Gateway afin que le démarrage puisse terminer la migration Matrix
• si vous utilisez openclaw update --no-restart, la migration Matrix prise en charge au démarrage est différée jusqu’à ce que vous exécutiez plus tard openclaw doctor --fix et redémarriez le Gateway

• la création ou la réutilisation d’un instantané pré-migration sous ~/Backups/openclaw-migrations/
• la réutilisation de vos identifiants Matrix mis en cache
• la conservation de la même sélection de compte et de la configuration channels.matrix
• le déplacement du plus ancien magasin de synchronisation Matrix plat vers l’emplacement actuel scoped par compte
• le déplacement du plus ancien magasin crypto Matrix plat vers l’emplacement actuel scoped par compte quand le compte cible peut être résolu en toute sécurité
• l’extraction d’une clé de déchiffrement de sauvegarde de clés de salon Matrix précédemment enregistrée depuis l’ancien magasin crypto rust, quand cette clé existe localement
• la réutilisation de la racine de stockage par hachage de jeton existante la plus complète pour le même compte Matrix, homeserver et utilisateur quand le jeton d’accès change plus tard
• l’analyse des racines de stockage par hachage de jeton voisines à la recherche de métadonnées de restauration d’état chiffré en attente quand le jeton d’accès Matrix a changé mais que l’identité du compte/appareil est restée la même
• la restauration des clés de salon sauvegardées dans le nouveau magasin crypto au prochain démarrage Matrix

• OpenClaw écrit un fichier marqueur à ~/.openclaw/matrix/migration-snapshot.json après un instantané réussi afin que les passes ultérieures de démarrage et de réparation puissent réutiliser la même archive.
• Ces instantanés automatiques de migration Matrix sauvegardent uniquement la configuration et l’état (includeWorkspace: false).
• Si Matrix ne présente qu’un état de migration avec avertissements, par exemple parce que userId ou accessToken manque encore, OpenClaw ne crée pas encore l’instantané, car aucune mutation Matrix n’est exploitable.
• Si l’étape d’instantané échoue, OpenClaw ignore la migration Matrix pour cette exécution au lieu de modifier l’état sans point de récupération.

• le plus ancien magasin Matrix plat (~/.openclaw/matrix/bot-storage.json et ~/.openclaw/matrix/crypto/) provenait d’une disposition à magasin unique, donc OpenClaw ne peut le migrer que vers une seule cible de compte Matrix résolue
• les anciens magasins Matrix déjà scoped par compte sont détectés et préparés pour chaque compte Matrix configuré

​

Ce que la migration ne peut pas faire automatiquement

• les clés de salon locales uniquement qui n’ont jamais été sauvegardées
• l’état chiffré quand le compte Matrix cible ne peut pas encore être résolu parce que homeserver, userId ou accessToken sont encore indisponibles
• la migration automatique d’un magasin Matrix plat partagé quand plusieurs comptes Matrix sont configurés mais que channels.matrix.defaultAccount n’est pas défini
• les installations avec chemin de plugin personnalisé qui sont épinglées à un chemin de dépôt au lieu du paquet Matrix standard
• une clé de récupération manquante quand l’ancien magasin avait des clés sauvegardées mais n’a pas conservé la clé de déchiffrement localement

• les installations avec chemin de plugin Matrix personnalisé sont signalées à la fois par le démarrage du Gateway et par openclaw doctor

​

Flux de mise à niveau recommandé

1. Mettez à jour OpenClaw et le plugin Matrix normalement. Préférez un simple openclaw update sans --no-restart afin que le démarrage puisse terminer immédiatement la migration Matrix.
2. Exécutez :
   openclaw doctor --fix
   
   Si Matrix a un travail de migration exploitable, doctor créera ou réutilisera d’abord l’instantané pré-migration et affichera le chemin de l’archive.
3. Démarrez ou redémarrez le Gateway.
4. Vérifiez l’état actuel de la vérification et de la sauvegarde :
   openclaw matrix verify status
   openclaw matrix verify backup status
   
5. Placez la clé de récupération du compte Matrix que vous réparez dans une variable d’environnement propre au compte. Pour un seul compte par défaut, MATRIX_RECOVERY_KEY convient. Pour plusieurs comptes, utilisez une variable par compte, par exemple MATRIX_RECOVERY_KEY_ASSISTANT, et ajoutez --account assistant à la commande.
6. Si OpenClaw vous indique qu’une clé de récupération est nécessaire, exécutez la commande pour le compte correspondant :
   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. Si cet appareil n’est toujours pas vérifié, exécutez la commande pour le compte correspondant :
   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
   
   Si la clé de récupération est acceptée et que la sauvegarde est utilisable, mais que Cross-signing verified est toujours no, effectuez l’auto-vérification depuis un autre client Matrix :
   openclaw matrix verify self
   
   Acceptez la demande dans un autre client Matrix, comparez les émojis ou les décimales, et saisissez yes uniquement lorsqu’ils correspondent. La commande ne se termine avec succès qu’après que Cross-signing verified devient yes.
8. Si vous abandonnez volontairement l’ancien historique irrécupérable et voulez une nouvelle base de sauvegarde pour les futurs messages, exécutez :
   openclaw matrix verify backup reset --yes
   
9. Si aucune sauvegarde de clés côté serveur n’existe encore, créez-en une pour les récupérations futures :
   openclaw matrix verify bootstrap
   

​

Fonctionnement de la migration chiffrée

1. Le démarrage ou openclaw doctor --fix crée ou réutilise l’instantané pré-migration si la migration chiffrée est exploitable.
2. Le démarrage ou openclaw doctor --fix inspecte l’ancien magasin crypto Matrix via l’installation active du plugin Matrix.
3. Si une clé de déchiffrement de sauvegarde est trouvée, OpenClaw l’écrit dans le nouveau flux de clé de récupération et marque la restauration des clés de salon comme en attente.
4. Au prochain démarrage Matrix, OpenClaw restaure automatiquement les clés de salon sauvegardées dans le nouveau magasin crypto.

​

Messages courants et leur signification

​

Messages de mise à niveau et de détection

• Signification : l’ancien état Matrix sur disque a été détecté et migré vers la disposition actuelle.
• Que faire : rien, sauf si la même sortie contient aussi des avertissements.

• Signification : OpenClaw a créé une archive de récupération avant de modifier l’état Matrix.
• Que faire : conservez le chemin d’archive affiché jusqu’à confirmer que la migration a réussi.

• Signification : OpenClaw a trouvé un marqueur d’instantané de migration Matrix existant et a réutilisé cette archive au lieu de créer une sauvegarde dupliquée.
• Que faire : conservez le chemin d’archive affiché jusqu’à confirmer que la migration a réussi.

• Signification : un ancien état Matrix existe, mais OpenClaw ne peut pas le mapper à un compte Matrix actuel parce que Matrix n’est pas configuré.
• Que faire : configurez channels.matrix, puis relancez openclaw doctor --fix ou redémarrez le Gateway.

• Signification : OpenClaw a trouvé un ancien état, mais ne peut toujours pas déterminer la racine exacte du compte/appareil actuel.
• Que faire : démarrez une fois le Gateway avec une connexion Matrix fonctionnelle, ou relancez openclaw doctor --fix après l’existence d’identifiants mis en cache.

• Signification : OpenClaw a trouvé un magasin Matrix plat partagé, mais refuse de deviner quel compte Matrix nommé doit le recevoir.
• Que faire : définissez channels.matrix.defaultAccount sur le compte prévu, puis relancez openclaw doctor --fix ou redémarrez le Gateway.

• Signification : le nouvel emplacement scoped par compte possède déjà un magasin de synchronisation ou crypto, donc OpenClaw ne l’a pas écrasé automatiquement.
• Que faire : vérifiez que le compte actuel est le bon avant de supprimer ou déplacer manuellement la cible conflictuelle.

• Signification : OpenClaw a tenté de déplacer l’ancien état Matrix, mais l’opération sur le système de fichiers a échoué.
• Que faire : inspectez les permissions du système de fichiers et l’état du disque, puis relancez openclaw doctor --fix.

• Signification : OpenClaw a trouvé un ancien magasin Matrix chiffré, mais aucune configuration Matrix actuelle ne permet de l’y rattacher.
• Que faire : configurez channels.matrix, puis relancez openclaw doctor --fix ou redémarrez le Gateway.

• Signification : le magasin chiffré existe, mais OpenClaw ne peut pas décider en toute sécurité à quel compte/appareil actuel il appartient.
• Que faire : démarrez une fois le Gateway avec une connexion Matrix fonctionnelle, ou relancez openclaw doctor --fix après la disponibilité des identifiants mis en cache.

• Signification : OpenClaw a trouvé un ancien magasin crypto plat partagé, mais refuse de deviner quel compte Matrix nommé doit le recevoir.
• Que faire : définissez channels.matrix.defaultAccount sur le compte prévu, puis relancez openclaw doctor --fix ou redémarrez le Gateway.

• Signification : OpenClaw a détecté un ancien état Matrix, mais la migration est encore bloquée par des données d’identité ou d’identifiants manquantes.
• Que faire : terminez la connexion Matrix ou la configuration, puis relancez openclaw doctor --fix ou redémarrez le Gateway.

• Signification : OpenClaw a trouvé un ancien état Matrix chiffré, mais n’a pas pu charger le point d’entrée d’assistance du Plugin Matrix qui inspecte normalement ce magasin.
• Que faire : réinstallez ou réparez le Plugin Matrix (openclaw plugins install @openclaw/matrix, ou openclaw plugins install ./path/to/local/matrix-plugin pour une copie de travail du dépôt), puis relancez openclaw doctor --fix ou redémarrez le Gateway.
• Si npm signale le paquet Matrix appartenant à OpenClaw comme obsolète, utilisez le Plugin intégré d’une build OpenClaw empaquetée actuelle ou le chemin de la copie de travail locale jusqu’à ce qu’un paquet npm plus récent soit publié.

• Signification : OpenClaw a trouvé un chemin de fichier d’assistance qui sort de la racine du Plugin ou échoue aux contrôles de frontière du Plugin ; il a donc refusé de l’importer.
• Que faire : réinstallez le Plugin Matrix depuis un chemin de confiance, puis relancez openclaw doctor --fix ou redémarrez le Gateway.

• Signification : OpenClaw a refusé de modifier l’état Matrix parce qu’il ne pouvait pas d’abord créer l’instantané de récupération.
• Que faire : corrigez l’erreur de sauvegarde, puis relancez openclaw doctor --fix ou redémarrez le Gateway.

• Signification : la solution de repli côté client Matrix a trouvé un ancien stockage plat, mais le déplacement a échoué. OpenClaw interrompt désormais cette solution de repli au lieu de démarrer silencieusement avec un nouveau magasin vide.
• Que faire : inspectez les autorisations du système de fichiers ou les conflits, conservez l’ancien état intact, puis réessayez après avoir corrigé l’erreur.

• Signification : Matrix est épinglé à une installation par chemin ; les mises à jour principales ne le remplacent donc pas automatiquement par le paquet Matrix standard du dépôt.
• Que faire : réinstallez avec openclaw plugins install @openclaw/matrix lorsque vous voulez revenir au Plugin Matrix par défaut.
• Si npm signale le paquet Matrix appartenant à OpenClaw comme obsolète, utilisez le Plugin intégré d’une build OpenClaw empaquetée actuelle jusqu’à ce qu’un paquet npm plus récent soit publié.

​

Messages de récupération de l’état chiffré

• Signification : les clés de salon sauvegardées ont été restaurées avec succès dans le nouveau magasin crypto.
• Que faire : généralement rien.

• Signification : certaines anciennes clés de salon existaient uniquement dans l’ancien magasin local et n’avaient jamais été téléversées vers la sauvegarde Matrix.
• Que faire : attendez-vous à ce qu’une partie de l’ancien historique chiffré reste indisponible, sauf si vous pouvez récupérer ces clés manuellement depuis un autre client vérifié.

• Signification : la sauvegarde existe, mais OpenClaw n’a pas pu récupérer automatiquement la clé de récupération.
• Que faire : exécutez printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin.

• Signification : OpenClaw a trouvé l’ancien magasin chiffré, mais n’a pas pu l’inspecter de manière suffisamment sûre pour préparer la récupération.
• Que faire : relancez openclaw doctor --fix. Si cela se répète, conservez intact l’ancien répertoire d’état et récupérez les données avec un autre client Matrix vérifié, puis printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin.

• Signification : OpenClaw a détecté un conflit de clé de sauvegarde et a refusé d’écraser automatiquement le fichier recovery-key actuel.
• Que faire : vérifiez quelle clé de récupération est correcte avant de relancer toute commande de restauration.

• Signification : c’est la limite stricte de l’ancien format de stockage.
• Que faire : les clés sauvegardées peuvent toujours être restaurées, mais l’historique chiffré disponible uniquement localement peut rester indisponible.

• Signification : le nouveau Plugin a tenté la restauration, mais Matrix a renvoyé une erreur.
• Que faire : exécutez openclaw matrix verify backup status, puis réessayez avec printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin si nécessaire.

​

Messages de récupération manuelle

• Signification : OpenClaw sait que vous devriez disposer d’une clé de sauvegarde, mais elle n’est pas active sur cet appareil.
• Que faire : exécutez openclaw matrix verify backup restore, ou définissez MATRIX_RECOVERY_KEY et exécutez printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin si nécessaire.

• Signification : cet appareil ne dispose actuellement pas de la clé de récupération stockée.
• Que faire : définissez MATRIX_RECOVERY_KEY, exécutez printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin, puis restaurez la sauvegarde.

• Signification : la clé stockée ne correspond pas à la sauvegarde Matrix active.
• Que faire : définissez MATRIX_RECOVERY_KEY sur la bonne clé et exécutez printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin.

• Signification : la sauvegarde existe, mais cet appareil ne fait pas encore suffisamment confiance à la chaîne de signature croisée.
• Que faire : définissez MATRIX_RECOVERY_KEY et exécutez printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin.

• Signification : vous avez tenté une étape de récupération sans fournir de clé de récupération alors qu’elle était requise.
• Que faire : relancez la commande avec --recovery-key-stdin, par exemple printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin.

• Signification : la clé fournie n’a pas pu être analysée ou ne correspondait pas au format attendu.
• Que faire : réessayez avec la clé de récupération exacte provenant de votre client Matrix ou du fichier recovery-key.

• Signification : OpenClaw a pu appliquer la clé de récupération, mais Matrix n’a toujours pas établi une confiance complète dans l’identité par signature croisée pour cet appareil. Vérifiez la sortie de la commande pour Recovery key accepted, Backup usable, Cross-signing verified et Device verified by owner.
• Que faire : exécutez openclaw matrix verify self, acceptez la demande dans un autre client Matrix, comparez le SAS et saisissez yes uniquement lorsqu’il correspond. La commande attend une confiance complète dans l’identité Matrix avant de signaler la réussite. Utilisez printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify bootstrap --recovery-key-stdin --force-reset-cross-signing uniquement lorsque vous voulez intentionnellement remplacer l’identité de signature croisée actuelle.

• Signification : le stockage secret n’a pas produit de session de sauvegarde active sur cet appareil.
• Que faire : vérifiez d’abord l’appareil, puis revérifiez avec openclaw matrix verify backup status.

• Signification : cet appareil ne peut pas restaurer depuis le stockage secret tant que la vérification de l’appareil n’est pas terminée.
• Que faire : exécutez d’abord printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin.

​

Messages d’installation de Plugin personnalisé

• Signification : votre enregistrement d’installation de Plugin pointe vers un chemin local qui n’existe plus.
• Que faire : réinstallez avec openclaw plugins install @openclaw/matrix, ou, si vous exécutez depuis une copie de travail du dépôt, openclaw plugins install ./path/to/local/matrix-plugin.
• Si npm signale le paquet Matrix appartenant à OpenClaw comme obsolète, utilisez le Plugin intégré d’une build OpenClaw empaquetée actuelle ou le chemin de la copie de travail locale jusqu’à ce qu’un paquet npm plus récent soit publié.

​

Si l’historique chiffré ne revient toujours pas

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

​

Si vous voulez repartir de zéro pour les futurs messages

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

​

Connexe

• Matrix : configuration et paramétrage du canal.
• Règles push Matrix : routage des notifications.
• Doctor : contrôle d’intégrité et déclencheur de migration automatique.
• Guide de migration : tous les chemins de migration (déplacements de machine, imports entre systèmes).
• Plugins : installation et enregistrement de Plugin.