OpenClaw

Canal Matrix OpenClaw

Décentralisé
Moyen

Connectez OpenClaw à Matrix — un protocole de communication fédéré et ouvert. Cette intégration permet à votre assistant IA de participer aux salons Matrix et aux messages directs sur n'importe quel serveur domestique (matrix.org, Element ou auto-hébergé). OpenClaw se connecte via l'API Client-Serveur Matrix avec prise en charge optionnelle du chiffrement de bout en bout (E2EE) via le SDK crypto Rust. Le canal Matrix est fourni en tant que plugin et prend en charge la fédération, les fils de discussion, les réactions et les médias riches.

Info rapide
DifficultéMoyen
CatégorieDécentralisé
Fonctionnalités prises en charge5 / 6

Matrix Fonctionnalités prises en charge

Messages texte

Pris en charge

Médias et fichiers

Pris en charge

Réactions

Pris en charge

Fils de discussion

Pris en charge

Messages vocaux

Non pris en charge

Discussion de groupe

Pris en charge

Matrix Prérequis

  • Un compte Matrix actif sur n'importe quel serveur domestique (matrix.org, Element ou auto-hébergé)
  • Le plugin Matrix installé : openclaw plugins install @openclaw/matrix
  • OpenClaw Gateway en cours d'exécution et configuré
  • Node.js 18+ installé sur votre serveur

Matrix Configuration rapide

1

Installer le plugin Matrix

Le canal Matrix est fourni en tant que plugin séparé. Installez-le via 'openclaw plugins install @openclaw/matrix'. Le plugin sera téléchargé depuis le registre npm et activé automatiquement.

2

Obtenir les identifiants Matrix

Vous avez besoin soit d'un jeton d'accès, soit d'un nom d'utilisateur/mot de passe. Pour les jetons d'accès : utilisez curl pour appeler le point de terminaison de connexion de votre serveur domestique et copiez le jeton. Pour nom d'utilisateur/mot de passe : la passerelle se connectera automatiquement et stockera le jeton dans ~/.openclaw/credentials/matrix/credentials.json.

3

Ajouter la configuration du canal Matrix

Ajoutez la configuration du canal Matrix à ~/.openclaw/openclaw.json avec l'URL de votre serveur domestique et vos identifiants. Vous pouvez également utiliser les variables d'environnement MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN, MATRIX_USER_ID et MATRIX_PASSWORD.

4

Démarrer la passerelle et tester

Exécutez 'openclaw gateway' pour démarrer le service. Envoyez un message direct à votre utilisateur bot Matrix depuis un autre compte. Si vous utilisez la politique d'appairage par défaut, approuvez l'expéditeur via 'openclaw pairing approve matrix <code>' dans votre terminal.

Matrix Exemple de configuration

config.json
{
  "channels": {
    "matrix": {
      "enabled": true,
      "homeserver": "https://matrix.org",
      "accessToken": "your_access_token_here",
      "dmPolicy": "pairing"
    }
  }
}

Matrix Documentation Détaillée

Aperçu de l'architecture

OpenClaw se connecte à Matrix via l'API Client-Serveur, agissant comme un client Matrix standard. L'architecture est pilotée par événements : votre bot reçoit des événements (messages, réactions, changements de membres) via des requêtes de synchronisation par sondage long, les traite avec votre IA, puis envoie des réponses via l'API. Matrix est fédéré, ce qui signifie que votre bot peut communiquer avec des utilisateurs sur n'importe quel serveur domestique du réseau Matrix mondial — pas seulement le serveur domestique où votre compte bot est enregistré. C'est fondamentalement différent des plateformes centralisées comme WhatsApp ou Telegram. Le flux est : L'utilisateur envoie un message dans Matrix → Le serveur domestique route vers votre passerelle via sync → OpenClaw traite avec l'IA → réponse envoyée via l'API d'envoi d'événements → message délivré via la fédération.
La fédération signifie que votre bot sur matrix.org peut discuter avec des utilisateurs sur n'importe quel serveur domestique Matrix (par ex. element.io, serveur domestique de Mozilla ou instances auto-hébergées).
Le plugin Matrix utilise le sondage long par défaut. Pas besoin de webhooks ou d'URL publique — la passerelle établit une connexion sortante vers votre serveur domestique.

Méthodes d'authentification

OpenClaw prend en charge deux approches d'authentification pour Matrix : 1. **Jeton d'accès (recommandé)** — Obtenez un jeton en appelant l'API de connexion de votre serveur domestique via curl ou un client Matrix. Définissez channels.matrix.accessToken dans votre configuration. Le système récupère automatiquement votre ID utilisateur via le point de terminaison /whoami. 2. **Nom d'utilisateur/Mot de passe** — Définissez channels.matrix.userId et channels.matrix.password. OpenClaw appelle le point de terminaison de connexion automatiquement et stocke le jeton d'accès dans ~/.openclaw/credentials/matrix/credentials.json. Les variables d'environnement ont la priorité sur les fichiers de configuration : MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN, MATRIX_USER_ID, MATRIX_PASSWORD.
openclaw.json
# Méthode par jeton d'accès
{
  "channels": {
    "matrix": {
      "homeserver": "https://matrix.example.org",
      "accessToken": "syt_xxx..."
    }
  }
}

# Méthode par nom d'utilisateur/mot de passe
{
  "channels": {
    "matrix": {
      "homeserver": "https://matrix.example.org",
      "userId": "@bot:example.org",
      "password": "your_password"
    }
  }
}
Ne commitez jamais les jetons d'accès ou les mots de passe dans le contrôle de version. Utilisez des variables d'environnement pour les déploiements en production. Si votre jeton est compromis, déconnectez tous les appareils via votre client Matrix pour invalider tous les jetons, puis générez-en un nouveau.

Politiques DM

Les politiques DM (Message Direct) contrôlent qui peut interagir avec votre assistant IA. OpenClaw prend en charge quatre politiques : • pairing (par défaut) — Les utilisateurs inconnus reçoivent un code d'appairage au premier contact. Approuvez via 'openclaw pairing approve matrix <CODE>' pour accorder l'accès. Une fois approuvés, les utilisateurs peuvent discuter librement. • allowlist — Seuls les ID utilisateur Matrix explicitement listés dans channels.matrix.dm.allowFrom peuvent envoyer des messages au bot. Tous les autres sont ignorés silencieusement. • open — Toute personne qui envoie un message au bot reçoit une réponse. Nécessite allowFrom: ["*"]. À utiliser avec prudence. • disabled — La gestion des DM est complètement désactivée. Les listes d'autorisation acceptent les ID utilisateur Matrix complets au format @user:server (par ex. @alice:matrix.org).
openclaw.json
{
  "channels": {
    "matrix": {
      "dmPolicy": "allowlist",
      "dm": {
        "allowFrom": ["@alice:matrix.org", "@bob:example.org"]
      }
    }
  }
}

Support des discussions de groupe (Salons)

Les conversations de groupe Matrix sont appelées "salons". Par défaut, OpenClaw utilise une politique de liste d'autorisation pour les salons, nécessitant une activation basée sur les mentions. Vous pouvez configurer les salons auxquels le bot participe et comment il répond. Les salons sont identifiés par des ID de salon (!roomId:server) ou des alias de salon (#alias:server). Vous pouvez configurer des paramètres spécifiques au salon comme le comportement d'adhésion automatique, les exigences de mention et les listes d'autorisation d'utilisateurs par salon.
openclaw.json
{
  "channels": {
    "matrix": {
      "groupPolicy": "allowlist",
      "groups": {
        "!abc123:matrix.org": {
          "allow": true,
          "requireMention": false,
          "users": ["@alice:matrix.org"]
        },
        "#team-chat:example.org": {
          "allow": true
        }
      },
      "autoJoin": "allowlist"
    }
  }
}
Définissez autoJoin sur 'always' pour accepter automatiquement toutes les invitations de salon, 'allowlist' pour rejoindre uniquement les salons configurés, ou 'off' pour ignorer les invitations.
Utilisez requireMention: false pour activer les réponses automatiques sans mentionner le bot. Soyez prudent dans les salons à fort trafic.

Chiffrement de bout en bout (E2EE)

Matrix prend en charge le chiffrement de bout en bout (E2EE) via les protocoles Olm et Megolm. OpenClaw peut participer aux salons chiffrés lorsque vous activez le chiffrement via le SDK crypto Rust. Lorsqu'il est activé, le système déchiffre automatiquement les messages chiffrés, chiffre les médias sortants dans les salons sécurisés et stocke l'état cryptographique dans ~/.openclaw/matrix/accounts/ (SQLite). La vérification de l'appareil est requise lors de la première connexion — approuvez la demande de vérification dans Element ou un autre client Matrix pour activer le partage de clés. Si le chargement des modules crypto échoue, l'E2EE est désactivé et les salons chiffrés restent inaccessibles.
openclaw.json
{
  "channels": {
    "matrix": {
      "encryption": true
    }
  }
}
Le changement de jetons d'accès nécessite une nouvelle vérification de l'appareil. Conservez des sauvegardes de votre répertoire d'état crypto (~/.openclaw/matrix/accounts/) pour éviter de perdre l'accès à l'historique des messages chiffrés.

Fédération et sélection du serveur domestique

Matrix est un protocole fédéré — il n'y a pas de serveur central unique. Vous pouvez choisir d'enregistrer votre bot sur n'importe quel serveur domestique : • **matrix.org** — Le serveur domestique phare géré par la Matrix Foundation. Inscription ouverte, haute fiabilité, mais peut être plus lent en raison du trafic élevé. • **Element Matrix Services** — Serveurs domestiques hébergés professionnellement sur element.io avec des fonctionnalités premium et un support. • **Auto-hébergé** — Exécutez votre propre serveur domestique pour un contrôle et une confidentialité maximum. Synapse est l'option la plus mature et activement développée. Dendrite (Go) et Conduit (Rust) sont des alternatives plus légères adaptées aux petits déploiements, mais sont désormais en mode maintenance ou développement limité. Votre bot peut communiquer avec des utilisateurs sur n'importe quel serveur domestique, quel que soit l'endroit où il est enregistré, grâce à la fédération.
Pour les déploiements en production, envisagez d'utiliser un serveur domestique auto-hébergé ou Element Matrix Services pour un meilleur contrôle et de meilleures performances.
La fédération fonctionne de manière transparente — les utilisateurs n'ont pas besoin de savoir sur quel serveur domestique se trouve votre bot.

Fils de discussion et modes de réponse

Matrix prend en charge les conversations en fil via le type de relation m.thread. OpenClaw peut participer aux fils et contrôler la façon dont il gère les réponses. Le paramètre threadReplies contrôle le comportement des fils : 'off' désactive la prise en charge des fils, 'inbound' lit uniquement le contexte des fils, et 'always' lit et crée des réponses en fil. Le paramètre replyToMode contrôle l'attachement de métadonnées pour les relations de réponse.
openclaw.json
{
  "channels": {
    "matrix": {
      "threadReplies": "always",
      "replyToMode": "reference"
    }
  }
}

Gestion des médias et téléchargement de fichiers

Matrix prend en charge les médias riches, notamment les images, vidéos, audio et documents. OpenClaw gère automatiquement les téléchargements de médias — les fichiers sont téléchargés vers le dépôt de médias de votre serveur domestique et référencés dans les événements de message. Vous pouvez configurer la taille maximale des fichiers via le paramètre mediaMaxMb. La valeur par défaut est de 50 Mo pour les médias entrants, avec optimisation JPEG automatique et redimensionnement pour les images surdimensionnées lors des envois sortants.
openclaw.json
{
  "channels": {
    "matrix": {
      "mediaMaxMb": 50
    }
  }
}
Les téléchargements de médias sont stockés sur votre serveur domestique. Si vous utilisez un serveur domestique public comme matrix.org, soyez attentif aux limites de stockage et aux conditions d'utilisation.

Réactions et fonctionnalités riches

OpenClaw prend en charge les réactions Matrix (réponses emoji aux messages), les sondages, le partage de localisation (format geo URI) et d'autres fonctionnalités riches. Les réactions peuvent être envoyées et lues via des outils si activées. Vous pouvez contrôler des opérations spécifiques via la configuration actions, restreignant ce que votre agent IA peut faire (réactions, messages, épingles, informations sur les membres/canaux).
openclaw.json
{
  "channels": {
    "matrix": {
      "actions": {
        "reactions": true,
        "messages": true,
        "pins": false
      }
    }
  }
}

Pourquoi Matrix pour l'IA auto-hébergée ?

Matrix est un excellent choix pour les assistants IA auto-hébergés car : • **Vraiment ouvert** — Spécification ouverte, pas de verrouillage propriétaire, plusieurs implémentations de clients et de serveurs. • **Fédéré** — Pas de point unique de contrôle ou de défaillance. Votre bot peut communiquer sur l'ensemble du réseau Matrix mondial. • **Axé sur la confidentialité** — Support E2EE, options d'auto-hébergement et pas de collecte de données centralisée. • **Fonctionnalités riches** — Fils de discussion, réactions, médias, sondages et types d'événements extensibles. • **Pas de numéro de téléphone requis** — Contrairement à WhatsApp ou Signal, Matrix ne nécessite pas de numéro de téléphone pour l'inscription. Le compromis est la complexité : le modèle de fédération de Matrix et la configuration E2EE peuvent être plus complexes que les plateformes centralisées. Pour les utilisateurs et les équipes soucieux de la confidentialité, ce compromis en vaut la peine.

Matrix Référence de Configuration

enabled
Type: booleanDefault: true

Activer ou désactiver le canal Matrix

homeserver
Type: stringDefault: "https://matrix.org"

URL du serveur domestique Matrix (par ex. https://matrix.org, https://element.io)

accessToken
Type: stringDefault: ""

Jeton d'accès Matrix pour l'authentification (méthode recommandée)

userId
Type: stringDefault: ""

ID utilisateur Matrix (par ex. @bot:matrix.org) — utilisé avec l'authentification par mot de passe

password
Type: stringDefault: ""

Mot de passe du compte Matrix — utilisé avec userId pour la connexion

encryption
Type: booleanDefault: false

Activer le chiffrement de bout en bout via le SDK crypto Rust

dmPolicy
Type: stringDefault: "pairing"

Politique d'accès DM : pairing, allowlist, open ou disabled

dm.allowFrom
Type: arrayDefault: []

ID utilisateur Matrix autorisés pour les DM (par ex. [@alice:matrix.org])

groupPolicy
Type: stringDefault: "allowlist"

Politique de salon : allowlist ou disabled

groups
Type: objectDefault: {}

Configuration spécifique au salon (ID ou alias de salon comme clé)

groups.<roomId>.allow
Type: booleanDefault: false

Permettre au bot de participer à ce salon

groups.<roomId>.requireMention
Type: booleanDefault: true

Exiger la mention du bot pour déclencher des réponses dans ce salon

groups.<roomId>.users
Type: arrayDefault: []

Liste d'autorisation d'utilisateurs par salon (ID utilisateur Matrix)

autoJoin
Type: stringDefault: "allowlist"

Adhésion automatique aux invitations de salon : always, allowlist ou off

textChunkLimit
Type: numberDefault: 4096

Nombre maximum de caractères par message sortant

chunkMode
Type: stringDefault: "length"

Comment diviser les longues réponses : length (limite stricte) ou newline (limites de paragraphe)

threadReplies
Type: stringDefault: "inbound"

Comportement des fils : off, inbound (lecture seule) ou always (lecture + création)

replyToMode
Type: stringDefault: "reference"

Mode d'attachement de métadonnées de réponse

mediaMaxMb
Type: numberDefault: 50

Taille maximale du fichier média en mégaoctets

actions.reactions
Type: booleanDefault: true

Permettre à l'agent d'envoyer/lire des réactions

actions.messages
Type: booleanDefault: true

Permettre à l'agent de lire/envoyer/modifier/supprimer des messages

actions.pins
Type: booleanDefault: true

Permettre à l'agent d'épingler/désépingler des messages

actions.memberInfo
Type: booleanDefault: true

Permettre à l'agent de rechercher les informations des membres du salon

actions.channelInfo
Type: booleanDefault: true

Permettre à l'agent de récupérer les informations du salon/canal

Matrix Questions Fréquentes

Matrix Dépannage

Le bot ne reçoit pas de messages

La politique DM bloque les messages, ou le bot n'est pas dans le salon

Vérifiez les paramètres channels.matrix.dmPolicy et dm.allowFrom. Pour les salons, assurez-vous que le salon est dans votre liste d'autorisation groups et que le bot a été invité et a rejoint.
Les salons chiffrés E2EE n'affichent pas de messages

Appareil non vérifié ou échec du chargement des modules crypto

Vérifiez l'appareil de votre bot dans Element ou un autre client Matrix. Vérifiez les journaux pour les erreurs de chargement des modules crypto. Assurez-vous que channels.matrix.encryption est défini sur true.
Jeton d'accès invalide ou expiré

Le jeton a été révoqué ou invalidé sur le serveur domestique

Générez un nouveau jeton d'accès en vous reconnectant. Si vous utilisez nom d'utilisateur/mot de passe, supprimez ~/.openclaw/credentials/matrix/credentials.json et redémarrez la passerelle.
Le bot rejoint le salon mais ne répond pas

Le salon n'est pas dans la liste d'autorisation ou requireMention est activé

Ajoutez le salon à channels.matrix.groups avec allow: true. Si requireMention est true, les utilisateurs doivent mentionner le bot pour obtenir une réponse.
Erreurs de fédération avec d'autres serveurs domestiques

Problèmes de connectivité du serveur domestique ou de fédération

Vérifiez l'état de fédération de votre serveur domestique sur federationtester.matrix.org. Vérifiez les enregistrements DNS SRV et les certificats SSL si auto-hébergé.
L'installation du plugin échoue

Accès au registre npm ou incompatibilité de version Node.js

Assurez-vous que Node.js 18+ est installé. Essayez 'openclaw plugins install @openclaw/matrix --verbose' pour des journaux d'erreur détaillés. Vérifiez la connectivité réseau au registre npm.
Voir la documentation complèteRetour à tous les canaux

Canaux associés

Nostr

Advanced

OpenClaw integration decentralisee NIP-04 DM

Guide de configuration

Tlon

Advanced

OpenClaw integration messagerie Urbit

Guide de configuration