​

Matrix (plugin)

​

Plugin requis

openclaw plugins install @openclaw/matrix

openclaw plugins install ./extensions/matrix

​

Configuration

1. Installez le plugin Matrix :
   • Depuis npm : openclaw plugins install @openclaw/matrix
   • Depuis une verification locale : openclaw plugins install ./extensions/matrix
2. Creez un compte Matrix sur un homeserver :
   • Parcourez les options d’hebergement sur https://matrix.org/ecosystem/hosting/
   • Ou hebergez-le vous-meme.
3. Obtenez un jeton d’acces pour le compte du bot :
   • Utilisez l’API de connexion Matrix avec curl sur votre homeserver :
   curl --request POST \
     --url https://matrix.example.org/_matrix/client/v3/login \
     --header 'Content-Type: application/json' \
     --data '{
     "type": "m.login.password",
     "identifier": {
       "type": "m.id.user",
       "user": "your-user-name"
     },
     "password": "your-password"
   }'
   
   • Remplacez matrix.example.org par l’URL de votre homeserver.
   • Ou definissez channels.matrix.userId + channels.matrix.password : OpenClaw appelle le meme point de terminaison de connexion, stocke le jeton d’acces dans ~/.openclaw/credentials/matrix/credentials.json, et le reutilise au demarrage suivant.
4. Configurez les informations d’identification :
   • Env : MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN (ou MATRIX_USER_ID + MATRIX_PASSWORD)
   • Ou config : channels.matrix.*
   • Si les deux sont definis, la configuration est prioritaire.
   • Avec un jeton d’acces : l’ID utilisateur est recupere automatiquement via /whoami.
   • Lorsqu’il est defini, channels.matrix.userId doit etre l’ID Matrix complet (exemple : @bot:example.org).
5. Redemarrez la Gateway (passerelle) (ou terminez la prise en main).
6. Lancez un Message prive avec le bot ou invitez-le dans un salon depuis n’importe quel client Matrix (Element, Beeper, etc. ; voir https://matrix.org/ecosystem/clients/). Beeper necessite l’E2EE ; definissez donc channels.matrix.encryption: true et verifiez l’appareil.

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_***",
      dm: { policy: "pairing" },
    },
  },
}

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_***",
      encryption: true,
      dm: { policy: "pairing" },
    },
  },
}

​

Chiffrement (E2EE)

• Si le module crypto se charge, les salons chiffres sont dechiffres automatiquement.
• Les médias sortants sont chiffrés lors de l’envoi vers des salles chiffrées.
• Lors de la premiere connexion, OpenClaw demande la verification de l’appareil depuis vos autres sessions.
• Verifiez l’appareil dans un autre client Matrix (Element, etc.) pour activer le partage de cles.
• Si le module crypto ne peut pas etre charge, l’E2EE est desactive et les salons chiffres ne seront pas dechiffres ; OpenClaw enregistre un avertissement.
• Si vous voyez des erreurs de module crypto manquant (par exemple, @matrix-org/matrix-sdk-crypto-nodejs-*), autorisez les scripts de build pour @matrix-org/matrix-sdk-crypto-nodejs et executez pnpm rebuild @matrix-org/matrix-sdk-crypto-nodejs ou recuperez le binaire avec node node_modules/@matrix-org/matrix-sdk-crypto-nodejs/download-lib.js.

​

Multi-compte

{
  channels: {
    matrix: {
      enabled: true,
      dm: { policy: "pairing" },
      accounts: {
        assistant: {
          name: "Main assistant",
          homeserver: "https://matrix.example.org",
          accessToken: "syt_assistant_***",
          encryption: true,
        },
        alerts: {
          name: "Alerts bot",
          homeserver: "https://matrix.example.org",
          accessToken: "syt_alerts_***",
          dm: { policy: "allowlist", allowFrom: ["@admin:example.org"] },
        },
      },
    },
  },
}

• Le démarrage des comptes est sérialisé afin d’éviter les conditions de concurrence liées aux imports simultanés de modules.
• Les variables d’environnement (MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN, etc.) s’appliquent uniquement au compte par défaut.
• Les paramètres de base du canal (politique DM, politique de groupe, filtrage des mentions, etc.) s’appliquent à tous les comptes sauf remplacement au niveau du compte.
• Utilisez bindings[].match.accountId pour router chaque compte vers un agent différent.
• L’état cryptographique est stocké par compte + access token (magasins de clés séparés par compte).

​

Modele de routage

• Les reponses retournent toujours vers Matrix.
• Les Messages prives partagent la session principale de l’agent ; les salons correspondent a des sessions de groupe.

​

Contrôle d’accès (DMs)

• Par defaut : channels.matrix.dm.policy = "pairing". Les expediteurs inconnus recoivent un code d’appairage.
• Approbation via :
  • openclaw pairing list matrix
  • openclaw pairing approve matrix <CODE>
• Messages prives publics : channels.matrix.dm.policy="open" plus channels.matrix.dm.allowFrom=["*"].
• channels.matrix.dm.allowFrom accepte des ID utilisateur Matrix complets (exemple : @user:server). L’assistant resolve les noms d’affichage en ID utilisateur lorsque la recherche d’annuaire trouve une correspondance unique exacte.
• N’utilisez pas de noms d’affichage ni de localparts simples (exemple : "Alice" ou "alice"). Ils sont ambigus et ignorés pour la correspondance avec la liste d’autorisation. Utilisez des identifiants complets @user:server.

​

Salons (groupes)

• Par defaut : channels.matrix.groupPolicy = "allowlist" (controle par mention). Utilisez channels.defaults.groupPolicy pour remplacer la valeur par defaut lorsqu’elle n’est pas definie.
• Autorisez des salons via channels.matrix.groups (ID de salon ou alias ; les noms sont resolus en ID lorsque la recherche d’annuaire trouve une correspondance unique exacte) :

{
  channels: {
    matrix: {
      groupPolicy: "allowlist",
      groups: {
        "!roomId:example.org": { allow: true },
        "#alias:example.org": { allow: true },
      },
      groupAllowFrom: ["@owner:example.org"],
    },
  },
}

• requireMention: false active la reponse automatique dans ce salon.
• groups."*" peut definir des valeurs par defaut pour le controle par mention entre les salons.
• groupAllowFrom restreint quels expediteurs peuvent declencher le bot dans les salons (ID utilisateur Matrix complets).
• Des listes d’autorisation users par salon peuvent restreindre davantage les expediteurs au sein d’un salon specifique (utilisez des ID utilisateur Matrix complets).
• L’assistant de configuration demande des listes d’autorisation de salons (ID de salon, alias ou noms) et ne resolve les noms qu’en cas de correspondance exacte et unique.
• Au demarrage, OpenClaw resolve les noms de salon/utilisateur dans les listes d’autorisation en ID et consigne le mapping ; les entrees non resolues sont ignorees pour la correspondance des listes d’autorisation.
• Les invitations sont rejointes automatiquement par defaut ; controlez ce comportement avec channels.matrix.autoJoin et channels.matrix.autoJoinAllowlist.
• Pour n’autoriser aucun salon, definissez channels.matrix.groupPolicy: "disabled" (ou conservez une liste d’autorisation vide).
• Cle heritee : channels.matrix.rooms (meme structure que groups).

​

Fil de discussion

• Les reponses en fil sont prises en charge.
• channels.matrix.threadReplies controle si les reponses restent dans les fils :
  • off, inbound (par defaut), always
• channels.matrix.replyToMode controle les metadonnees de reponse lorsque l’on ne repond pas dans un fil :
  • off (par defaut), first, all

​

Capacites

​

Problemes courants

openclaw models auth paste-token --provider anthropic
openclaw models status

openclaw pairing list matrix

• Connecté mais les messages de la salle ont été ignorés: espace bloqué par groupPolicy ou la liste d’autorisations de salle.
• DMs ignorés: expéditeur en attente d’approbation lorsque channels.matrix.dm.policy="appairage".
• Les salles chiffrées échouent : le support du cryptage ou les paramètres de chiffrement ne correspondent pas.

​

Reference de configuration (Matrix)

• channels.matrix.enabled : activer/desactiver le demarrage du canal.
• channels.matrix.homeserver : URL du homeserver.
• channels.matrix.userId : ID utilisateur Matrix (optionnel avec jeton d’acces).
• channels.matrix.accessToken : jeton d’acces.
• channels.matrix.password : mot de passe pour la connexion (jeton stocke).
• channels.matrix.deviceName : nom d’affichage de l’appareil.
• channels.matrix.encryption : activer l’E2EE (par defaut : false).
• channels.matrix.initialSyncLimit : limite de synchronisation initiale.
• channels.matrix.threadReplies : off | inbound | always (par defaut : inbound).
• channels.matrix.textChunkLimit : taille des fragments de texte sortants (caracteres).
• channels.matrix.chunkMode : length (par defaut) ou newline pour fractionner sur les lignes vides (frontieres de paragraphes) avant le fractionnement par longueur.
• channels.matrix.dm.policy : pairing | allowlist | open | disabled (par defaut : appairage).
• channels.matrix.dm.allowFrom : liste d’autorisation des Messages prives (ID utilisateur Matrix complets). open requiert "*". L’assistant resolve les noms en ID lorsque c’est possible.
• channels.matrix.groupPolicy : allowlist | open | disabled (par defaut : liste d’autorisation).
• channels.matrix.groupAllowFrom : expediteurs autorises pour les messages de groupe (ID utilisateur Matrix complets).
• channels.matrix.allowlistOnly : forcer les regles de liste d’autorisation pour Messages prives + salons.
• channels.matrix.groups : liste d’autorisation de groupe + carte des parametres par salon.
• channels.matrix.rooms : liste d’autorisation/configuration de groupe heritee.
• channels.matrix.replyToMode : mode de reponse pour les fils/balises.
• channels.matrix.mediaMaxMb : plafond de media entrant/sortant (Mo).
• channels.matrix.autoJoin : gestion des invitations (always | allowlist | off, par defaut : toujours).
• channels.matrix.autoJoinAllowlist : ID/alias de salons autorises pour l’adhesion automatique.
• channels.matrix.accounts : configuration multi-compte indexée par ID de compte (chaque compte hérite des paramètres de niveau supérieur).
• channels.matrix.actions : controle d’outils par action (reactions/messages/epingles/memberInfo/channelInfo).