Hermes Agent sur Discord ne répond pas : solutions

Votre bot est en ligne et vous ignore

Le point vert est allumé. Le bot apparaît dans la liste des membres du serveur. Vous le @mentionnez, vous envoyez une slash command, vous tapez un message normal et rien ne revient. Aucune erreur dans les logs, aucune réponse dans le canal. Discord montre le bot comme actif et Hermes Agent montre le gateway comme connecté.

Presque tous les cas que nous voyons se ramènent à l'une de quatre causes. Trois d'entre elles échouent silencieusement par conception, et c'est pour cela que le bot a l'air sain tout en ne faisant rien. Ce post passe en revue chaque cause, comment confirmer que c'est la vôtre et la solution exacte.

Cause 1 : le Message Content Intent est désactivé

C'est la cause la plus fréquente d'un bot Discord qui se connecte puis ignore chaque message normal. Symptôme : vos slash commands fonctionnent, mais rien ne se passe quand vous tapez un message ou une réponse ordinaire. Dans les logs vous voyez arriver des événements MESSAGE_CREATE, mais le champ content est vide.

Ce qui se passe : Message Content est un intent privilégié du gateway. Discord le livre désactivé par défaut. Sans lui, votre bot reçoit chaque événement de message mais n'a pas le droit de voir le texte, donc tout handler qui essaie de matcher par mot-clé, mention ou préfixe échoue en silence.

La solution : ouvrez le Discord Developer Portal, choisissez votre application, entrez dans Bot dans la barre latérale, descendez jusqu'à Privileged Gateway Intents et activez Message Content Intent. Enregistrez.

Pour les bots dans moins de 100 serveurs, aucune validation n'est nécessaire, la bascule prend effet immédiatement. Au-delà de 100 serveurs, vous devez soumettre l'app à vérification et Discord approuve l'intent séparément.

Pas besoin de redémarrer Hermes Agent après la bascule. Le prochain message entrant arrivera avec le champ content renseigné.

Cause 2 : vous avez invité la mauvaise application

Celle-ci fait mal parce que tout a l'air correct au premier regard. Il y a un bot dans votre serveur, il est en ligne et il a le bon avatar. Mais quoi que vous tapiez, il ne répond jamais.

Ce qui se passe : vous avez probablement créé plusieurs applications Discord pendant la configuration (une de test, la vraie, une renommée), et l'URL d'invitation que vous avez utilisée pointe vers une application différente de celle dont le token fait tourner Hermes Agent. Discord connecte volontiers les deux apps au gateway, les deux apparaissent en ligne, mais seule l'app dont vous avez le token reçoit des événements de votre serveur, et si cette app n'est pas invitée, elle ne reçoit rien.

Vérifiez d'abord : dans le Developer Portal, ouvrez l'application dont le token est dans votre .env Hermes Agent, et copiez l'Application ID depuis General Information. Puis dans votre serveur Discord, cliquez droit sur le bot dans la liste des membres et choisissez Copier l'ID utilisateur. Si ces deux IDs ne correspondent pas, vous avez invité une autre app.

La solution : régénérez l'URL d'invitation OAuth2 pour la bonne application (les scopes exacts sont dans la Cause 3), expulsez le mauvais bot de votre serveur et invitez le bon. Confirmez que les IDs correspondent avant d'aller plus loin.

Panneau du Discord Developer Portal montrant un champ Application ID à côté d'une fiche membre d'un serveur affichant un User ID identique à celui du bot

Cause 3 : l'invitation n'incluait pas bot ou applications.commands

Si votre bot apparaît dans le serveur mais ne reçoit jamais de slash commands, ou n'apparaît pas du tout comme un vrai utilisateur bot, l'URL d'invitation OAuth2 a été générée avec les mauvais scopes.

L'OAuth2 de Discord exige deux scopes distincts pour une installation de bot complète :

bot, qui fait que l'application invitée devient un utilisateur bot dans le serveur.
applications.commands, qui permet au bot d'enregistrer et de recevoir des slash commands.

Sans le premier, Discord installe l'app comme une intégration et non comme un membre bot, et le token n'a rien à quoi se rattacher. Sans le second, le bot est bien un membre réel mais les slash commands ne s'enregistrent pas, donc /nimportequoi renvoie L'interaction a échoué ou n'apparaît même pas en autocomplétion.

La solution : dans le Developer Portal, allez dans OAuth2 dans la barre latérale, entrez dans URL Generator, cochez bot et applications.commands dans la section Scopes, puis dans le panneau Bot Permissions qui apparaît en dessous, cochez au minimum :

Send Messages
Read Message History
Embed Links
Attach Files
Use Slash Commands

Copiez l'URL générée en bas de page, ouvrez-la dans un navigateur, choisissez votre serveur et confirmez. Une URL minimale valide ressemble à ceci :

https://discord.com/oauth2/authorize?client_id=<APPLICATION_ID>&scope=bot+applications.commands&permissions=277562616896

Si votre bot doit rejoindre des salons vocaux pour répondre en TTS, cochez aussi Connect et Speak dans la grille de permissions et réinvitez. Discord met à jour l'appartenance existante au lieu d'ajouter un doublon.

Cause 4 : le canal refuse le rôle du bot

Les permissions au niveau serveur ne sont que la moitié de l'histoire. Discord superpose des overrides de canal et de catégorie par-dessus les permissions de rôle, et un seul deny au niveau canal sur Send Messages ou Read Message History va faire taire un bot qui marche partout ailleurs dans le serveur.

Symptôme : votre bot répond dans certains canaux et pas dans d'autres. Ou le bot est muet dans tous les canaux, mais seulement sur ce serveur, alors même que le même bot marche sur votre serveur de test.

Ce qui se passe : les overrides de canal l'emportent sur les permissions de rôle. Si quelqu'un de votre serveur a refusé Send Messages pour @everyone sur ce canal, ou l'a restreint à un rôle que votre bot n'a pas, votre bot ne peut pas y publier même avec Send Messages accordé au niveau serveur. Read Message History est une permission distincte de View Channel, donc un bot peut voir un nouveau message arriver et échouer à répondre si l'historique est refusé, car certaines skills Hermes Agent lisent le contexte récent avant de répondre.

Vérifiez d'abord : clic droit sur le canal concerné, Modifier le canal, Permissions, et regardez le rôle de votre bot (ou @everyone si le bot n'a pas de rôle attribué). Cherchez un X rouge sur l'un de : View Channel, Send Messages, Read Message History, Send Messages in Threads, Use Application Commands.

La solution : soit ajoutez un ✓ explicite pour le rôle du bot sur le canal concerné, soit retirez le deny au niveau de la catégorie (les denies de catégorie se propagent à tous les canaux qu'elle contient). Si votre bot doit répondre dans les threads, Send Messages in Threads est une permission distincte qui a besoin de son propre grant. Voyez le fil de support Discord sur les overrides de canal pour toutes les règles de précédence.

Panneau de permissions de canal Discord montrant un rôle de bot avec des coches vertes sur Send Messages et Read Message History

Ordre de diagnostic qui fait gagner du temps

Quand un bot devient muet, parcourez les causes dans cet ordre plutôt que de sauter sur la correction la plus tape-à-l'œil :

Comparez Application ID et User ID du bot. Soixante secondes, attrape le cas de la mauvaise app avant de toucher au reste.
Vérifiez le Message Content Intent. Soixante secondes dans le Developer Portal, corrige la plus grosse part des bots muets d'un seul toggle.
Regardez les événements entrants. Si vous lancez Hermes Agent avec HERMES_LOG_LEVEL=debug, vous verrez si le bot reçoit des événements et si le champ content des messages est vide.
Revérifiez les scopes d'invitation. Si le symptôme concerne les slash commands, c'est presque toujours la réponse. Réinvitez avec les deux scopes cochés.
Auditez les overrides de canal. À faire seulement une fois les quatre précédents écartés, car c'est le plus lent à vérifier et la cause la moins fréquente quand le bot est muet partout.

Pour le parcours complet d'installation Discord depuis zéro, voyez le guide de setup Hermes Agent sur Discord. Si votre bot n'arrive pas à se connecter à Discord (au lieu de se connecter et rester muet), le post Hermes Agent Docker container keeps restarting couvre les crash loops de gateway.

Quand vous préférez ne pas vous battre avec Discord chaque semaine

Les intents, le modèle de scopes et la matrice d'overrides par canal de Discord sont ce qu'ils sont. Si vous estimez qu'un agent conversationnel simple ne devrait pas exiger un flux OAuth et une validation d'intent privilégié pour dire bonjour, démarrez avec Hermify. Hermify fait tourner un Hermes Agent géré sur Telegram avec la même mémoire et les mêmes skills, en ligne en une minute environ, sans configuration de gateway à surveiller.