Matrix

Exécutez ZeroClaw dans les salles Matrix, y compris les salles chiffrées de bout en bout (E2EE).

Qui peut parler à l’agent

Les expéditeurs entrants sont filtrés par rapport au peer set résolu pour l’agent lié, issu de la configuration peer_groups à laquelle l’agent appartient. La correspondance supprime le @ initial et est insensible à la casse par rapport à l’identifiant d’expéditeur natif du canal. Un ensemble vide refuse tout le monde ; un ensemble contenant "*" accepte n’importe qui ; sinon, seuls les pairs externes listés (et les agents pairs) sont acceptés. Ceci est distinct de l’appairage de la passerelle (gateway.require_pairing), qui authentifie les clients HTTP/WebSocket, et non les expéditeurs des canaux de discussion.

Un groupe de pairs pour matrix définit channel à matrix, liste les expéditeurs autorisés dans external_peers (pour matrix, l’identifiant utilisateur Matrix complet, @user:server.tld ; ["*"] accepte n’importe qui), nomme éventuellement des agents pairs pour la répartition inter-agents, une liste de blocage ignore, et une output_modality (mirror, voice ou text). Voir Peer Groups pour la référence des champs.

Où définir ce paramètre :

Mode d’échec courant que ce guide cible :

« Matrix est correctement configuré, les vérifications réussissent, mais le bot ne répond pas. »

FAQ rapide

Si Matrix apparaît connecté mais qu’il n’y a pas de réponse, validez d’abord ces points :

1. L’expéditeur fait partie de l’ensemble de pairs de l’agent (pour les tests : external_peers = ["*"]).
2. Le bot a rejoint la pièce cible.
3. Les identifiants appartiennent au compte du bot (vérification whoami sur le chemin du jeton, voir §5C).
4. La salle chiffrée peut être déchiffrée : recovery_key défini (recommandé) ou clés partagées avec l’appareil du bot.
5. Le démon a été redémarré après les modifications de configuration.

1. Exigences

Avant de tester le flux de messages :

1. • Le compte du bot est joint à la salle cible.
2. Les identifiants authentifient le compte du bot : soit user_id + password (recommandé, voir §2), soit un access_token (méthode par jeton, §3).
3. allowed_rooms inclut le salon cible (ou est vide pour autoriser tous les salons que le bot a rejoints). Les entrées sont comparées littéralement à l’ID canonique du salon (!room:server) de chaque message entrant, donc listez ici les ID canoniques des salons : ZeroClaw ne résout pas une entrée #alias:server pour cette liste d’autorisation. (Les alias ne sont résolus que pour les cibles de livraison sortantes telles que delivery.to de cron.) Trouvez l’ID canonique d’un salon dans son client (dans Element : Paramètres du salon → Avancé → ID interne du salon).
4. Un groupe de pairs autorise l’expéditeur (external_peers = ["*"] pour les tests ouverts, voir §6).
5. Pour les salons E2EE, le bot peut déchiffrer : une recovery_key (recommandé) restaure les clés automatiquement, ou les clés sont partagées manuellement avec l’appareil du bot.

2. Configuration

zeroclaw config set channels.matrix.<alias>.access_token    # entrée masquée, stockée chiffrée

export ZEROCLAW_channels__matrix__<alias>__access_token=

zeroclaw config set channels.matrix.<alias>.ack_reactions <value>

export ZEROCLAW_channels__matrix__<alias>__ack_reactions=

zeroclaw config set channels.matrix.<alias>.allowed_rooms <value>

export ZEROCLAW_channels__matrix__<alias>__allowed_rooms=

zeroclaw config set channels.matrix.<alias>.approval_timeout_secs <value>

export ZEROCLAW_channels__matrix__<alias>__approval_timeout_secs=

zeroclaw config set channels.matrix.<alias>.device_id <value>

export ZEROCLAW_channels__matrix__<alias>__device_id=

zeroclaw config set channels.matrix.<alias>.draft_update_interval_ms <value>

export ZEROCLAW_channels__matrix__<alias>__draft_update_interval_ms=

zeroclaw config set channels.matrix.<alias>.excluded_tools <value>

export ZEROCLAW_channels__matrix__<alias>__excluded_tools=

zeroclaw config set channels.matrix.<alias>.homeserver <value>

export ZEROCLAW_channels__matrix__<alias>__homeserver=

zeroclaw config set channels.matrix.<alias>.interrupt_on_new_message <value>

export ZEROCLAW_channels__matrix__<alias>__interrupt_on_new_message=

zeroclaw config set channels.matrix.<alias>.mention_only <value>

export ZEROCLAW_channels__matrix__<alias>__mention_only=

zeroclaw config set channels.matrix.<alias>.message_max_bytes <value>

export ZEROCLAW_channels__matrix__<alias>__message_max_bytes=

zeroclaw config set channels.matrix.<alias>.multi_message_delay_ms <value>

export ZEROCLAW_channels__matrix__<alias>__multi_message_delay_ms=

zeroclaw config set channels.matrix.<alias>.password    # entrée masquée, stockée chiffrée

export ZEROCLAW_channels__matrix__<alias>__password=

zeroclaw config set channels.matrix.<alias>.recovery_key    # entrée masquée, stockée chiffrée

export ZEROCLAW_channels__matrix__<alias>__recovery_key=

zeroclaw config set channels.matrix.<alias>.reply_in_thread <value>

export ZEROCLAW_channels__matrix__<alias>__reply_in_thread=

zeroclaw config set channels.matrix.<alias>.reply_min_interval_secs <value>

export ZEROCLAW_channels__matrix__<alias>__reply_min_interval_secs=

zeroclaw config set channels.matrix.<alias>.reply_queue_depth_max <value>

export ZEROCLAW_channels__matrix__<alias>__reply_queue_depth_max=

zeroclaw config set channels.matrix.<alias>.stream_draft_delete <value>

export ZEROCLAW_channels__matrix__<alias>__stream_draft_delete=

zeroclaw config set channels.matrix.<alias>.stream_draft_lines <value>

export ZEROCLAW_channels__matrix__<alias>__stream_draft_lines=

zeroclaw config set channels.matrix.<alias>.stream_mode <value>

export ZEROCLAW_channels__matrix__<alias>__stream_mode=

zeroclaw config set channels.matrix.<alias>.stream_reasoning <value>

export ZEROCLAW_channels__matrix__<alias>__stream_reasoning=

zeroclaw config set channels.matrix.<alias>.stream_tool_arguments <value>

export ZEROCLAW_channels__matrix__<alias>__stream_tool_arguments=

zeroclaw config set channels.matrix.<alias>.user_id <value>

export ZEROCLAW_channels__matrix__<alias>__user_id=

Matrix se configure sous forme de bloc [channels.matrix.<alias>]. Définissez-le via l’une de ces interfaces :

Configuration recommandée : mot de passe + clé de récupération

La méthode officielle et la plus simple pour exécuter Matrix est de laisser ZeroClaw se connecter avec une nouvelle session et gérer sa propre identité d’appareil :

• Omettez device_id. Laissez le homeserver en attribuer un à la connexion. ZeroClaw enregistre l’identifiant attribué dans session.json et le réutilise à chaque redémarrage, vous n’avez donc aucune valeur à rechercher, copier ou maintenir synchronisée. Épingler un device_id à la main est la source la plus fréquente de partage de clés défaillant.
• Omettez access_token. Lorsqu’il n’est pas défini, ZeroClaw revient à la connexion par mot de passe. Une nouvelle connexion est également ce qu’utilise le chemin de récupération automatique (§8), de sorte que le bot se rétablit de lui-même d’un état local corrompu sans intervention de l’opérateur.
• Définissez password. En l’absence d’access_token, user_id + password effectuent la connexion.
• Définissez recovery_key. Cela restaure les clés de salon depuis la sauvegarde côté serveur et signe de manière croisée l’appareil fraîchement enregistré automatiquement à chaque démarrage : pas de vérification par emoji, pas de partage manuel de clés, pas de bootstrap. Consultez §5I pour savoir comment l’obtenir depuis Element.

Un bloc complet recommandé définit donc homeserver, user_id, password et recovery_key, et laisse access_token et device_id non définis.

Le chemin access_token + device_id (§3) fonctionne toujours et est documenté en détail pour les opérateurs qui doivent réutiliser un token préexistant, mais il vous oblige à maintenir vous-même un device_id stable, donc préférez le mot de passe + la clé de récupération sauf si vous avez une raison spécifique de ne pas le faire.

channels.matrix.<alias>.password est un secret. Stocké chiffré, jamais en clair dans config.toml. Définissez-le via l’une de ces méthodes, qui chiffrent lors de l’écriture :

zeroclaw config set channels.matrix.<alias>.password    # demande une saisie masquée, stocke de manière chiffrée

channels.matrix.<alias>.access_token est un secret. Stocké chiffré, jamais en clair dans config.toml. Définissez-le via l’une de ces méthodes, qui chiffrent à l’écriture :

zeroclaw config set channels.matrix.<alias>.access_token    # demande une saisie masquée, stocke de manière chiffrée

homeserver est requis. Pour la configuration recommandée, définissez également user_id, password et recovery_key. access_token et device_id ne sont nécessaires que pour la méthode basée sur les jetons décrite dans la §3 ; allowed_rooms permet éventuellement de restreindre les salons dans lesquels le bot répond. Autorisez les expéditeurs avec un groupe de pairs. Index complet des champs : référence de configuration.

Vous n’avez pas encore de recovery_key ? Consultez la §5I : elle explique pas à pas comment en générer une dans Element. Vous optez plutôt pour la méthode par jeton ? Consultez la §3 pour l’appel API de connexion par mot de passe qui génère un access_token ainsi qu’un device_id stable en une seule fois. Pour retrouver le device_id d’un jeton que vous possédez déjà, consultez la §5H.

À propos de user_id et device_id

• Pour la configuration recommandée avec mot de passe + clé de récupération, définissez user_id et laissez device_id non défini : le homeserver l’attribue et ZeroClaw le persiste.
• ZeroClaw lit l’identité depuis Matrix /_matrix/client/v3/account/whoami.
• Ce n’est que sur le chemin access_token que vous définissez device_id manuellement : une connexion par token transporte un appareil déjà créé par le serveur, et ZeroClaw a besoin de cet id exact pour la restauration de session E2EE (voir §5H pour le trouver).

Threads et contexte

Lorsqu’une conversation Matrix se déroule dans un fil de discussion, ce fil constitue une conversation à part entière. ZeroClaw dérive une clé de session distincte par fil, de sorte que chaque fil dispose d’une fenêtre de contexte et d’un historique indépendants : les messages d’un fil ne débordent jamais dans un autre, et l’agent ne voit pas les tours précédents d’un fil voisin. Pour Matrix, ce comportement est contrôlé par reply_in_thread : lorsqu’il est activé, les messages de premier niveau ouvrent un fil et chaque fil est une conversation séparée ; lorsqu’il est désactivé, les réponses sont publiées à la racine du canal et l’historique est indexé par expéditeur et cible plutôt que par fil.

• L’isolation est l’objectif. Le contexte de chaque thread est autonome : il ne fuit pas en dehors du thread, et rien de l’extérieur du thread ne s’y infiltre. Les threads parallèles conservent des états conversationnels distincts, de sorte que des tâches sans rapport ne se contaminent jamais entre elles.
• Les threads longs font croître le contexte. Un thread accumule l’historique tant qu’il reste actif, donc un thread très long finit par remplir la fenêtre de contexte du modèle comme toute autre conversation longue. Démarrez un nouveau thread pour réinitialiser.
• Le travail en cours est limité à chaque fil de discussion. Un nouveau message dans un fil n’annule pas une réponse en cours dans un autre ; la tâche de chaque fil est indépendante.

Définissez le comportement du thread sur n’importe quelle surface :

zeroclaw config set channels.matrix.<alias>.reply_in_thread true     # réponses en fil de discussion activées
zeroclaw config set channels.matrix.<alias>.reply_in_thread false    # réponses à la racine du canal

3. Méthode par jeton (alternative) : obtention de access_token et device_id

[!IMPORTANT] Cette section concerne uniquement le chemin access_token. Si vous avez suivi la configuration recommandée par mot de passe + clé de récupération dans la §2, vous pouvez l’ignorer : vous n’avez pas besoin d’un jeton d’accès ni d’un device_id géré manuellement.

Utilisez ce chemin lorsque vous devez réutiliser un token préexistant (par exemple un token copié depuis un autre déploiement). Element n’expose pas le token directement, donc la méthode canonique pour en générer un est un appel API unique de connexion par mot de passe qui renvoie à la fois le token d’accès et un identifiant d’appareil stable. La connexion par token est associée à un appareil, donc sur ce chemin device_id est requis et doit rester stable.

Si votre compte opérateur possède déjà un jeton, passez directement à la §4. Si vous avez seulement besoin de rechercher le device_id d’un jeton existant, consultez la §5H Option 1 (whoami) ou Option 2 (Element).

Étape 1 : Émettre un jeton via une connexion par mot de passe

Exécutez ceci une seule fois. Remplacez your.homeserver, le nom d’utilisateur du bot, le mot de passe, et choisissez une courte chaîne device_id quelconque (alphanumérique, sans espaces ; il s’agit de l’étiquette d’appareil côté serveur que ZeroClaw réutilisera à chaque redémarrage) :

curl -sS -X POST https://your.homeserver/_matrix/client/v3/login \
  -H "Content-Type: application/json" \
  -d '{"type":"m.login.password","identifier":{"type":"m.id.user","user":"YOUR_BOT_USERNAME"},"password":"YOUR_PASSWORD","device_id":"NEW_DEVICE_ID"}'

Réponse :

{"\"user_id\"": "@bot:example.com", "access_token": "syt_...", "\u00ab device_id \u00bb": "APPAREILNEW"}

Étape 2 : Appliquez les deux valeurs à ZeroClaw

Placez access_token, device_id et user_id de la réponse dans votre bloc [channels.matrix.<alias>] (voir §2 pour savoir où les définir), puis redémarrez : zeroclaw service restart.

Notes

• Conservez une copie du jeton lorsque vous le collez pour la première fois. Les secrets sont chiffrés au repos et zeroclaw config get affichera [masked] pour le champ du jeton ; vous ne pourrez pas le récupérer ultérieurement. Mettez-le de côté dans une note temporaire si vous en avez besoin pour les extraits de validation curl dans la §5C.
• Réutilisez le même device_id à chaque redémarrage : le modifier force un nouvel enregistrement d’appareil côté serveur, ce qui rompt le partage de clés et la vérification dans les salons chiffrés. Le mécanisme de récupération automatique décrit dans la §8 gère les rares cas où la suppression est réellement le bon choix.
• Rotation ultérieure du jeton d’accès sans relancer l’assistant : mettez à jour le champ access_token dans votre configuration (voir §2), puis exécutez zeroclaw service restart.
• Le jeton apparaît comme expiré ou invalide au démarrage : générez-en un nouveau avec le même curl, répétez l’étape 2.

4. Validation rapide

Appliquez le jeu de champs défini dans la §2 si ce n’est pas déjà fait, puis redémarrez avec zeroclaw service restart (arrière-plan) ou zeroclaw daemon (premier plan). Envoyez un message en texte brut dans le salon Matrix configuré. Vérifiez :

• Les journaux de ZeroClaw indiquent que l’écouteur Matrix a démarré sans erreurs répétées de synchronisation ou d’authentification.
• Dans une salle chiffrée, le bot peut lire et répondre aux messages chiffrés des utilisateurs autorisés.

5. Résolution des problèmes de « non-réponse »

Exécutez dans l’ordre.

A. Salle et appartenance

• Confirmez que le compte du bot a rejoint la salle.
• Si vous ajoutez un salon dans allowed_rooms, il doit s’agir de l’identifiant canonique du salon (!room:server), et non d’un alias #alias:server. Les alias ne sont pas résolus pour la liste d’autorisation, donc une entrée sous forme d’alias ne correspond silencieusement à rien. Trouvez l’identifiant canonique dans Element via Paramètres du salon → Avancé → Identifiant interne du salon.

B. Liste d’autorisation des expéditeurs (groupes de pairs)

L’expéditeur doit faire partie de l’ensemble des pairs de l’agent, voir Qui peut communiquer avec l’agent en haut de cette page. Pour le diagnostic, définissez temporairement external_peers = ["*"] et redémarrez le démon.

C. Jetons et identité

Les secrets sont chiffrés au repos et ne sont pas récupérables : zeroclaw config get affiche [masked] pour tout champ secret. Pour exécuter les vérifications ci-dessous, utilisez le jeton d’accès que vous avez généré dans la §3 (ou générez-en un nouveau) ainsi que l’URL de votre propre serveur d’accueil (homeserver).

Validez le jeton côté serveur :

curl -sS -H "Authorization: Bearer <access_token>" \
  "https://your.homeserver/_matrix/client/v3/account/whoami"

• Le user_id retourné doit correspondre au compte du bot.
• Si device_id est absent de la réponse, définissez-le manuellement (voir §5H).
• Effectuez la rotation du jeton d’accès : mettez à jour le champ access_token dans votre configuration (voir §2), puis exécutez zeroclaw service restart.

D. Vérifications spécifiques à l’E2EE

• Le dispositif du bot doit avoir reçu les clés de salle depuis des dispositifs de confiance.
• Si les clés n’ont pas été partagées avec cet appareil, les événements chiffrés ne peuvent pas être déchiffrés.
• Vérifiez la confiance de l’appareil et le partage de clés à partir d’une session Matrix de confiance.
• matrix_sdk_crypto::backups: Trying to backup room keys but no backup key was found : la récupération de la sauvegarde des clés n’est pas encore activée sur cet appareil. Non bloquant pour le flux de messages ; il reste néanmoins recommandé de la finaliser (voir §5I).
• Si les destinataires voient les messages du bot comme « non vérifiés », vérifiez/signez l’appareil du bot depuis une session Matrix de confiance et gardez le device_id stable entre les redémarrages.

N. Niveaux de journal

ZeroClaw réduit matrix_sdk, matrix_sdk_base et matrix_sdk_crypto au niveau warn par défaut ; ils sont trop verbeux au niveau info. Pour restaurer la sortie du SDK à des fins de débogage :

RUST_LOG=info,matrix_sdk=info,matrix_sdk_base=info,matrix_sdk_crypto=info zeroclaw daemon

F. Formatage des messages (Markdown)

• ZeroClaw envoie les réponses Matrix sous forme de contenu texte m.room.message capable de gérer le markdown.
• Les clients Matrix qui prennent en charge formatted_body affichent les mises en forme, les listes et les blocs de code.
• Si le formatage apparaît en texte brut : vérifiez d’abord la capacité du client, puis confirmez que ZeroClaw exécute une version avec la sortie Matrix activée pour le markdown.

G. Test de début frais

Après avoir modifié la configuration, redémarrez le daemon et envoyez un nouveau message. L’historique de l’ancienne timeline ne sera pas rejoué.

H. Recherche du device_id pour un jeton existant

Vous n’avez besoin de ceci que sur le chemin access_token (§3). La configuration recommandée par mot de passe + clé de récupération omet entièrement device_id : le homeserver en attribue un et ZeroClaw le persiste, il n’y a donc rien à rechercher. Si vous êtes passé à la configuration recommandée, ignorez cette section.

Si vous devez vraiment fixer un device_id (parce que vous réutilisez un jeton d’accès existant plutôt que de vous connecter avec un mot de passe), utilisez ceci pour trouver celui lié à ce jeton. Pour les bots tout nouveaux sur la voie du jeton, consultez §3 : le flux de connexion par mot de passe qui s’y trouve renvoie les deux valeurs ensemble.

ZeroClaw a besoin d’un device_id stable pour la restauration de session E2EE sur le chemin du jeton. Sans cela, un nouvel appareil est enregistré à chaque redémarrage, ce qui rompt le partage de clés et la vérification des appareils.

Option 1 : whoami (la plus simple)

curl -sS -H "Authorization: Bearer <access_token>" \
  "https://your.homeserver/_matrix/client/v3/account/whoami"

Inclut device_id si le token est lié à une session d’appareil :

{"\"user_id\"": "@bot:example.com", "\u00ab device_id \u00bb": "ABCDEF1234"}

Si device_id est absent, le jeton a été créé sans connexion d’appareil (par ex. via l’API d’administration). Générez un nouveau jeton + device_id ensemble via §3.

Option 2 : Depuis Element ou un autre client Matrix

1. Connectez-vous en tant que compte bot dans Element.
2. Paramètres → Sessions.
3. Copiez l’ID de l’appareil pour la session active.
4. Définissez device_id dans votre configuration (voir §2), puis exécutez zeroclaw service restart. Gardez device_id stable : le modifier force un nouvel enregistrement de l’appareil, ce qui rompt le partage de clés et la vérification existants.

H (suite). Récupération de la suppression du magasin de clés

Symptôme : Conflit détecté lors du téléchargement de la clé à usage unique de Matrix ; synchronisation arrêtée pour éviter une boucle de retry infinie et le canal devient indisponible.

Cause: Le magasin de cryptage local a été supprimé alors que l’ancien appareil avait encore des clés à usage unique enregistrées sur le homeserver. Le SDK ne peut pas télécharger de nouvelles clés car les anciennes clés existent toujours côté serveur, ce qui provoque une boucle infinie de conflits de clés à usage unique (OTK).

Correction : nouvelle connexion

Une nouvelle connexion crée un nouvel appareil avec un device_id distinct, contournant ainsi entièrement le conflit OTK (aucune suppression d’appareil conditionnée par l’UIA n’est nécessaire).

1. Arrêter ZeroClaw.

   sh

   zeroclaw service stop
   

2. Obtenez un nouveau jeton d’accès et device_id :

   sh

   curl -sS -X POST "https://matrix.org/_matrix/client/v3/login" \
     -H "Content-Type: application/json" \
     -d '{"type":"m.login.password","identifier":{"type":"m.id.user","user":"YOUR_BOT_USERNAME"},"password":"YOUR_PASSWORD","device_id":"NEW_DEVICE_ID"}'
   

   Enregistrez le access_token et le device_id retournés.

3. Supprimer le stockage local de crypto :

   sh

   rm -rf ~/.zeroclaw/state/matrix/
   

4. Appliquez les nouveaux identifiants : définissez access_token (secret, voir §2) et device_id dans votre configuration.

5. Redémarrer :

   sh

   zeroclaw service start
   

À quoi s’attendre lors du premier redémarrage

• Our own device might have been deleted : sans gravité ; l’ancien appareil a disparu.
• Failed to decrypt a room event : anciens messages antérieurs à la réinitialisation ; irrécupérables.
• Matrix E2EE recovery successful : clés de salon restaurées depuis la sauvegarde du serveur (uniquement si recovery_key est définie ; voir §5I).
• Les nouveaux messages se déchiffrent et fonctionnent normalement.

Prévention : Ne supprimez pas le répertoire d’état local sans préparer une nouvelle connexion. Si vous avez besoin de repartir de zéro, obtenez de nouvelles identifiants, puis supprimez le dépôt, et enfin mettez à jour la configuration.

I. Clé de récupération (recommandée pour le chiffrement de bout en bout)

Une clé de récupération permet à ZeroClaw de restaurer automatiquement les clés de salon et les secrets de signature croisée à partir de la sauvegarde côté serveur. Les réinitialisations d’appareil, les suppressions du magasin de chiffrement et les nouvelles installations sont toutes récupérées automatiquement : pas de vérification par émojis, pas de partage manuel de clés.

Étape 1 : Obtenez votre clé de récupération depuis Element

1. Connectez-vous au compte du bot dans Element (web ou bureau).
2. Paramètres → Sécurité et confidentialité → Chiffrement → Sauvegarde sécurisée.
3. Si la sauvegarde est déjà configurée, votre clé de récupération a été affichée lors de la première activation. Si vous l’avez sauvegardée, utilisez-la.
4. Si la sauvegarde n’est pas configurée, cliquez sur « Set up Secure Backup » → « Generate a Security Key ». Element affiche la clé (elle ressemble à EsTj 3yST y93F SLpB ...) ; copiez-la dans un endroit sûr.
5. Continuez après l’affichage de la clé : Element vous demande ensuite de ressaisir la clé dans une boîte de confirmation pour prouver que vous l’avez enregistrée. Collez-la et continuez pour terminer la configuration. Il s’agit de la même valeur que celle que vous avez mise dans recovery_key.
6. (Facultatif) Déconnectez la session Element du bot une fois la clé enregistrée : cliquez sur le menu du compte → All settings → Account, puis Remove this device. Laisser la session connectée ne pose pas de problème ; la supprimer permet simplement de garder la liste des appareils ordonnée.

Étape 2 : Ajouter la clé de récupération à ZeroClaw

Appliquez la clé de récupération à ZeroClaw :

channels.matrix.<alias>.recovery_key est un secret. Stocké chiffré, jamais en clair dans config.toml. Définissez-le via l’une de ces méthodes, qui chiffrent à l’écriture :

zeroclaw config set channels.matrix.<alias>.recovery_key    # demande une saisie masquée, stocke de manière chiffrée

Ensuite, zeroclaw service restart. La clé de récupération est immédiatement chiffrée au repos.

Étape 3 : Redémarrer

zeroclaw service restart

Au démarrage, vous devriez voir :

Matrix E2EE recovery successful — room keys and cross-signing secrets restored from server backup.

Désormais, même si le magasin de clés local est supprimé, ZeroClaw se rétablit automatiquement au prochain démarrage.

6. Journalisation de débogage

Diagnostics propres au canal Matrix :

RUST_LOG=zeroclaw::channels::matrix=debug zeroclaw daemon

Surfaces :

• Confirmation de la restauration de la session
• Chaque achèvement de cycle de synchronisation
• état du commutateur de conflit OTK
• Résultats de la vérification de l’état du service
• Classification des erreurs de synchronisation transitoires versus mortelles

Pour plus de détails au niveau du SDK :

RUST_LOG=zeroclaw::channels::matrix=debug,matrix_sdk_crypto=debug zeroclaw daemon

7. Notes opérationnelles

• Conservez les jetons Matrix hors des journaux et des captures d’écran.
• Commencez avec une configuration permissive external_peers = ["*"], puis restreignez à des identifiants utilisateur explicites une fois la vérification effectuée.
• Utilisez toujours les ID de salle canoniques dans allowed_rooms : les alias ne sont pas résolus pour la liste d’autorisation entrante (ils sont résolus uniquement pour delivery.to en sortie).
• Threading : lorsque channels.matrix.reply_in_thread est à true (valeur par défaut), chaque réponse du bot s’inscrit dans un fil de discussion rattaché au message de l’utilisateur. Les messages utilisateur de premier niveau ouvrent un nouveau fil ; les fils existants sont poursuivis. La chronologie principale du salon ne contient que les messages initiés par l’utilisateur.
• Contexte de racine de fil de discussion : le premier message entrant que ZeroClaw voit dans un fil donné est préfixé par [Thread root from @sender]: <root body> afin que l’agent dispose de la conversation qui a déclenché la réponse. Les fils démarrés par le bot lui-même omettent le préambule. Le suivi est effectué uniquement en mémoire ; après un redémarrage du démon, le message suivant dans chaque fil actif réinjecte le préambule exactement une fois.
• Médias en réponse en ligne : channels.matrix.mention_only = true fait que le bot ignore les envois de médias seuls (pas de corps de texte permettant une mention). Lorsque l’utilisateur répond en ligne à un tel événement ignoré avec une question (@bot can you see this?), ZeroClaw parcourt le m.relates_to.m.in_reply_to.event_id de la réponse, récupère l’événement parent et intègre ses médias dans le message courant : le pipeline de vision de l’agent voit l’image même si l’envoi original avait été filtré.
• Les pièces jointes suivent le fil de discussion : les appels room.send_attachment transmettent un AttachmentConfig::reply(...) avec EnforceThread::Threaded lorsqu’une ancre de fil est présente, de sorte que les PDF / images / notes vocales s’affichent dans le fil du bot plutôt que dans le fil de discussion principal.
• Marqueurs de médias sortants : l’agent émet [image:url|path], [file:url|path], [voice:url|path], [video:...], [audio:...] (ainsi que les alias en majuscules / [document:...]) dans le texte de sa réponse ; ZeroClaw récupère les octets (HTTP pour http(s)://, lecture locale sinon) et les téléverse en tant qu’événement de message Matrix approprié. Les cibles manquantes ou illisibles ne sont pas fatales : le canal enregistre un avertissement, supprime uniquement ce marqueur et ajoute une ligne (note: I couldn't deliver the file at <path>.) afin que l’opérateur voie ce qui a été tenté au lieu d’une réponse silencieusement supprimée.
• Messages vocaux (MSC3245) : les événements m.audio entrants portant le champ org.matrix.msc3245.voice sont enregistrés dans {workspace_dir}/matrix_files/ et traités par le fournisseur de transcription configuré de l’agent, afin que l’agent reçoive à la fois le texte de la transcription et le chemin source. Les notes vocales sortantes utilisent le marqueur [voice:<url|path>] ; ZeroClaw les téléverse en tant que m.audio avec l’indicateur vocal + une forme d’onde à zéro, afin qu’Element affiche la bulle comme une note vocale. Consultez Model Providers pour la configuration du fournisseur de transcription.
• Réactions d’accusé de réception : contrôlées par channels.matrix.ack_reactions (par défaut true). Lorsqu’elle est activée, le bot réagit avec 👀 pendant le traitement et ✅ une fois terminé. Définissez la valeur sur false pour garder les salons sans réactions.
• Sessions persistantes : lors de la première connexion réussie, ZeroClaw écrit ~/.zeroclaw/state/matrix/session.json (user_id + device_id + access_token + refresh_token optionnel). Les redémarrages suivants appellent restore_session() à partir de ce blob : pas de nouvelle connexion. Le magasin cryptographique SQLite de matrix-rust-sdk se trouve à côté, dans ~/.zeroclaw/state/matrix/store/. Une fois que session.json existe, la rotation de access_token dans la configuration n’a aucun effet tant que le fichier n’est pas supprimé : le jeton enregistré a la priorité. Supprimez session.json pour forcer une nouvelle connexion à partir des valeurs de configuration.
• Signature croisée : lorsque recovery_key correspond à ce qui est scellé dans le stockage secret côté serveur de votre compte, ZeroClaw exécute recovery().recover(key) à chaque démarrage, le SDK importe vos clés existantes master / self-signing / user-signing, et l’appareil nouvellement enregistré est automatiquement signé. Pas de bootstrap, pas d’UIA, pas de rotation de clés. Si votre compte n’a pas encore de signature croisée configurée, générez la clé de récupération dans Element (Settings → Security & Privacy → Secure Backup) avant de configurer recovery_key.
• Livraison Cron : delivery.to doit être un identifiant de salon simple (!abc:server) ou un alias (#room:server). Les anciennes configurations qui écrivaient <sender>||<room> sont tolérées : ZeroClaw extrait le dernier segment préfixé par !/# et émet un avertissement concernant la valeur mal formée.

Diffusion en continu

Matrix diffuse les réponses en continu via le paramètre stream_mode :

• off (par défaut) : la réponse entière est publiée en un seul message une fois que l’agent a terminé. C’est l’option la plus simple, et elle n’affiche jamais de réponse partiellement rédigée.
• partial : le bot publie immédiatement un brouillon et le modifie sur place au fur et à mesure que la réponse arrive en streaming. draft_update_interval_ms régule le rythme des modifications ; augmentez-le si Matrix les limite par rate-limiting.
• multi_message : chaque paragraphe est publié comme un message distinct, séparé par multi_message_delay_ms. Idéal pour les réponses longues qui formeraient sinon un seul bloc de texte.

Posez-le sur n’importe quelle surface :

zeroclaw config set channels.matrix.<alias>.stream_mode <value>

Spécificités de Matrix : en mode partial, l’état d’exécution des outils est affiché via le même pipeline de modifications que le texte de la réponse. En mode single_message, les mises à jour d’état des outils et de la progression sont modifiées dans un brouillon glissant unique, tandis que la réponse finale est envoyée comme un message Matrix distinct. stream_draft_lines contrôle les lignes de progression visibles : 0 supprime uniquement la limite du nombre de lignes ; il ne crée jamais de second message de progression. message_max_bytes plafonne le contenu du brouillon et de l’événement final, en comptant le Markdown rendu (y compris le HTML généré) ainsi que les métadonnées de relation de réponse et de modification Matrix, et non uniquement la source Markdown. Lorsque la progression dépasse la taille autorisée, les lignes ou entrées complètes les plus anciennes sont supprimées afin que la fenêtre conserve l’activité la plus récente ; un élément individuel trop volumineux est remplacé par une alerte visible. La réponse finale distincte conserve un préfixe compatible UTF-8. Le contenu de la progression est échappé avant le rendu Markdown, afin que le raisonnement reste lisible sur plusieurs lignes, tandis que le contenu utilisateur, modèle ou outil ne puisse introduire de formatage Markdown ou HTML. Les valeurs inférieures à 512 utilisent ce minimum effectif afin qu’un événement Matrix sérialisé non vide puisse tenir. La limite ne s’applique pas aux demandes d’approbation, aux notifications système, à la livraison planifiée ni aux autres envois ordinaires. Choisissez un budget inférieur à la limite des événements Matrix. stream_reasoning contrôle la visibilité du raisonnement du fournisseur dans ce brouillon de progression : off supprime les mises à jour du brouillon dérivées du raisonnement, status émet des signaux de présence sans texte de raisonnement brut, et full émet le texte de raisonnement brut du fournisseur dans le brouillon de progression. stream_draft_delete contrôle si les transcriptions persistantes de la progression sont supprimées avant la publication de la réponse finale ; les échecs de suppression sont consignés et la livraison de la réponse finale se poursuit. Les brouillons contenant uniquement un espace réservé sont supprimés avant la réponse finale, même lorsque la conservation des transcriptions est activée. En mode multi_message, chaque paragraphe est publié dans son propre message du fil, et le découpage tient compte des clôtures de blocs de code : les lignes vides à l’intérieur des blocs délimités ne coupent pas un bloc de code entre plusieurs messages.

stream_tool_arguments contrôle les arguments d’outil qui apparaissent dans les lignes de progression single_message. Une configuration absente ou vide utilise des valeurs par défaut prudentes pour chaque outil ; les wrappers de skills, les plugins, les outils MCP et les noms non résolus n’affichent que leurs noms. Une seule entrée default_base sélectionne none, safe ou all, tandis que les règles d’outil portant un nom exact peuvent remplacer cette base ou ajouter et supprimer des champs :

stream_tool_arguments = [
    { default_base = "safe", argument_chars = 60 },
    { tool = "delegate", base = "none", include = ["agent", "background", "prompt"], argument_chars = 0 },
    { tool = "mock_tool", base = "all", exclude = ["token"] },
]

L’ordre des règles est sans importance, les entrées en double d’outil ou par défaut sont rejetées, et une règle dont la base est omise hérite de default_base. include ajoute des champs après la sélection de la base ; exclude les supprime. Les champs propres à l’exécution ne sont jamais affichés, les champs dont le nom correspond à des informations d’identification sont masqués récursivement dans chaque valeur sélectionnée, et chaque valeur rendue est soumise à une détection des fuites d’informations d’identification ainsi qu’à une normalisation sur une seule ligne avant de parvenir à Matrix. Inclure une valeur composite reste une décision explicite de divulgation de l’opérateur, mais ne contourne pas le masquage des informations d’identification. En mode safe, seuls les arguments scalaires de niveau supérieur recommandés sont rendus ; les valeurs nulles, les tableaux et les objets sont omis. Sélectionner all ou nommer un argument dans include constitue un choix explicite de l’opérateur autorisant le rendu JSON compact d’une valeur composite. La valeur de argument_chars dans l’entrée par défaut remplace la limite héritée par valeur de 60 ; ce même champ dans une règle d’outil la remplace pour cet outil. 0 conserve les valeurs complètes, tandis que message_max_bytes limite toujours la taille du brouillon rendu. Un all explicite s’applique aux outils inconnus ; utilisez une règle portant le nom exact lorsque vous activez les arguments pour un seul outil d’extension.

8. Récupération automatique après corruption de l’état local

Le store SQLite par défaut de matrix-rust-sdk est mono-appareil et suppose que la vue locale reste synchronisée avec le homeserver. Deux modes de défaillance brisent cette hypothèse de manière irrécupérable ; ZeroClaw détecte chacun d’eux au démarrage et (lorsque password + user_id sont tous deux configurés) efface automatiquement ~/.zeroclaw/state/matrix/ et se ré-authentifie afin qu’un nouvel appareil soit créé côté serveur.

• État de chiffrement orphelin. Un répertoire store/ existe mais pas session.json (nettoyage manuel, installation antérieure interrompue, etc.). Une nouvelle connexion par-dessus un état de chiffrement orphelin reproduit les conflits Duplicate one-time keys / SigningKeyChanged qui ne se résolvent pas d’eux-mêmes.
• Indicateur StateStoreDataKey::OneTimeKeyAlreadyUploaded défini. Le SDK persiste cette clé dans le magasin d’état la première fois qu’il détecte un téléversement OTK en double (selon le commentaire du SDK lui-même : « we forgot about some of our one-time keys. This will lead to UTDs. »). Elle survit aux redémarrages ; la seule solution est d’effacer et de réenregistrer.

Le décalage de device_id est détecté mais toléré, sans réinitialisation. Si channels.matrix.device_id diffère de l’identifiant d’appareil stocké dans session.json, le canal consigne un avertissement et utilise l’identifiant sauvegardé (qui correspond à la valeur réellement attribuée par le serveur d’accueil lors de la connexion). Réinitialiser en cas de décalage créerait une boucle de récupération, car la récupération automatique génère elle-même un nouvel identifiant, laissant la configuration et la session définitivement désynchronisées.

Lorsque recover() échoue lui-même (typiquement MAC check for the secret storage key failed), le canal journalise l’id de la clé de stockage de secrets par défaut du homeserver, si l’événement de clé contient des informations de phrase secrète, la longueur de l’entrée après suppression des espaces, et la chaîne d’erreur complète : ces éléments indiquent quelle couche a rejeté la clé de récupération sans divulguer sa valeur. Les échecs de récupération sont non fatals (ils ne déclenchent pas d’effacement automatique) ; le bot continue, le nouvel appareil ne sera simplement pas cross-signé.

Si password + user_id ne sont pas configurés, la récupération automatique ne peut pas s’exécuter : le canal s’interrompt avec une erreur exploitable indiquant les deux choix possibles : les configurer, ou exécuter manuellement rm -rf ~/.zeroclaw/state/matrix/.

Voir aussi

• -Déploiement réseau
• Référence de configuration : générée à partir du schéma en vigueur
• Vue d’ensemble des canaux