Skip to main content
Effectuez la mise à niveau depuis l’ancien plugin public matrix vers l’implémentation actuelle. Pour la plupart des utilisateurs, la mise à niveau est déjà prise en charge :
  • 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/
Vous n’avez pas besoin de renommer les clés de configuration ni de réinstaller le plugin sous un nouveau nom. Le paquet racine openclaw n’intègre plus le code d’exécution Matrix ni les dépendances du SDK Matrix. Si openclaw channels status indique que Matrix est configuré, mais que le plugin n’est pas installé, exécutez openclaw doctor --fix ou openclaw plugins install @openclaw/matrix ; n’installez pas les paquets du SDK Matrix dans le paquet racine OpenClaw.

​
Ce que la migration effectue automatiquement

La migration Matrix s’exécute lorsque vous lancez openclaw doctor --fix, ainsi qu’en solution de repli lorsque le client Matrix démarre et trouve encore un état annexe basé sur des fichiers à côté de son stockage SQLite. La migration automatique couvre les éléments suivants :
  • 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
  • l’importation de l’état annexe basé sur des fichiers (cache de synchronisation bot-storage.json, recovery-key.json, legacy-crypto-migration.json, instantanés IndexedDB) dans l’état SQLite de Matrix ; les fichiers migrés sont archivés avec le suffixe .migrated
  • la réutilisation de la racine de stockage de hachages de jetons existante la plus complète pour le même compte Matrix, serveur d’accueil, utilisateur et appareil lorsque le jeton d’accès change ultérieurement

​
Mise à niveau depuis des versions d’OpenClaw antérieures à 2026.4

Les versions allant jusqu’à la série 2026.6 migraient également la disposition Matrix plate d’origine à stockage unique (~/.openclaw/matrix/bot-storage.json plus ~/.openclaw/matrix/crypto/) et préparaient la récupération de l’état chiffré depuis l’ancien stockage cryptographique Rust. Les versions actuelles n’incluent plus cette migration. Si vous mettez à niveau une installation qui utilise encore la disposition plate, commencez par passer à une version 2026.6, exécutez openclaw doctor --fix, puis démarrez le Gateway une fois afin de migrer le stockage plat et toutes les clés de salon récupérables. Passez ensuite à la dernière version. L’ancien plugin public Matrix ne créait pas automatiquement de sauvegardes des clés de salon Matrix. Si votre ancienne installation contenait un historique chiffré uniquement local qui n’a jamais été sauvegardé, certains anciens messages chiffrés peuvent rester illisibles après la mise à niveau, quel que soit le chemin de migration.

​
Procédure de mise à niveau recommandée

  1. Mettez à jour OpenClaw et le plugin Matrix normalement.
  2. Exécutez :
  3. Démarrez ou redémarrez le Gateway.
  4. Vérifiez l’état actuel de la vérification et de la sauvegarde :
  5. Placez la clé de récupération du compte Matrix que vous réparez dans une variable d’environnement propre à ce 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 :
  7. Si cet appareil n’est toujours pas vérifié, exécutez la commande pour le compte correspondant :
    Si la clé de récupération est acceptée et que la sauvegarde est utilisable, mais que Cross-signing verified vaut toujours no, effectuez l’auto-vérification depuis un autre client Matrix :
    Acceptez la demande dans un autre client Matrix, comparez les emoji ou les nombres décimaux, et saisissez yes uniquement s’ils correspondent. La commande attend que l’identité Matrix soit entièrement approuvée avant de signaler la réussite.
  8. Si vous abandonnez volontairement l’ancien historique irrécupérable et souhaitez une nouvelle base de référence de sauvegarde pour les futurs messages, exécutez :
    Ajoutez --rotate-recovery-key uniquement si l’ancienne clé de récupération ne doit plus permettre de déverrouiller la nouvelle sauvegarde.
  9. S’il n’existe encore aucune sauvegarde de clés côté serveur, créez-en une pour les récupérations futures :

​
Messages courants et leur signification

Failed migrating legacy Matrix client storage: ...
  • Signification : la solution de repli côté client Matrix a trouvé un état annexe basé sur des fichiers, mais l’importation dans SQLite a échoué. OpenClaw annule les déplacements terminés et interrompt cette solution de repli au lieu de démarrer silencieusement avec un nouveau stockage.
  • Que faire : vérifiez les autorisations du système de fichiers ou les conflits, conservez l’ancien état intact, puis réessayez après avoir corrigé l’erreur.
Matrix is installed from a custom path: ...
  • Signification : Matrix est épinglé à une installation depuis un chemin, les mises à jour de la branche principale ne le remplacent donc pas automatiquement par le paquet Matrix par défaut.
  • Que faire : réinstallez-le avec openclaw plugins install @openclaw/matrix lorsque vous souhaitez revenir au plugin Matrix par défaut.
Matrix is installed from a custom path that no longer exists: ...
  • Signification : l’enregistrement d’installation de votre plugin pointe vers un chemin local qui n’existe plus.
  • Que faire : réinstallez-le avec openclaw plugins install @openclaw/matrix ou, si vous exécutez OpenClaw depuis une copie de travail du dépôt, avec openclaw plugins install ./path/to/local/matrix-plugin. openclaw doctor --fix peut également supprimer pour vous les références obsolètes au plugin Matrix.

​
Messages de récupération manuelle

openclaw matrix verify status et openclaw matrix verify backup status affichent une ligne Backup issue: ainsi que des instructions Next steps: lorsque la sauvegarde des clés de salon n’est pas saine sur cet appareil : Autres erreurs de récupération : Matrix recovery key is required
  • 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 : réexécutez la commande avec --recovery-key-stdin, par exemple printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin.
Invalid Matrix recovery key: ...
  • 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 de l’exportation de la clé de récupération.
Matrix recovery key was applied, but this device still lacks full Matrix identity trust.
  • Signification : la clé de récupération a déverrouillé des données de sauvegarde utilisables, mais Matrix n’a pas établi une approbation complète de l’identité par signature croisée pour cet appareil. Recherchez dans la sortie de la commande 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 s’il correspond. Utilisez printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify bootstrap --recovery-key-stdin --force-reset-cross-signing uniquement si vous souhaitez volontairement remplacer l’identité de signature croisée actuelle.
Si vous acceptez de perdre l’ancien historique chiffré irrécupérable, vous pouvez plutôt réinitialiser la base de référence de sauvegarde actuelle avec openclaw matrix verify backup reset --yes. Lorsque le secret de sauvegarde stocké est défectueux, cette réinitialisation répare également le stockage des secrets afin que la nouvelle clé de sauvegarde puisse être chargée correctement après le redémarrage.

​
Si l’historique chiffré ne revient toujours pas

Exécutez ces vérifications dans l’ordre :
Si la sauvegarde est restaurée correctement, mais que l’historique manque encore dans certains anciens salons, ces clés manquantes n’ont probablement jamais été sauvegardées par l’ancien plugin.

​
Si vous souhaitez repartir de zéro pour les futurs messages

Si vous acceptez de perdre l’ancien historique chiffré irrécupérable et souhaitez uniquement disposer d’une base de référence de sauvegarde propre pour la suite, exécutez ces commandes dans l’ordre :
Si l’appareil n’est toujours pas vérifié après cela, terminez la vérification depuis votre client Matrix en comparant les emoji SAS ou les codes décimaux et en confirmant qu’ils correspondent.

​
Voir aussi

  • Matrix : configuration 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 entre machines, importations entre systèmes).
  • Plugins : installation et enregistrement des plugins.