Configurer Hermes Agent sur Slack (Socket Mode)

Pourquoi faire vivre Hermes Agent dans Slack

Si votre équipe vit déjà dans Slack, c'est là que votre agent IA doit vivre aussi. Les onglets de navigateur et les tableaux de bord isolés perdent le contexte que les canaux, les threads et les messages directs offrent gratuitement : qui pose la question, de quoi on parlait il y a cinq minutes, et où la réponse devrait atterrir.

Hermes Agent propose une intégration Slack de première classe via Socket Mode, donc le runtime peut tourner sur votre portable, sur un VPS à 5 dollars ou derrière un pare-feu d'entreprise et continuer à échanger des messages en temps réel. Pas besoin d'exposer un webhook public, ni de monter un proxy inverse, ni d'ouvrir un port entrant. L'agent se connecte vers Slack, garde un WebSocket ouvert, et fait passer chaque message et chaque réponse par ce même canal.

Ce guide déroule la configuration complète de bout en bout : créer l'app Slack à partir du manifeste fourni, générer les deux tokens, brancher le canal home et la liste d'autorisés, démarrer le gateway, et les pièges qui font trébucher le premier déploiement.

Ce qu'il vous faut avant de commencer

Un déploiement Slack propre demande cinq éléments en place :

• Un workspace où vous avez la permission d'installer des apps. La plupart des workspaces exigent qu'un admin valide l'installation par défaut - vérifiez Settings & administration → Workspace settings → Permissions si vous n'êtes pas admin.
• Une installation de Hermes Agent fonctionnelle. Le guide Hermes Agent sur Docker couvre la voie la plus propre pour en monter une ; sous Windows, le setup WSL2 est l'équivalent.
• Une clé d'API de provider de modèle. Anthropic, OpenAI, OpenRouter et tout endpoint compatible OpenAI conviennent. Le runtime s'en sert pour réellement répondre aux messages.
• Votre Slack user ID numérique pour la liste d'autorisés (voir plus bas).
• Environ 15 minutes pour la première installation. Les redéploiements suivants prennent moins d'une minute.

Étape 1 - Générer le manifeste de l'app Slack

Les apps Slack se définissent par un manifeste YAML qui déclare permissions, abonnements aux événements, slash commands et Socket Mode en une seule fois. Hermes embarque un manifeste pensé pour son handler Slack natif, vous n'avez donc pas à assembler la liste des scopes à la main :

hermes slack manifest --write ./hermes-slack-manifest.yaml

Ouvrez https://api.slack.com/apps, cliquez sur Create New App, choisissez From an app manifest, sélectionnez votre workspace et collez le contenu de hermes-slack-manifest.yaml. Slack montre exactement ce qui va être créé. Confirmez.

Le manifeste active Socket Mode, déclare chaque événement auquel Hermes s'abonne (app_mention, message.im, message.channels, message.groups, message.mpim), enregistre les slash commands intégrés et demande les scopes de bot que le runtime utilise vraiment :

• app_mentions:read - écouter quand quelqu'un mentionne le bot dans un canal.
• chat:write - envoyer des réponses et ouvrir des threads.
• im:history, im:read, im:write - conversations en messages directs.
• channels:history, groups:history, mpim:history - lire le contexte des canaux publics, privés et des groupes où le bot est invité.
• users:read - résoudre les IDs d'utilisateur en noms lisibles pour l'UI de la liste d'autorisés et pour les logs d'audit.
• commands - enregistrer la surface du slash command /hermes.

Modifier le manifeste après installation ne pose pas de problème. Ajouter des scopes après l'installation est l'opération qui produit le plus de pannes silencieuses - voir la section troubleshooting plus bas.

Étape 2 - Générer le bot token et l'app-level token

Slack émet deux tokens distincts pour une app en Socket Mode, et Hermes a besoin des deux :

Bot token (xoxb-…)

Dans les réglages de l'app, allez dans OAuth & Permissions → Install to Workspace. Approuvez les scopes du manifeste. Slack émet un token xoxb-…. Copiez-le.

App-level token (xapp-…)

Allez dans Basic Information → App-Level Tokens → Generate Token and Scopes. Donnez-lui un nom (par exemple hermes-socket), ajoutez le scope connections:write et cliquez sur Generate. Slack émet un token xapp-…. Copiez-le.

Les deux tokens jouent des rôles différents. Le bot token authentifie les appels à l'API Slack (envoyer un message, lire l'historique d'un canal). L'app token authentifie le WebSocket Socket Mode lui-même - sans lui, le runtime démarre mais ne se connecte jamais à Slack et le bot reste muet pour toujours.

Étape 3 - Trouvez votre Slack user ID numérique

Hermes Agent ne répondra qu'aux IDs d'utilisateur présents dans SLACK_ALLOWED_USERS. C'est le contrôle de sécurité le plus important de toute la configuration et il attend des IDs numériques, pas des @handles ni des noms affichés.

Dans Slack, cliquez sur votre avatar → Profile → menu trois points (⋮) → Copy member ID. L'ID ressemble à U01ABCD2EFG. Répétez pour chaque collègue à autoriser.

Sauter la liste d'autorisés revient à publier votre clé d'API provider à toute personne du workspace. Si une instance Hermes est joignable depuis un workspace Slack ouvert et que la liste est vide, chaque message dans chaque canal où le bot est invité va consommer vos tokens.

Étape 4 - Configurez le runtime Hermes

Ouvrez ~/.hermes/.env (ou le .env que lit votre conteneur) et ajoutez :

SLACK_BOT_TOKEN=xoxb-...votre-bot-token...
SLACK_APP_TOKEN=xapp-...votre-app-token...
SLACK_ALLOWED_USERS=U01ABCD2EFG,U02HIJK3LMN
SLACK_HOME_CHANNEL=C04XYZ123AB

Une note sur chaque variable :

• SLACK_BOT_TOKEN - le token xoxb-… de l'étape 2.
• SLACK_APP_TOKEN - le token xapp-…. L'oublier est la panne la plus fréquente et elle ne produit aucun message d'erreur - le gateway n'ouvre tout simplement jamais le WebSocket.
• SLACK_ALLOWED_USERS - liste d'IDs numériques séparés par une virgule. Le bot ignore tous les autres, y compris les admins et les comptes bot.
• SLACK_HOME_CHANNEL (optionnel) - l'ID du canal pour les messages proactifs, les résumés programmés et les notifications déclenchées par les skills. Clic droit sur le canal dans Slack → View channel details → copiez l'ID en bas. Si vide, la sortie proactive part en DM du bot avec le premier utilisateur autorisé.

chmod 600 ~/.hermes/.env après la sauvegarde. Les deux tokens donnent un accès en écriture à votre workspace ; traitez-les comme des clés SSH.

Étape 5 - Démarrez le gateway

Redémarrez le gateway pour qu'il prenne en compte le nouvel environnement :

hermes gateway restart

Ou, avec Docker Compose :

docker compose restart gateway

Suivez les logs et guettez le handshake avec Slack :

hermes gateway logs --follow

Vous cherchez deux lignes, dans cet ordre :

slack: connecting to Socket Mode
slack: connected as @votre-bot-name (workspace: votre-workspace)

Si vous ne voyez que la première et plus rien, le token xapp-… est faux, manquant ou ne porte pas le scope connections:write. Si vous n'en voyez aucune, le gateway ne lit pas le nouveau .env - confirmez le chemin du fichier que le runtime utilise.

Étape 6 - Invitez le bot et envoyez le premier message

Dans n'importe quel canal où vous voulez que le bot participe :

/invite @votre-bot-name

Le bot ne voit que les messages des canaux où il a été invité. C'est une restriction côté Slack, pas côté Hermes - même avec channels:history accordé, il lit zéro historique tant que vous ne l'invitez pas.

Envoyez un DM au bot, ou mentionnez-le (@) dans le canal. Hermes répond dans la même conversation, avec sa mémoire persistante et ses skills intactes. À partir d'ici, toutes les capacités de Hermes - mémoire persistante, tâches programmées, skills personnalisées - fonctionnent exactement comme sur la surface Telegram.

Les pannes qui mordent en premier

Cinq erreurs expliquent presque chaque fil de support du genre "l'intégration Slack est cassée" :

Oublier le token xapp-…. Socket Mode ne se connecte pas du tout sans lui, et le tableau de bord Slack ne vous prévient pas. Le correctif tient en une ligne dans .env plus un redémarrage.

Ajouter des scopes après installation sans réinstaller. Les nouveaux scopes apparaissent sur la page OAuth mais ne sont réellement accordés au bot qu'après un clic sur Reinstall to Workspace. Le bot conserve l'ancien jeu de scopes en silence. Si les logs du runtime affichent des erreurs missing_scope, c'est cela.

Le bot n'est pas invité dans le canal. Un bot avec channels:history lit toujours zéro historique tant qu'il n'est pas invité. Il répondra aux DMs immédiatement mais restera muet en canal jusqu'à ce que vous lanciez /invite @votre-bot-name.

SLACK_ALLOWED_USERS vide. Le comportement par défaut est d'ignorer tout le monde. C'est un défaut sécurisé volontaire, mais cela donne l'impression d'un bot cassé à qui le teste pour la première fois sans penser à ajouter son propre ID.

Deux processus de gateway sur le même volume de données. Si vous lancez un gateway en mode Slack et un autre en mode Telegram contre le même répertoire /data, l'ordre des messages et les écritures de mémoire se corrompent l'un l'autre en quelques minutes. Pour les deux surfaces, lancez un seul gateway avec les blocs SLACK_* et TELEGRAM_* dans le .env - le runtime multiplexe les deux nativement.

Si le problème a l'air Slack mais que les symptômes sont plus généraux, le guide de troubleshooting Telegram couvre les soucis de gateway et de provider plus en profondeur - la plupart sont indépendants de la surface.

Slack et Telegram, côte à côte

Les deux surfaces ne sont pas exclusives. Le même runtime Hermes peut servir les deux en même temps - utile quand le même agent gère un chat personnel sur Telegram et un canal Slack d'équipe depuis la même mémoire.

Sautez la plomberie Slack

Les étapes Slack en elles-mêmes sont simples, mais vous restez propriétaire de l'hôte : sauvegardes, TLS pour le dashboard, rotation des logs et cadence des mises à jour. Pour une installation personnelle, c'est viable. Pour une équipe qui veut le bot opérationnel en quelques minutes et aucune charge opérationnelle ensuite, Hermify provisionne un runtime Hermes managé, chiffre vos tokens Slack au repos, expose la liste d'autorisés dans une UI plutôt que dans un .env et garde la connexion Socket Mode en bonne santé sur un serveur persistant.

Vous apportez le workspace Slack et une clé d'API de provider ; la plateforme s'occupe de tout le reste. Si vous évaluez ce compromis, la comparaison self-hosting vs managé détaille les chiffres de coût et de maintenance.

Sources

• Guide utilisateur Slack de Hermes Agent
• Setup du gateway Hermes Agent pour Telegram et Slack (EvoMap)
• Comment connecter Slack à Hermes Agent (hermes-agent.ai)
• Pas à pas : connecter Hermes Agent à Slack via Socket Mode (gist)
• Documentation Socket Mode de Slack
• Référence des types de token Slack