Mattermost

Client REST v4 par interrogation et WebSocket. Par défaut, le bot interroge les canaux toutes les 3 secondes pour les nouveaux posts ; définissez listen_mode = "websocket" pour une diffusion d’événements quasi en temps réel via une connexion WebSocket persistante. Les posts de réponse sont toujours envoyés via POST /api/v4/posts, quel que soit le mode d’écoute.

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 mattermost définit channel à mattermost, liste les expéditeurs autorisés dans external_peers (pour mattermost, l’UUID de l’utilisateur Mattermost (et non un nom d’utilisateur) ; ["*"] accepte tout le monde), nomme éventuellement des agents pairs pour la distribution inter-agents, une liste de blocage ignore, et une output_modality (mirror, voice ou text). Consultez Peer Groups pour la référence des champs.

Où définir ce paramètre :

Pour ajouter un humain spécifique à la liste d’autorisation, copiez son ID utilisateur depuis System Console → User Management. Mattermost effectue la correspondance avec l’UUID de l’utilisateur, et non un nom d’utilisateur, et ne résout pas les noms d’utilisateur au moment de la réception du message.

Démarrage rapide

Configurez un canal Mattermost (url plus un secret bot_token, voir Authentification) via l’une des interfaces ci-dessous. Cela seul vous offre :

1. Détection automatique de chaque canal que le bot peut lire dans toutes les équipes dont il fait partie.
2. Canaux DM et DM de groupe découverts automatiquement et interrogés en même temps que les canaux d’équipe.
3. Les nouveaux MP (créés après le démarrage du bot) sont récupérés lors de la prochaine actualisation de découverte, qui a lieu toutes les 60 secondes.
4. mention_only est contourné dans les canaux de messages privés et de groupes privés (afin que les conversations en tête-à-tête ne nécessitent pas de mentionner le bot avec @).

Pour restreindre le bot, affinez avec channel_ids, team_ids ou discover_dms.

Configuration

bot_token et password sont des secrets :

channels.mattermost.<alias>.bot_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.mattermost.<alias>.bot_token    # demande une saisie masquée, stocke de manière chiffrée

Référence des champs

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

export ZEROCLAW_channels__mattermost__<alias>__approval_timeout_secs=

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

export ZEROCLAW_channels__mattermost__<alias>__bot_token=

zeroclaw config set channels.mattermost.<alias>.channel_ids <value>

export ZEROCLAW_channels__mattermost__<alias>__channel_ids=

zeroclaw config set channels.mattermost.<alias>.discover_dms <value>

export ZEROCLAW_channels__mattermost__<alias>__discover_dms=

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

export ZEROCLAW_channels__mattermost__<alias>__excluded_tools=

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

export ZEROCLAW_channels__mattermost__<alias>__interrupt_on_new_message=

zeroclaw config set channels.mattermost.<alias>.listen_mode <value>

export ZEROCLAW_channels__mattermost__<alias>__listen_mode=

zeroclaw config set channels.mattermost.<alias>.login_id <value>

export ZEROCLAW_channels__mattermost__<alias>__login_id=

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

export ZEROCLAW_channels__mattermost__<alias>__mention_only=

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

export ZEROCLAW_channels__mattermost__<alias>__password=

zeroclaw config set channels.mattermost.<alias>.proxy_url <value>

export ZEROCLAW_channels__mattermost__<alias>__proxy_url=

zeroclaw config set channels.mattermost.<alias>.purpose_as_instructions <value>

export ZEROCLAW_channels__mattermost__<alias>__purpose_as_instructions=

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

export ZEROCLAW_channels__mattermost__<alias>__reply_min_interval_secs=

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

export ZEROCLAW_channels__mattermost__<alias>__reply_queue_depth_max=

zeroclaw config set channels.mattermost.<alias>.team_ids <value>

export ZEROCLAW_channels__mattermost__<alias>__team_ids=

zeroclaw config set channels.mattermost.<alias>.thread_replies <value>

export ZEROCLAW_channels__mattermost__<alias>__thread_replies=

zeroclaw config set channels.mattermost.<alias>.url <value>

export ZEROCLAW_channels__mattermost__<alias>__url=

Découverte de canaux

Il existe deux modes de portée.

1. Découverte automatique (lorsque channel_ids est vide ou défini sur ["*"]). Au démarrage, puis toutes les 60 secondes, le bot appelle GET /api/v4/users/me/channels, filtre le résultat selon team_ids (canaux publics/privés) et discover_dms (messages directs/messages directs de groupe), puis interroge chaque canal restant. Les nouveaux messages directs créés en cours d’exécution apparaissent lors de la prochaine actualisation.
2. Explicite (lorsque channel_ids est une liste non vide d’ID autres que *). Au démarrage, le bot appelle GET /api/v4/channels/{id} pour chaque entrée afin de connaître son type (afin de savoir lesquels sont des DM pour le contournement mention_only), puis interroge exactement ces canaux indéfiniment. Aucune redécouverte périodique.

Dans les deux modes, chaque canal possède son propre curseur since : le bot suit le create_at le plus élevé qu’il a traité par canal et le transmet sous la forme since=<ms> lors de l’appel GET /api/v4/channels/{id}/posts suivant. Les curseurs ne se mélangent pas entre les canaux, de sorte qu’un canal peu actif ne supprime pas les messages d’un canal très actif.

Mode WebSocket

Définissez listen_mode = "websocket" pour passer de l’interrogation REST à une connexion WebSocket persistante (wss://<server>/api/v4/websocket). Le mode WebSocket :

• Diffuse les nouvelles publications en quasi temps réel (sans délai d’interrogation de 3 secondes).
• Réduit la charge HTTP sur le serveur Mattermost (une connexion au lieu de N requêtes toutes les 3 s).
• Renvoie les sessions ayant échoué au superviseur de canal partagé, qui se reconnecte avec un backoff exponentiel borné en utilisant les valeurs reliability.channel_initial_backoff_secs et reliability.channel_max_backoff_secs configurées.
• Nécessite Mattermost v4.0+ (l’endpoint /api/v4/websocket).

La découverte de canaux, mention_only, thread_replies, la transcription audio et l’autorisation par groupe de pairs fonctionnent de manière identique dans les deux modes.

Compromis :

• Le mode WebSocket doit maintenir une connexion TCP+TLS persistante.
• Pendant une fenêtre de reconnexion, des messages publiés dans un canal peuvent être manqués car cet écouteur ne demande pas encore la reprise/relecture de connexion Mattermost. L’interrogation rattrape le retard via les curseurs since=.
• Le mode d’interrogation est plus résistant aux interruptions réseau transitoires, au prix d’un trafic HTTP constant.

Pour revenir en arrière, définissez listen_mode = "polling" (ou supprimez le champ ; le polling est la valeur par défaut).

Approbation de l’outil via le chat (approval_timeout_secs)

Lorsqu’un outil nécessite une approbation (il figure dans always_ask, ou le profil de risque ne l’approuve pas automatiquement), l’agent publie la demande dans le canal d’où provient le message et attend. Il existe deux façons de répondre, et les options disponibles dépendent de listen_mode.

Répondez avec le token. Cela fonctionne dans tous les modes d’écoute :

APPROBATION REQUISE [a1b2c3]
Outil : shell
Arguments : command: pwd

Réponse : "a1b2c3 yes", "a1b2c3 no" ou "a1b2c3 always"

a1b2c3 yes
a1b2c3 no
a1b2c3 always

A reply that matches a pending token is consumed as a decision and never reaches the model.

Toucher une réaction. Cette option nécessite listen_mode = "websocket". Le bot place ✅ et ❌ sur son propre message d’invite ; toucher l’une d’elles répond à l’invite. Les réactions parviennent au bot sous forme d’événements WebSocket reaction_added, et l’écouteur en mode polling lit les messages sans jamais les voir ; avec listen_mode = "polling", aucun emoji n’est donc ajouté : un bouton qui ne fait silencieusement rien sur une invite de sécurité est pire que pas de bouton. Si vous voulez des approbations en un seul geste, définissez listen_mode = "websocket" (voir Mode WebSocket).

always n’a pas d’émoji, et c’est volontaire. Il accorde une entrée de liste d’autorisation limitée à la session plutôt que d’autoriser un seul appel, et un appui accidentel à côté de ✅ serait un moyen trop facile d’élargir une session. Passer à always reste donc une décision à saisir explicitement.

Mattermost ne propose pas de boutons de message interactifs ici. Ceux-ci envoient leurs données à une URL d’intégration, ce qui nécessite un point de terminaison HTTP entrant que le bot ne peut pas exposer depuis un client par interrogation (polling) ou WebSocket ; les réactions sont l’action en un clic qui fonctionne sur la connexion que le bot maintient déjà.

Qui peut répondre, et où. Le jeton est un corrélateur, et non un mot de passe : il circule en clair dans le canal, donc chaque membre peut le lire. Deux conditions doivent donc être réunies. L’utilisateur qui répond doit appartenir au groupe de pairs de l’alias, c’est-à-dire à la même autorité qui détermine les messages auxquels l’agent donne suite. Et la réponse doit arriver dans le canal où l’invite a été publiée : un même bot dessert plusieurs canaux, donc un jeton transmis dans un autre salon n’est pas une réponse valide, même si l’utilisateur est autorisé. La liaison s’effectue par canal et non par fil, si bien qu’une réponse dans le canal plutôt que dans le fil de l’invite est acceptée. Une réponse ou une action qui échoue à l’une de ces vérifications est consignée au niveau WARN et ignorée ; l’invite reste ouverte afin qu’un opérateur autorisé puisse toujours y répondre au bon endroit.

Tout le monde dans le canal peut lire les arguments de l’outil. L’invite comprend le nom de l’outil et un résumé de ses arguments. Acheminez les demandes d’approbation vers un canal dont vous acceptez que les membres puissent voir ces informations.

approval_timeout_secs borne l’attente. La valeur par défaut est de 300 secondes, et 0 refuse immédiatement au lieu de désactiver l’approbation : un zéro permet donc de refuser tous les outils soumis à approbation, et non d’attendre indéfiniment. En cas de dépassement du délai, la demande est refusée et le jeton est supprimé, si bien qu’une réponse ou un appui tardif ne peut plus approuver un appel que personne n’attend. Un dépassement de délai ou un système de demande injoignable est enregistré comme un refus décidé par le runtime de sa propre initiative, et non comme un refus de la part d’un humain.

Les décisions sont définitives : retirer une réaction ne rétracte pas une réponse, et la première réponse valide met fin à la question pour les deux chemins.

S’il est impossible au bot de placer l’emoji, ce qui est le plus souvent un problème de permissions, il journalise failed to seed Mattermost approval reaction au niveau WARN et l’invite fonctionne toujours par réponse.

Note: the instruction to preserve “purpose_as_instructions” exactly applies, and the English phrase “purpose as instructions” is translated while the identifier and backticked code stay unchanged.

Désactivé par défaut. Lorsqu’il est activé, la description du canal (channel purpose) de chaque salon Mattermost est injectée dans le prompt système de l’agent en tant que contexte fourni par le canal, afin qu’un salon puisse spécialiser l’agent sans qu’une entrée de configuration soit nécessaire pour chaque salon :

[channels.mattermost.default]
purpose_as_instructions = true

Définissez l’objectif d’un canal pour décrire à quoi sert cette salle, par exemple « Maintenance de paquets Arch Linux pour les dépôts AUR ». L’agent le considère comme une référence faisant autorité concernant l’orientation de la salle, son ton et les compétences à utiliser.

Il ne fait pas autorité sur les règles de l’agent. Le texte injecté est étiqueté comme fourni par le canal et se voit explicitement refuser tout pouvoir d’accorder des capacités, d’assouplir des restrictions ou de prévaloir sur les règles de fonctionnement ; en cas de conflit, ce sont les règles qui s’appliquent. Il ne peut ni activer un outil, ni élargir un groupe de pairs, ni modifier un niveau d’autonomie.

Ce que cette option accorde, et à qui

Activer cette option est une décision de confiance, et il vaut la peine d’être franc sur sa nature plutôt que de laisser celle-ci être déduite de l’avertissement ci-dessus.

Le but est régi par les permissions manage_public_channel_properties / manage_private_channel_properties de Mattermost, qui, dans les schémas par défaut, sont accordées à chaque membre du canal. Il s’agit généralement d’un groupe plus large que les personnes qui contrôlent cette configuration, et il ne recoupe pas nécessairement les peer_groups de l’alias : un membre qui n’est pas un pair ZeroClaw autorisé, et qui ne peut donc pas obtenir de l’agent une réponse directe, peut tout de même modifier le but de la salle.

Le texte atteint le prompt système. Le cadrage qui l’entoure indique au modèle que le texte est fourni par le canal, décrit la pièce plutôt que de commander l’agent, et ne remplace jamais ses règles. Mais le cadrage est un fort a priori, non une frontière. Un texte qui se présente comme une instruction peut influencer ce que l’agent fait dans cette pièce, et aucun échappement n’y change rien ; c’est du langage naturel, et le modèle le lit comme tel.

Donc, la décision que prend cette fonctionnalité, explicitement : activer purpose_as_instructions pour un alias donne à toute personne pouvant modifier l’objet des salons concernés la capacité d’orienter l’agent à cet endroit, dans les limites des permissions que l’agent possède déjà. Ne l’activez que lorsque cet ensemble de personnes est digne de confiance pour les capacités configurées de l’agent. Dans le cas contraire, laissez-la désactivée (valeur par défaut), ou restreignez manage_*_channel_properties dans votre schéma de permissions aux personnes qui devraient en disposer.

Ce que l’objectif ne peut toujours pas faire, c’est élargir ces capacités. Il ne peut pas activer un outil, ajouter un pair, modifier un niveau d’autonomie, ni approuver son propre appel d’outil : ces décisions relèvent de la configuration et du chemin d’approbation, et aucun des deux ne lit le texte de l’invite.

Structurellement, le texte est contenu. Avant l’injection, il est aplati en une seule ligne, les chevrons et les caractères de contrôle étant supprimés, de sorte qu’il ne peut ni fermer sa propre section, ni en ouvrir une autre, ni forger un titre Markdown qui semble appartenir à une autre partie de l’invite de l’opérateur. Il est également limité à 500 caractères, au-dessus de la limite de 250 caractères imposée par Mattermost à ce champ (l’en-tête du canal en autorise 1024), de sorte qu’aucun usage légitime n’est tronqué, tandis qu’un serveur compromis ne peut pas coller une invite entière.

Une modification du objet prend effet au message suivant, avec un délai qui dépend de listen_mode :

Vider l’objectif d’un canal arrête l’injection ; il n’est pas conservé à partir d’une valeur précédente. Les salons sans objectif n’apportent rien.

Pour revenir en arrière, définissez purpose_as_instructions = false (ou supprimez le champ ; la désactivation est la valeur par défaut). Aucun état de canal n’a besoin d’être nettoyé, car rien n’est mis en cache pour un alias qui n’a pas activé cette option.

Messages directs

Mattermost classe les canaux par type :

G et D sont traités de manière identique par ZeroClaw : aucun ne comporte de team_id, tous deux sont contrôlés par discover_dms, et tous deux contournent implicitement mention_only (une conversation privée n’a aucun bruit ambiant à filtrer).

L’autorisation des expéditeurs de DM passe toujours par le résolveur de groupe de pairs du canal, comme pour tout autre canal. discover_dms est un paramètre de réglage, pas une frontière de sécurité ; ce sont les groupes de pairs qui décident qui est autorisé à s’adresser à l’agent.

Exécution de threads

1. La publication entrante se trouve dans un fil de discussion existant (root_id est défini) → la réponse arrive toujours dans ce fil, quel que soit thread_replies.
2. Le post entrant est de premier niveau et thread_replies = true (par défaut) → la réponse ouvre un fil de discussion ancré sur le post entrant.
3. L’envoi entrant est de premier niveau et thread_replies = false → la réponse est publiée à la racine du canal.

Gestion du contexte

Lorsqu’une conversation Mattermost se déroule dans un fil de discussion, ce fil constitue sa propre conversation. ZeroClaw dérive une clé de session distincte par fil, de sorte que chaque fil possède une fenêtre de contexte et un historique indépendants : les messages d’un fil ne débordent jamais dans un autre, et l’agent ne voit pas les échanges antérieurs d’un fil voisin. Pour Mattermost, ce comportement est contrôlé par thread_replies : lorsqu’il est activé, les messages de premier niveau ouvrent un fil et chaque fil constitue une conversation distincte ; lorsqu’il est désactivé, les réponses sont publiées à la racine du canal et l’historique est indexé par expéditeur et par 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.mattermost.<alias>.thread_replies true     # réponses en fil de discussion activées
zeroclaw config set channels.mattermost.<alias>.thread_replies false    # réponses à la racine du canal

Authentification

Deux chemins :

1. Jeton de bot (recommandé). Créez-le dans System Console → Integrations → Bot Accounts, copiez le jeton d’accès et stockez-le dans bot_token. Les jetons restent valides après les rotations de mot de passe et sont plus faciles à révoquer.
2. Flux de connexion. Définissez login_id (email ou nom d’utilisateur) et password. Le bot appelle POST /api/v4/users/login au démarrage et met en cache le jeton de session renvoyé en mémoire. Aucune persistance sur disque.

bot_token l’emporte lorsque les deux sont définis.

Messages vocaux

Lorsque [transcription] est configuré et qu’un post entrant contient une pièce jointe audio (type MIME audio/* ou extension ogg/mp3/m4a/wav/opus/flac) sans corps de texte, le fichier audio est téléchargé via GET /api/v4/files/{file_id} et acheminé vers le fournisseur de transcription configuré. La transcription est préfixée [Voice] et devient le contenu du message. Les pièces jointes dépassant 25 Mo ou la durée limite définie par transcription.max_duration_secs sont ignorées avec un avertissement WARN.

Configuration

1. Dans Mattermost : Console système → Intégrations → Comptes de bot → Ajouter un compte de bot. Définissez un nom d’utilisateur (par ex. zeroclaw), activez les portées souhaitées.
2. Copiez le jeton d’accès. Stockez-le dans votre backend de secrets ZeroClaw.
3. Invitez le bot dans les équipes où vous souhaitez qu’il soit actif. Pour la découverte automatique des MP, aucune invitation supplémentaire n’est nécessaire : tout utilisateur peut envoyer un MP au bot.
4. Créez le canal mattermost.<alias> en référençant le jeton via la passerelle, zerocode, ou zeroclaw config set.
5. Liez le canal à un agent dans [agents.<alias>] via channels = ["mattermost.<alias>"].

Notes opérationnelles

1. La fréquence d’interrogation est de 3 secondes par canal. N canaux découverts = N appels HTTP toutes les 3 secondes vers le serveur Mattermost. Les configurations auto-hébergées par défaut gèrent cela facilement ; si vous êtes sur un tenant cloud partagé avec des limites de débit strictes, envisagez de restreindre la portée avec channel_ids ou team_ids.
2. L’identité du bot est récupérée une fois via GET /api/v4/users/me et mise en cache pour toute la durée de vie du processus. Les changements de nom d’utilisateur nécessitent un redémarrage.
3. Le jeton de session du flux de connexion par mot de passe est conservé uniquement en mémoire. Un redémarrage relance la connexion.

Voir aussi

• Vue d’ensemble des canaux
• Groupes de pairs
• Référence : schéma de configuration