Mattermost (plugin)

Statut : pris en charge via plugin (jeton bot + evenements WebSocket). Les canaux, groupes et DMs sont pris en charge. Mattermost est une plateforme de messagerie d’equipe auto-hebergeable ; voir le site officiel sur mattermost.com pour les details du produit et les telechargements.

Plugin requis

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

Installation via CLI (registre npm) :

openclaw plugins install @openclaw/mattermost

Checkout local (execution depuis un depot git) :

openclaw plugins install ./extensions/mattermost

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

Details : Plugins

Configuration rapide

Installez le plugin Mattermost.
Creez un compte bot Mattermost et copiez le jeton bot.
Copiez l’URL de base Mattermost (ex : https://chat.example.com).
Configurez OpenClaw et demarrez la gateway.

Configuration minimale :

{
  channels: {
    mattermost: {
      enabled: true,
      botToken: "mm-token",
      baseUrl: "https://chat.example.com",
      dmPolicy: "pairing",
    },
  },
}

Commandes slash natives

Les commandes slash natives sont opt-in. Quand elles sont activees, OpenClaw enregistre des commandes slash oc_* via l’API Mattermost et recoit les callbacks POST sur le serveur HTTP de la gateway.

{
  channels: {
    mattermost: {
      commands: {
        native: true,
        nativeSkills: true,
        callbackPath: "/api/channels/mattermost/command",
        // Utilisez quand Mattermost ne peut pas atteindre la gateway directement (proxy inverse/URL publique).
        callbackUrl: "https://gateway.example.com/api/channels/mattermost/command",
      },
    },
  },
}

Remarques :

native: "auto" est desactive par defaut pour Mattermost. Definissez native: true pour activer.
Si callbackUrl est omis, OpenClaw en derive un depuis host/port de la gateway + callbackPath.
Pour les configurations multi-comptes, commands peut etre defini au niveau superieur ou sous channels.mattermost.accounts.<id>.commands (les valeurs de compte surchargent les champs de niveau superieur).
Les callbacks de commande sont valides avec des jetons par commande et echouent de maniere fermee quand les verifications de jeton echouent.
Exigence d’accessibilite : le point de terminaison de callback doit etre accessible depuis le serveur Mattermost.

Variables d’environnement (compte par defaut)

Definissez-les sur l’hote de la gateway si vous preferez les variables d’env :

MATTERMOST_BOT_TOKEN=...
MATTERMOST_URL=https://chat.example.com

Les variables d’env s’appliquent uniquement au compte par defaut (default). Les autres comptes doivent utiliser les valeurs de configuration.

Modes de chat

Mattermost repond automatiquement aux DMs. Le comportement dans les canaux est controle par chatmode :

oncall (par defaut) : repondre uniquement quand @mentionne dans les canaux.
onmessage : repondre a chaque message de canal.
onchar : repondre quand un message commence par un prefixe declencheur.

Exemple de configuration :

{
  channels: {
    mattermost: {
      chatmode: "onchar",
      oncharPrefixes: [">", "!"],
    },
  },
}

Remarques :

onchar repond toujours aux @mentions explicites.
channels.mattermost.requireMention est respecte pour les configs legacy mais chatmode est prefere.

Fils et sessions

Utilisez channels.mattermost.replyToMode pour controler si les reponses de canal et de groupe restent dans le canal principal ou demarrent un fil sous le post declencheur.

off (par defaut) : ne repondre dans un fil que quand le post entrant est deja dans un fil.
first : pour les posts de canal/groupe de premier niveau, demarrer un fil sous ce post et router la conversation vers une session au scope du fil.
all : meme comportement que first pour Mattermost aujourd’hui.
Les messages directs ignorent ce parametre et restent sans fil.

Controle d’acces (DMs)

Par defaut : channels.mattermost.dmPolicy = "pairing" (les expediteurs inconnus recoivent un code d’appairage).
Approbation via :
- openclaw pairing list mattermost
- openclaw pairing approve mattermost <CODE>
DMs publics : channels.mattermost.dmPolicy="open" plus channels.mattermost.allowFrom=["*"].

Canaux (groupes)

Par defaut : channels.mattermost.groupPolicy = "allowlist" (filtre par mention).
Autorisez les expediteurs avec channels.mattermost.groupAllowFrom (IDs utilisateur recommandes).
La correspondance par @username est mutable et n’est activee que quand channels.mattermost.dangerouslyAllowNameMatching: true.
Canaux ouverts : channels.mattermost.groupPolicy="open" (filtre par mention).
Remarque d’execution : si channels.mattermost est completement absent, l’execution se replie sur groupPolicy="allowlist" pour les verifications de groupe (meme si channels.defaults.groupPolicy est defini).

Cibles pour la livraison sortante

Utilisez ces formats de cible avec openclaw message send ou cron/webhooks :

channel:<id> pour un canal
user:<id> pour un DM
@username pour un DM (resolu via l’API Mattermost)

Les IDs opaques nus (comme 64ifufp...) sont ambigus dans Mattermost (ID utilisateur vs ID canal).

OpenClaw les resout utilisateur d’abord :

Si l’ID existe comme utilisateur (GET /api/v4/users/<id> reussit), OpenClaw envoie un DM en resolvant le canal direct via /api/v4/channels/direct.
Sinon l’ID est traite comme un ID canal.

Si vous avez besoin d’un comportement deterministe, utilisez toujours les prefixes explicites (user:<id> / channel:<id>).

Reactions (outil message)

Utilisez message action=react avec channel=mattermost.
messageId est l’ID du post Mattermost.
emoji accepte des noms comme thumbsup ou :+1: (les deux-points sont optionnels).
Definissez remove=true (booleen) pour supprimer une reaction.
Les evenements d’ajout/suppression de reaction sont transmis comme evenements systeme a la session d’agent routee.

Exemples :

message action=react channel=mattermost target=channel:<channelId> messageId=<postId> emoji=thumbsup
message action=react channel=mattermost target=channel:<channelId> messageId=<postId> emoji=thumbsup remove=true

Configuration :

channels.mattermost.actions.reactions : activer/desactiver les actions de reaction (par defaut true).
Surcharge par compte : channels.mattermost.accounts.<id>.actions.reactions.

Boutons interactifs (outil message)

Envoyez des messages avec des boutons cliquables. Quand un utilisateur clique sur un bouton, l’agent recoit la selection et peut repondre.

Activez les boutons en ajoutant inlineButtons aux capabilities du canal :

{
  channels: {
    mattermost: {
      capabilities: ["inlineButtons"],
    },
  },
}

Utilisez message action=send avec un parametre buttons. Les boutons sont un tableau 2D (rangees de boutons) :

message action=send channel=mattermost target=channel:<channelId> buttons=[[{"text":"Oui","callback_data":"yes"},{"text":"Non","callback_data":"no"}]]

Champs de bouton :

text (requis) : label d’affichage.
callback_data (requis) : valeur renvoyee au clic (utilisee comme ID d’action).
style (optionnel) : "default", "primary" ou "danger".

Adaptateur d’annuaire

Le plugin Mattermost inclut un adaptateur d’annuaire qui resout les noms de canaux et d’utilisateurs via l’API Mattermost. Cela active les cibles #channel-name et @username dans openclaw message send et les livraisons cron/webhook.

Aucune configuration necessaire — l’adaptateur utilise le jeton bot de la configuration du compte.

Multi-comptes

Mattermost supporte plusieurs comptes sous channels.mattermost.accounts :

{
  channels: {
    mattermost: {
      accounts: {
        default: { name: "Principal", botToken: "mm-token", baseUrl: "https://chat.example.com" },
        alerts: { name: "Alertes", botToken: "mm-token-2", baseUrl: "https://alerts.example.com" },
      },
    },
  },
}

Depannage

Pas de reponses dans les canaux : assurez-vous que le bot est dans le canal et mentionnez-le (oncall), utilisez un prefixe declencheur (onchar) ou definissez chatmode: "onmessage".
Erreurs d’authentification : verifiez le jeton bot, l’URL de base et si le compte est active.
Problemes multi-comptes : les variables d’env s’appliquent uniquement au compte default.
Les boutons apparaissent comme des boites blanches : l’agent envoie peut-etre des donnees de bouton malformees. Verifiez que chaque bouton a les champs text et callback_data.
Les boutons s’affichent mais les clics ne font rien : verifiez AllowedUntrustedInternalConnections dans la config du serveur Mattermost inclut 127.0.0.1 localhost, et que EnablePostActionIntegration est true dans ServiceSettings.
Les boutons retournent 404 au clic : l’id du bouton contient probablement des tirets ou des underscores. Le routeur d’action Mattermost casse avec les IDs non-alphanumeriques. Utilisez uniquement [a-zA-Z0-9].
La gateway journalise invalid _token : decalage HMAC. Verifiez que vous signez tous les champs du contexte (pas un sous-ensemble), utilisez des cles triees et du JSON compact (sans espaces). Voir la section HMAC ci-dessus.