Comment configurer Hermes Slack sur ZimaOS et corriger les erreurs de passerelle

Un agent Hermes peut se connecter à Slack sans exposer de point de terminaison webhook public, car son intégration Slack actuelle utilise le mode Socket. Le compte rendu de la communauté à l’origine de cette page a mené à bien la majeure partie de cette configuration : l’utilisateur a créé une nouvelle application Slack, obtenu un xoxb- un jeton de bot et un xapp- un jeton au niveau de l’application, exécuté hermes gateway setup dans le conteneur Hermes de ZimaOS, et invité le bot dans un canal Slack.

L’échec s’est produit lorsque Hermes a tenté de redémarrer sa passerelle. La CLI a renvoyé PermissionError: [Errno 13] Permission denied: '/opt/data/gateway.lock', et bien que l’application soit apparue dans Slack, une @Hermes la mention n’a produit aucune réponse. La documentation actuelle de ZimaSpace identifie désormais explicitement /opt/data les erreurs d’autorisation comme un problème de propriété Hermes pouvant survenir après des opérations sur la passerelle exécutées précédemment en tant que root. La documentation Slack actuelle de Hermes ajoute également plusieurs exigences de configuration qu’il est plus sûr de vérifier que de deviner manuellement les autorisations.

Ce qui s’est passé dans le compte rendu Slack de ZimaOS Hermes

La publication de la communauté de mai 2026 utilisait une installation propre de ZimaOS Hermes et un nouvel espace de travail Slack. L’utilisateur a créé une application Slack avec le mode Socket activé, copié les deux types de jetons requis et configuré Slack via l’assistant de passerelle Hermes.

La séquence clé était la suivante :

1. Créez une application Slack et activez le mode Socket.
2. Obtenez un jeton OAuth utilisateur du bot commençant par xoxb-.
3. Obtenez un jeton au niveau de l’application commençant par xapp-.
4. Exécutez hermes gateway setup dans le conteneur Hermes.
5. Sélectionnez Slack et saisissez les deux jetons.
6. Acceptez l’invite pour redémarrer la passerelle.

Le redémarrage a échoué avec :

PermissionError: [Errno 13] Permission denied: '/opt/data/gateway.lock'

L’utilisateur a ensuite redémarré la passerelle depuis l’interface web de Hermes, invité @Hermes dans un canal Slack, et Slack a confirmé que l’application avait été ajoutée. Cependant, une mention dans un canal n’a reçu aucune réponse. Il fallait donc potentiellement résoudre deux niveaux de problème : le processus de passerelle côté ZimaOS et la configuration des événements côté Slack.

Utiliser le manifeste Slack actuel de Hermes plutôt que de recréer manuellement toutes les autorisations

La documentation actuelle de Hermes recommande de générer un manifeste d’application Slack. Cette méthode est plus sûre que de recréer manuellement de mémoire chaque autorisation OAuth, commande slash, abonnement aux événements et paramètre du mode Socket.

Dans un environnement Hermes actuel, générez le manifeste avec :

hermes slack manifest --agent-view --write

Le fichier généré est écrit dans :

~/.hermes/slack-manifest.json

Créez ensuite une nouvelle application Slack à partir de ce manifeste dans l’interface d’administration des applications de Slack. La documentation actuelle de Hermes explique que le manifeste déclare ensemble les commandes intégrées, les portées requises, les abonnements aux événements et la configuration du mode Socket.

Pour consulter la procédure actuelle en amont, reportez-vous au guide de configuration de Slack pour Hermes Agent.

Les deux jetons Slack nécessaires à Hermes

Hermes utilise deux identifiants Slack différents, qui ne sont pas interchangeables :

• Jeton du bot : commence par xoxb- et devient SLACK_BOT_TOKEN.
• Jeton au niveau de l’application : commence par xapp-, doit prendre en charge le mode Socket Mode et devient SLACK_APP_TOKEN.

Un fichier d’environnement Hermes actuel peut contenir :

SLACK_BOT_TOKEN=xoxb-your-bot-token
SLACK_APP_TOKEN=xapp-your-app-token
SLACK_ALLOWED_USERS=U01ABC2DEF3

SLACK_ALLOWED_USERS utilise les identifiants de membre Slack, et non les noms affichés. Si les jetons sont corrects, mais que l’utilisateur à l’origine de la demande n’est pas autorisé, Hermes peut malgré tout sembler connecté tout en refusant de traiter les messages de cet utilisateur.

Ne publiez jamais de xoxb- ou xapp- valeurs dans une publication communautaire, une capture d’écran, un dépôt Git ou un journal d’assistance. Révoquez et régénérez un jeton s’il a été exposé.

Les mentions dans les canaux nécessitent les bons événements Slack

La visibilité d’un bot dans un canal ne prouve pas que Slack transmet les événements de messages à Hermes. La documentation actuelle de Hermes indique que les abonnements aux événements sont une cause fréquente d’échec.

Pour une application Slack configurée manuellement, vérifiez les événements requis par la version actuelle de Hermes. La documentation actuelle mentionne notamment les événements suivants :

• app_mention pour les messages directs @Hermes mentions.
• message.channels pour les messages dans les canaux publics où le bot est membre.
• message.groups lorsqu’une prise en charge des canaux privés est nécessaire.
• message.im pour les messages directs.

Si vous modifiez les portées ou les abonnements aux événements après avoir installé l’application Slack, réinstallez l’application dans l’espace de travail lorsque Slack vous le demande. Sinon, les paramètres affichés et les autorisations réellement accordées au bot installé peuvent différer.

Invitez Hermes dans le canal avant de tester

Hermes ne rejoint pas automatiquement tous les canaux Slack. Invitez-le explicitement :

/invite @Hermes

Testez ensuite une simple mention envoyée par un utilisateur Slack dont l’identifiant de membre figure dans la liste d’autorisation de Hermes. Si les messages directs fonctionnent, mais pas les mentions dans les canaux publics, concentrez-vous sur app_mention, message.channels, l’adhésion au canal et les autorisations de l’application installée avant de modifier la configuration réseau de ZimaOS.

Pourquoi /opt/data/gateway.lock peut renvoyer « Permission denied »

Le guide de l’agent Hermes de ZimaSpace documente désormais un problème d’autorisation concernant /opt/data. Il indique que celui-ci est généralement dû à l’exécution antérieure de Hermes Gateway en tant que root, qui a laissé des fichiers appartenant à root dans $HERMES_HOME.

Le workflow documenté par ZimaSpace pour le conteneur consiste à y accéder en tant que hermes utilisateur :

docker exec -it -u hermes hermes bash

Activez ensuite l’environnement virtuel Hermes :

source /opt/hermes/.venv/bin/activate

La configuration de la messagerie peut ensuite être ouverte avec :

hermes gateway setup

Si la passerelle échoue immédiatement avec /opt/data/gateway.lock et n’exécutez pas à répétition toute la passerelle en tant que root. Confirmez d’abord l’identité et la propriété concernées :

id
ls -ld /opt/data
ls -l /opt/data/gateway.lock 2>/dev/null

Le guide ZimaSpace actuel recommande de vérifier les journaux Hermes dans le tableau de bord ZimaOS et d’utiliser temporairement un shell root uniquement lorsque la propriété des fichiers doit être réparée. N’appliquez pas aveuglément une modification récursive de la propriété à /opt/data sauf si vous avez vérifié quels fichiers appartiennent à Hermes et quel utilisateur/groupe le paquet ZimaOS installé attend.

Redémarrez la passerelle uniquement après qu’Hermes peut écrire ses fichiers d’exécution.

Dans le rapport de la communauté, cliquer sur Redémarrer la passerelle dans l’interface web ne suffisait pas à prouver que la passerelle était opérationnelle. Si le processus sous-jacent ne peut pas créer ou mettre à jour son fichier de verrouillage, l’action de l’interface peut tout de même laisser l’intégration Slack indisponible.

Après avoir corrigé le problème réel de propriété, entrez dans le conteneur en tant que hermes utilisateur, activez l’environnement, puis exécutez ou redémarrez la passerelle à l’aide des commandes prises en charge par la version de Hermes installée. Surveillez les journaux Hermes de ZimaOS tout en envoyant un message Slack de test.

Pour résoudre efficacement les problèmes, il est utile de distinguer les cas suivants :

• Aucun démarrage de la passerelle : examinez les autorisations de /opt/data et les journaux Hermes.
• La passerelle fonctionne, mais aucune connexion Slack : vérifiez le jeton xapp- et le mode Socket.
• La connexion Slack existe, mais les mentions dans le canal restent silencieuses : vérifiez les événements de l’application, l’appartenance au canal, l’état de la réinstallation et SLACK_ALLOWED_USERS.
• Les messages directs fonctionnent, mais pas le canal : concentrez-vous sur les événements et les autorisations du canal plutôt que sur le fournisseur du modèle.

Utilisez le tableau de bord web Hermes pour consulter l’état, et non comme unique contrôle de santé.

Le guide ZimaSpace expose le tableau de bord web Hermes à l’adresse suivante :

http://ZIMAOS_LAN_IP:9119

Le tableau de bord peut afficher l’état d’exécution, les sessions et les paramètres du modèle. Il est utile pour redémarrer et surveiller la passerelle, mais il faut le compléter par les journaux lorsqu’une erreur d’autorisation survient au niveau du processus.

Liste de vérification du dépannage de Hermes Slack sur ZimaOS

1. Confirmez que la configuration du modèle Hermes elle-même fonctionne avant d’ajouter Slack.
2. Entrez dans le conteneur ZimaOS en tant qu’ hermes utilisateur, et non en tant que root, pour le fonctionnement normal de la passerelle.
3. Utilisez autant que possible le manifeste Slack actuel de Hermes au lieu de deviner manuellement les portées.
4. Confirmez que le xoxb- le jeton de bot et xapp- le jeton d’application et le jeton de bot appartiennent à la même application Slack prévue.
5. Confirmez que le mode Socket est activé.
6. Confirmez que votre Slack Member ID figure dans SLACK_ALLOWED_USERS.
7. Invitez Hermes dans le canal que vous testez.
8. Vérifiez app_mention et que les événements de messages requis sont abonnés.
9. Réinstallez l’application Slack après avoir modifié les portées ou les abonnements aux événements, lorsque Slack le demande.
10. Si /opt/data/gateway.lock échoue, vérifiez les propriétaires et les journaux Hermes de ZimaOS avant de redémarrer à nouveau.
11. Une fois la passerelle opérationnelle, testez séparément un message direct et une mention dans un canal.

FAQ sur Hermes Slack sur ZimaOS

Que signifie l’erreur d’autorisation gateway.lock ?

Cela signifie que le processus Hermes ne peut pas accéder au fichier de verrouillage d’exécution à l’emplacement attendu. La documentation actuelle de ZimaSpace indique qu’un /opt/data l’erreur d’autorisation est généralement liée à des fichiers dont le propriétaire est root après l’exécution de Hermes Gateway en tant que root.

Dois-je exécuter Hermes Gateway en tant que root pour résoudre le problème ?

Pas comme solution normale. ZimaSpace indique d’entrer dans le conteneur en tant que hermes utilisateur pour les opérations Hermes normales. Un shell root ne doit être utilisé que temporairement, lorsque vous avez confirmé qu’une réparation des propriétaires est nécessaire.

Pourquoi le bot Hermes est-il visible dans Slack, mais ne répond-il pas ?

Le fait que l’application soit installée et qu’on vous ait invité prouve seulement que Slack connaît l’application. Hermes a toujours besoin d’une passerelle opérationnelle, d’une connexion Socket Mode valide, d’abonnements corrects aux événements, d’autorisations d’espace de travail appropriées et d’un Slack Member ID autorisé.

Hermes Slack a-t-il besoin d’une URL webhook publique ?

Non. L’intégration Slack actuelle de Hermes utilise le mode Socket via des WebSockets. L’instance Hermes peut donc rester derrière un pare-feu sans point de terminaison webhook Slack entrant public.

Quelle est actuellement la meilleure façon de configurer l’application Slack ?

Utilisez le manifeste Slack généré par Hermes lorsque votre version installée de Hermes le prend en charge. Cela réduit les erreurs liées à des portées, des abonnements à des événements ou des définitions de commandes slash manquants.