Matrix (plugin)

Matrix est un protocole de messagerie ouvert et decentralise. OpenClaw se connecte en tant qu’utilisateur Matrix sur n’importe quel serveur, vous avez donc besoin d’un compte Matrix pour le bot. Une fois connecte, vous pouvez envoyer des DMs au bot directement ou l’inviter dans des salons (les « groupes » Matrix). Beeper est aussi un client valide, mais il necessite l’activation du E2EE.

Statut : pris en charge via plugin (@vector-im/matrix-bot-sdk). Messages directs, salons, fils, medias, reactions, sondages (envoi + poll-start en texte), localisation et E2EE (avec support crypto).

Plugin requis

Matrix est fourni comme plugin et n’est pas inclus dans l’installation de base.

Installation via CLI (registre npm) :

openclaw plugins install @openclaw/matrix

Checkout local (execution depuis un depot git) :

openclaw plugins install ./extensions/matrix

Si vous choisissez Matrix pendant la configuration/l’onboarding et qu’un checkout git est detecte, OpenClaw proposera automatiquement le chemin d’installation local.

Details : Plugins

Configuration

Installez le plugin Matrix :
- Depuis npm : openclaw plugins install @openclaw/matrix
- Depuis un checkout local : openclaw plugins install ./extensions/matrix
Creez un compte Matrix sur un serveur :
- Parcourez les options d’hebergement sur https://matrix.org/ecosystem/hosting/
- Ou hebergez-le vous-meme.
Obtenez un jeton d’acces pour le compte bot :
- Utilisez l’API de connexion Matrix avec curl sur votre serveur :
```
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 serveur.
- Ou definissez channels.matrix.userId + channels.matrix.password : OpenClaw appelle le meme point de connexion, stocke le jeton d’acces dans ~/.openclaw/credentials/matrix/credentials.json, et le reutilise au prochain demarrage.
Configurez les identifiants :
- Env : MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN (ou MATRIX_USER_ID + MATRIX_PASSWORD)
- Ou config : channels.matrix.*
- Si les deux sont definis, la config a la priorite.
- Avec un jeton d’acces : l’ID utilisateur est recupere automatiquement via /whoami.
- Quand defini, channels.matrix.userId devrait etre l’ID Matrix complet (exemple : @bot:example.org).
Redemarrez la gateway (ou terminez l’onboarding).
Demarrez un DM 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 le E2EE, definissez donc channels.matrix.encryption: true et verifiez l’appareil.

Configuration minimale (jeton d’acces, ID utilisateur auto-recupere) :

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

Configuration E2EE (chiffrement de bout en bout active) :

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

Chiffrement (E2EE)

Le chiffrement de bout en bout est pris en charge via le SDK crypto Rust.

Activez avec channels.matrix.encryption: true :

Si le module crypto se charge, les salons chiffres sont dechiffres automatiquement.
Les medias sortants sont chiffres lors de l’envoi dans des salons chiffres.
A 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, le E2EE est desactive et les salons chiffres ne seront pas dechiffres ; OpenClaw journalise 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.

L’etat crypto est stocke par compte + jeton d’acces dans ~/.openclaw/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/crypto/ (base de donnees SQLite). L’etat de synchronisation se trouve a cote dans bot-storage.json. Si le jeton d’acces (appareil) change, un nouveau magasin est cree et le bot doit etre re-verifie pour les salons chiffres.

Verification d’appareil : Quand le E2EE est active, le bot demandera la verification depuis vos autres sessions au demarrage. Ouvrez Element (ou un autre client) et approuvez la demande de verification pour etablir la confiance. Une fois verifie, le bot peut dechiffrer les messages dans les salons chiffres.

Multi-comptes

Support multi-comptes : utilisez channels.matrix.accounts avec des identifiants par compte et un name optionnel. Voir gateway/configuration pour le patron partage.

Chaque compte s’execute comme un utilisateur Matrix separe sur n’importe quel serveur. La config par compte herite des parametres de niveau superieur channels.matrix et peut surcharger n’importe quelle option (politique DM, groupes, chiffrement, etc.).

{
  channels: {
    matrix: {
      enabled: true,
      dm: { policy: "pairing" },
      accounts: {
        assistant: {
          name: "Assistant principal",
          homeserver: "https://matrix.example.org",
          accessToken: "syt_assistant_***",
          encryption: true,
        },
        alerts: {
          name: "Bot d'alertes",
          homeserver: "https://matrix.example.org",
          accessToken: "syt_alerts_***",
          dm: { policy: "allowlist", allowFrom: ["@admin:example.org"] },
        },
      },
    },
  },
}

Remarques :

Le demarrage des comptes est serialise pour eviter les conditions de concurrence avec les imports de modules concurrents.
Les variables d’env (MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN, etc.) ne s’appliquent qu’au compte par defaut.
Les parametres de base du canal (politique DM, politique de groupe, filtrage par mention, etc.) s’appliquent a tous les comptes sauf surcharge par compte.
Utilisez bindings[].match.accountId pour router chaque compte vers un agent different.
L’etat crypto est stocke par compte + jeton d’acces (magasins de cles separes par compte).

Modele de routage

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

Controle d’acces (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>
DMs publics : channels.matrix.dm.policy="open" plus channels.matrix.dm.allowFrom=["*"].
channels.matrix.dm.allowFrom accepte les IDs utilisateur Matrix complets (exemple : @user:server). L’assistant resout les noms d’affichage en IDs utilisateur quand la recherche d’annuaire trouve une correspondance unique exacte.
N’utilisez pas de noms d’affichage ou de localparts nus (exemple : "Alice" ou "alice"). Ils sont ambigus et sont ignores pour la correspondance de liste d’autorisation. Utilisez les IDs complets @user:server.

Salons (groupes)

Par defaut : channels.matrix.groupPolicy = "allowlist" (filtre par mention). Utilisez channels.defaults.groupPolicy pour surcharger la valeur par defaut quand non defini.
Remarque d’execution : si channels.matrix est completement absent, l’execution se replie sur groupPolicy="allowlist" pour les verifications de salon (meme si channels.defaults.groupPolicy est defini).
Autorisez les salons avec channels.matrix.groups (IDs de salon ou alias ; les noms sont resolus en IDs quand 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 les valeurs par defaut du filtrage par mention entre les salons.
groupAllowFrom restreint quels expediteurs peuvent declencher le bot dans les salons (IDs utilisateur Matrix complets).
Les listes users par salon peuvent restreindre davantage les expediteurs a l’interieur d’un salon specifique (utilisez les IDs utilisateur Matrix complets).
L’assistant de configuration demande les listes d’autorisation de salon (IDs de salon, alias ou noms) et resout les noms uniquement sur une correspondance exacte et unique.
Au demarrage, OpenClaw resout les noms de salon/utilisateur dans les listes d’autorisation en IDs et journalise la correspondance ; les entrees non resolues sont ignorees pour la correspondance de liste d’autorisation.
Les invitations sont auto-acceptees par defaut ; controlez avec channels.matrix.autoJoin et channels.matrix.autoJoinAllowlist.
Pour n’autoriser aucun salon, definissez channels.matrix.groupPolicy: "disabled" (ou gardez une liste d’autorisation vide).
Cle legacy : channels.matrix.rooms (meme forme que groups).

Fils

Le threading des reponses est pris en charge.
channels.matrix.threadReplies controle si les reponses restent dans les fils :
- off, inbound (par defaut), always
channels.matrix.replyToMode controle les metadonnees reply-to quand on ne repond pas dans un fil :
- off (par defaut), first, all

Fonctionnalites

Fonctionnalite	Statut
Messages prives	Pris en charge
Salons	Pris en charge
Fils	Pris en charge
Medias	Pris en charge
E2EE	Pris en charge (module crypto requis)
Reactions	Pris en charge (envoi/lecture via outils)
Sondages	Envoi pris en charge ; les poll starts entrants sont convertis en texte (reponses/fins ignorees)
Localisation	Pris en charge (URI geo ; altitude ignoree)
Commandes natives	Pris en charge

Depannage

Executez cette echelle en premier :

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

Puis confirmez l’etat d’appairage DM si necessaire :

openclaw pairing list matrix

Echecs courants :

Connecte mais les messages de salon sont ignores : salon bloque par groupPolicy ou la liste d’autorisation de salon.
DMs ignores : expediteur en attente d’approbation quand channels.matrix.dm.policy="pairing".
Les salons chiffres echouent : support crypto ou parametres de chiffrement non concordants.

Pour le flux de triage : /channels/troubleshooting.

Reference de configuration (Matrix)

Configuration complete : Configuration

Options du fournisseur :

channels.matrix.enabled : activer/desactiver le demarrage du canal.
channels.matrix.homeserver : URL du serveur.
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 le E2EE (par defaut : false).
channels.matrix.initialSyncLimit : limite de synchronisation initiale.
channels.matrix.threadReplies : off | inbound | always (par defaut : inbound).
channels.matrix.textChunkLimit : taille de decoupe du texte sortant (caracteres).
channels.matrix.chunkMode : length (par defaut) ou newline pour decouper sur les lignes vides (limites de paragraphe) avant la decoupe par longueur.
channels.matrix.dm.policy : pairing | allowlist | open | disabled (par defaut : pairing).
channels.matrix.dm.allowFrom : liste d’autorisation DM (IDs utilisateur Matrix complets). open necessite "*". L’assistant resout les noms en IDs quand possible.
channels.matrix.groupPolicy : allowlist | open | disabled (par defaut : allowlist).
channels.matrix.groupAllowFrom : expediteurs autorises pour les messages de groupe (IDs utilisateur Matrix complets).
channels.matrix.allowlistOnly : forcer les regles de liste d’autorisation pour DMs + salons.
channels.matrix.groups : liste d’autorisation de groupe + parametres par salon.
channels.matrix.rooms : liste d’autorisation/config de groupe legacy.
channels.matrix.replyToMode : mode reply-to pour les fils/tags.
channels.matrix.mediaMaxMb : limite de media entrant/sortant (Mo).
channels.matrix.autoJoin : gestion des invitations (always | allowlist | off, par defaut : always).
channels.matrix.autoJoinAllowlist : IDs/alias de salon autorises pour l’auto-join.
channels.matrix.accounts : configuration multi-comptes par ID de compte (chaque compte herite des parametres de niveau superieur).
channels.matrix.actions : controle par action des outils (reactions/messages/pins/memberInfo/channelInfo).