Mattermost Hermes Agent — Chat auto-hébergé

Si votre équipe utilise Mattermost, vous connaissez déjà l’attrait : l’interface et les sensations ressemblent à Slack, mais le serveur — et les données — restent sur votre propre infrastructure. Hermes Agent s’y connecte en tant que bot, via l’API REST de Mattermost (v4) et un WebSocket pour les événements en temps réel, afin que votre assistant puisse répondre en messages privés et dans les canaux d’équipe sans que rien ne quitte votre réseau.

Aucune bibliothèque supplémentaire à installer : l’adaptateur utilise aiohttp, déjà fourni avec Hermes. Il fonctionne avec Mattermost Team Edition (gratuite) et Enterprise Edition.

Comment Hermes se comporte dans Mattermost

Où vous lui parlez	Ce qui se passe
Messages privés	Hermes répond à chaque message — aucun `@mention` nécessaire. Chaque message privé a sa propre session.
Canaux	Hermes répond quand vous le `@mentionnez`. Sans mention, il ignore le message.
Fils	Avec `MATTERMOST_REPLY_MODE=thread`, les réponses s’imbriquent sous votre message et restent isolées du canal parent.
Canaux partagés	L’historique de session est isolé par utilisateur par défaut, donc deux personnes dans un même canal ne partagent pas la même conversation.

Ce dernier comportement est contrôlé par group_sessions_per_user dans config.yaml :

group_sessions_per_user: true   # each person keeps their own context

Mettez-le à false uniquement si vous voulez délibérément une conversation partagée pour tout le canal. Une session partagée signifie que tout le monde partage la croissance du contexte et les coûts en tokens, et qu’une tâche longue et riche en outils d’une personne peut alourdir ou interrompre l’exécution d’une autre.

Étape 1 : Activer les comptes bot (côté administrateur)

Les comptes bot doivent être activés sur le serveur avant de pouvoir en créer un :

Connectez-vous à Mattermost en tant qu’administrateur système.
Allez dans Console système → Intégrations → Comptes bot.
Mettez Activer la création de comptes bot sur true, puis cliquez sur Enregistrer.

Pas d’accès administrateur ? Demandez à votre administrateur Mattermost d’activer les comptes bot et d’en créer un pour vous.

Étape 2 : Créer le compte bot

Cliquez sur le menu ☰ (en haut à gauche) → Intégrations → Comptes bot → Ajouter un compte bot.
Remplissez les détails : Nom d’utilisateur comme hermes, Nom affiché comme Hermes Agent, et un Rôle — Member suffit.
Cliquez sur Créer un compte bot, puis copiez immédiatement le token — il n’est affiché qu’une seule fois. Si vous le perdez, vous devrez le régénérer depuis les paramètres du compte bot.

⚠️ Ne partagez jamais le token et ne le committez pas dans Git. Quiconque le détient a le contrôle total du bot.

Vous préférez que l’agent publie en tant que votre propre utilisateur plutôt qu’un bot séparé ? Créez un token d’accès personnel sous Profil → Sécurité → Tokens d’accès personnels → Créer un token.

Étape 3 : Inviter le bot dans les canaux

Le bot ne répond que dans les canaux auxquels il appartient :

Ouvrez le canal → cliquez sur le nom du canal → Ajouter des membres.
Recherchez le nom d’utilisateur du bot (par exemple hermes) et ajoutez-le.

Pour les messages privés, ouvrez simplement une conversation directe avec le bot — aucune invitation nécessaire.

Étape 4 : Trouver votre ID utilisateur Mattermost

Hermes utilise votre ID utilisateur — pas votre nom d’utilisateur — pour décider qui est autorisé à parler au bot :

Cliquez sur votre avatar (coin supérieur gauche) → Profil.
La boîte de dialogue affiche votre ID utilisateur : une chaîne alphanumérique de 26 caractères comme 3uo8dkh1p7g1mfk49ear5fzs5c. Cliquez dessus pour la copier.

Vous pouvez aussi le lire depuis l’API :

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-mattermost-server/api/v4/users/me | jq .id

Votre ID utilisateur n’est pas le @username que vous voyez dans les messages. Coller le nom d’utilisateur est la raison la plus courante pour laquelle un bot reste silencieux.

Étape 5 : Configurer Hermes

Lancez la configuration guidée et choisissez Mattermost quand demandé — elle vous demande l’URL du serveur, le token du bot et votre ID utilisateur :

hermes gateway setup

Ou configurez-le manuellement dans ~/.hermes/.env :

# Required
MATTERMOST_URL=https://mm.example.com
MATTERMOST_TOKEN=your-bot-token
MATTERMOST_ALLOWED_USERS=3uo8dkh1p7g1mfk49ear5fzs5c

# Multiple allowed users (comma-separated)
# MATTERMOST_ALLOWED_USERS=3uo8dkh1p7g1mfk49ear5fzs5c,8fk2jd9s0a7bncm1xqw4tp6r3e

# Optional: reply in a thread instead of flat messages (default: off)
# MATTERMOST_REPLY_MODE=thread

# Optional: respond without an @mention (default: true = mention required)
# MATTERMOST_REQUIRE_MENTION=false

# Optional: channels where no @mention is needed (comma-separated channel IDs)
# MATTERMOST_FREE_RESPONSE_CHANNELS=channel_id_1,channel_id_2

Puis démarrez la passerelle :

hermes gateway

Le bot se connecte à votre serveur Mattermost en quelques secondes. Envoyez-lui un message privé, ou @mentionnez-le dans un canal où il a été ajouté, pour tester.

Étape 6 : Options de comportement facultatives

Paramètre	Ce qu’il fait
`MATTERMOST_REPLY_MODE`	`off` (par défaut) publie des messages à plat ; `thread` imbrique les réponses sous votre message et garde les canaux actifs bien rangés.
`MATTERMOST_REQUIRE_MENTION`	`true` par défaut. Mettez à `false` pour répondre à tous les messages du canal (les messages privés fonctionnent toujours).
`MATTERMOST_FREE_RESPONSE_CHANNELS`	ID de canaux qui ignorent l’exigence de mention même quand les mentions sont requises.
`MATTERMOST_HOME_CHANNEL`	Où vont les messages proactifs — sortie cron, rappels, notifications. Ou tapez `/sethome` dans un canal.
`mattermost.allowed_channels`	Restreint le bot à une liste d’ID de canaux ; les messages venant d’ailleurs sont ignorés. Les messages privés sont exemptés.
`mattermost.channel_prompts`	Injecte un prompt système éphémère par canal — appliqué à chaque tour, jamais enregistré dans l’historique de conversation.

Quand le bot est @mentionné, la mention est retirée du message avant traitement, donc @hermes summarize this thread arrive comme une instruction propre.

Dépannage

Symptôme	Cause probable	Correctif
Le bot vous ignore dans les canaux	Il n’est pas dans le canal, ou votre ID utilisateur n’est pas dans `MATTERMOST_ALLOWED_USERS`	Ajoutez le bot au canal, vérifiez l’ID utilisateur de 26 caractères, redémarrez la passerelle
Le bot ne peut pas publier	Token invalide, ou le bot manque de permissions dans ce canal	Vérifiez `MATTERMOST_TOKEN`, confirmez que le compte est actif et membre du canal
Déconnexions constantes	Coupures WebSocket, redémarrages du serveur, ou problèmes de proxy/pare-feu	L’adaptateur se reconnecte avec un backoff exponentiel (2s → 60s) ; pour nginx, assurez-vous que les en-têtes d’upgrade WebSocket sont configurés
Rien ne se passe du tout	Passerelle non démarrée, ou URL/token incorrect	Vérifiez la sortie de `hermes gateway`, et que `MATTERMOST_URL` inclut `https://` sans slash final

Testez un token directement avec :

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-server/api/v4/users/me

Sécuriser le bot

Définissez toujours MATTERMOST_ALLOWED_USERS. Sans cela, la passerelle refuse tous les utilisateurs par défaut par mesure de sécurité — et les utilisateurs autorisés obtiennent un accès complet aux capacités de l’agent, y compris l’utilisation d’outils et l’accès système, donc gardez la liste restreinte. Pour un aperçu plus large du durcissement d’un déploiement, consultez les recommandations de sécurité officielles.

Et ensuite ?

Une fois la passerelle en place, Mattermost se comporte comme n’importe quel autre canal Hermes : commandes slash, envois de fichiers, notes vocales, sortie cron livrée à votre canal principal — le tout sur une infrastructure que vous contrôlez. Si vous préférez l’option hébergée, l’intégration Slack couvre la voie Socket Mode ; si vous exécutez des passerelles sur plusieurs machines, Hermes Relay les connecte.