Configurer Hermes Agent sur Discord (bot + voix)

Pourquoi faire tourner Hermes Agent dans Discord

Si votre projet, votre studio ou vos amis vivent déjà sur un serveur Discord, c'est là que votre agent doit être joignable. Les threads, les salons vocaux et les salles réservées par rôle donnent à Hermes un contexte qu'aucun tableau de bord isolé ne peut fournir : qui pose la question, dans quel salon il se trouve, s'il parle ou s'il tape, et où la réponse doit atterrir.

Hermes Agent embarque un support Discord de premier ordre qui couvre à la fois le texte et la voix. Le runtime se connecte vers Discord via le Gateway WebSocket standard : il peut donc vivre sur votre laptop, sur un petit VPS ou derrière le NAT de votre box, et continuer à recevoir les messages en temps réel. Aucun webhook public à exposer, aucun port entrant à ouvrir. Le même runtime qui répond aux messages texte peut aussi rejoindre un salon vocal avec /voice join, écouter via STT et répondre à voix haute via TTS.

Ce guide déroule le setup complet de bout en bout : créer l'application Discord, générer le token du bot, activer les intents que Discord exige en silence, câbler l'allowlist et le canal principal, inviter le bot avec la bonne URL OAuth2 et les erreurs qui piègent les premiers déploiements.

Ce qu'il vous faut avant de commencer

Un déploiement propre sur Discord demande cinq choses en place :

Un serveur Discord sur lequel vous avez le droit d'ajouter des bots. Si ce n'est pas le vôtre, demandez à l'administration : l'URL d'invitation ne fonctionne que pour quelqu'un ayant "Gérer le serveur" sur la cible.
Une installation d'Hermes Agent qui tourne. Le guide Docker d'Hermes Agent est la voie la plus propre ; sous Windows, le setup WSL2 est l'équivalent.
Une clé de fournisseur de modèle. Anthropic, OpenAI, OpenRouter ou n'importe quel endpoint compatible OpenAI conviennent. Le runtime s'en sert pour répondre.
Votre identifiant Discord numérique pour l'allowlist (Mode développeur → clic droit sur votre nom → Copier l'ID de l'utilisateur).
Environ 15 minutes pour la première installation. Les redéploiements suivants prennent moins d'une minute.

Étape 1 - Créez l'application Discord et le bot

Ouvrez le portail développeur Discord, cliquez sur New Application, donnez-lui un nom (par exemple hermes-agent) et acceptez les conditions développeur. Cela crée un conteneur d'application qui hébergera l'utilisateur bot, les identifiants OAuth2 et le token.

Depuis la page de l'application, allez dans Bot dans la barre latérale. Discord n'exige plus de cliquer sur Add Bot pour les nouvelles applications : l'utilisateur bot est créé automatiquement. Ce que vous devez faire, c'est lui donner un nom d'affichage, un avatar et désactiver Public Bot si vous voulez que l'URL d'invitation ne soit utilisable que par vous.

Cliquez ensuite sur Reset Token pour révéler le token du bot. Il ressemble à MTA…. Copiez-le une seule fois et collez-le directement dans votre .env : Discord ne vous le remontrera jamais, il vous laissera seulement le régénérer.

Traitez ce token comme une clé SSH. Toute personne qui l'a peut agir comme votre bot, lire tous les messages de tous les salons où le bot se trouve et cramer vos tokens du fournisseur de modèle en déclenchant l'agent.

Étape 2 - Activez les Gateway Intents exigés par Discord

C'est l'étape qui casse en silence la majorité des déploiements de bots Discord. Discord découpe "ce que Discord envoie à votre bot" en intents. Certains sont privilégiés : il faut les activer explicitement pour chaque application, sinon Discord ouvre le WebSocket, livre les événements et vide simplement les champs que vous n'avez pas demandés.

Toujours dans Bot, descendez jusqu'à Privileged Gateway Intents et activez :

Message Content Intent - obligatoire pour lire le texte des messages. Sans lui, Hermes reçoit les événements de message avec un contenu vide et reste muet pour toujours.
Server Members Intent - obligatoire pour résoudre l'allowlist face aux vrais IDs membres et pour voir quand des membres arrivent ou partent.
Presence Intent - facultatif, utile si vous voulez que le bot réagisse quand quelqu'un se connecte ou entre dans un salon vocal.

Cliquez sur Save Changes en bas. Cela se fait dans le portail développeur : aucun interrupteur .env pour ça.

Une fois votre bot vérifié et présent sur plus de 100 serveurs, Discord vous obligera à demander ces intents. En dessous de ce seuil, activer les cases suffit.

Étape 3 - Trouvez votre identifiant Discord numérique

Hermes Agent ne répondra qu'aux IDs listés dans DISCORD_ALLOWED_USERS. C'est le contrôle de sécurité le plus important de tout le setup, et il attend des IDs numériques, pas des @handles.

Dans Discord, ouvrez Paramètres utilisateur → Avancé → activez Mode développeur. Fermez les paramètres, faites clic droit sur votre nom dans n'importe quel salon ou liste de membres et choisissez Copier l'ID de l'utilisateur. L'ID ressemble à 284102345871466496. Recommencez pour chaque coéquipier à autoriser.

Sauter l'allowlist revient à publier la clé de votre fournisseur devant tout le serveur. Si une instance Hermes est joignable depuis un serveur public avec une allowlist vide, chaque message que le bot peut lire cramera vos tokens et, dans un salon vocal, chaque bruit qu'il entend sera transcrit.

Étape 4 - Configurez le runtime Hermes

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

DISCORD_BOT_TOKEN=MTA...votre-bot-token...
DISCORD_ALLOWED_USERS=284102345871466496,297811223344556677
DISCORD_HOME_CHANNEL=123456789012345678
DISCORD_HOME_CHANNEL_NAME="#bot-updates"

Une note sur chacun :

DISCORD_BOT_TOKEN - le token copié à l'étape 1.
DISCORD_ALLOWED_USERS - liste d'IDs numériques séparés par des virgules. Le bot ignore tous les autres, y compris les administrateurs du serveur et les autres bots.
DISCORD_HOME_CHANNEL (facultatif) - l'ID du salon pour les messages proactifs, les sorties de tâches planifiées et les notifications de skills. Clic droit sur le salon dans Discord → Copier l'ID du salon. Non renseigné, la sortie proactive part dans le DM du bot avec le premier utilisateur autorisé.
DISCORD_HOME_CHANNEL_NAME (facultatif) - un libellé lisible utilisé dans les logs, sans impact sur le routage.

chmod 600 ~/.hermes/.env après enregistrement. Le token donne un accès complet à votre bot ; traitez-le comme une clé SSH.

Étape 5 - Invitez le bot dans votre serveur

Les bots ne rejoignent pas les serveurs, on les y invite via une URL OAuth2 qui demande d'emblée les bons scopes et permissions. Ceux qu'attend Hermes sont :

Scopes : bot et applications.commands (le second active les slash commands /voice).
Permissions integer : 274878286912, qui couvre Voir les salons, Envoyer des messages, Intégrer des liens, Joindre des fichiers, Lire l'historique des messages, Envoyer des messages dans les threads et Ajouter des réactions.

Récupérez le Client ID de votre application dans General Information sur le portail et injectez-le dans ce modèle :

https://discord.com/oauth2/authorize?client_id=YOUR_APP_ID&scope=bot+applications.commands&permissions=274878286912

Ouvrez l'URL, choisissez votre serveur, confirmez les permissions, et Discord ajoute le bot comme un membre. Vous pouvez aussi construire l'URL depuis OAuth2 → URL Generator du portail si vous préférez cocher des cases : le résultat est le même.

Pour la voix, vous voudrez en plus Se connecter et Parler sur le salon vocal spécifique visé. Si elles manquent après l'invitation, ajoutez au bot un rôle qui les accorde ou modifiez directement les surcharges de permission du salon.

Étape 6 - Lancez le gateway et envoyez le premier message

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

hermes gateway restart

Ou, avec Docker Compose :

docker compose restart gateway

Suivez les logs et attendez le handshake Discord :

hermes gateway logs --follow

Vous cherchez deux lignes, dans cet ordre :

discord: connecting to Gateway
discord: connected as votre-nom-bot#1234 (guilds: 1)

Si vous ne voyez que la première et rien ensuite, le token est faux ou a été régénéré. Si le bot se connecte mais ne répond pas dans le salon, soit Message Content Intent est toujours désactivé sur le portail, soit votre ID n'est pas dans DISCORD_ALLOWED_USERS.

Une fois en ligne, envoyez-lui un DM ou mentionnez-le avec @ dans un salon qu'il peut voir. Hermes répond dans la même conversation, avec toute sa mémoire et son contexte de skills intacts. À partir d'ici, toutes les capacités d'Hermes, mémoire persistante, tâches planifiées et skills personnalisées, marchent exactement comme sur la surface Telegram.

Étape 7 - Activez la voix (facultatif, mais sympa)

Les salons vocaux Discord sont une surface de premier ordre pour Hermes. Une fois le bot dans le serveur avec Se connecter et Parler, rejoignez vous-même un salon vocal et, dans n'importe quel salon textuel visible par le bot, tapez :

/voice join

Le bot va rejoindre le salon vocal dans lequel vous êtes, commencer à écouter via le fournisseur STT que vous avez configuré et répondre à voix haute via le TTS. La surface de commandes est :

/voice join - rejoint votre salon vocal actuel.
/voice channel - alias de /voice join.
/voice leave - quitte le salon vocal.
/voice status - indique si le mode voix est actif et dans quel salon le bot se trouve.

Seuls les utilisateurs présents dans DISCORD_ALLOWED_USERS sont transcrits ; l'audio des autres est ignoré, ce qui compte si le salon vocal est partagé avec des personnes non explicitement autorisées. Pour choisir une pile STT/TTS qui tient bien sur le flux Opus de Discord, le tour d'horizon du mode voix d'Hermes est la lecture suivante.

Les erreurs qui mordent en premier

Cinq erreurs expliquent presque tous les fils "mon setup Discord est cassé" :

Message Content Intent toujours désactivé. Le bot se connecte, rejoint le serveur et ne répond à rien. Discord ne vous prévient pas. Activez-le dans le portail et redémarrez le gateway.

DISCORD_ALLOWED_USERS vide. Le défaut est d'ignorer tout le monde. C'est un défaut sûr voulu, mais il donne l'impression que le bot est cassé pour quelqu'un qui teste pour la première fois et oublie d'ajouter son propre ID.

Mauvaises permissions dans l'invitation. Si le bot ne voit pas le salon ou n'a pas Envoyer des messages, il reste muet même pour les utilisateurs autorisés. Réinvitez-le avec le permissions integer 274878286912 ou corrigez le rôle dans Paramètres du serveur → Rôles.

Permissions vocales manquantes sur un salon particulier. Le bot a Se connecter et Parler au niveau du serveur, mais une surcharge de salon les lui retire. Discord affiche le bot comme "connecté" mais ne produit aucun audio dans les deux sens. Vérifiez l'onglet permissions du salon vocal.

Deux processus de gateway sur le même volume de données. Si vous démarrez un gateway en mode Discord et un autre en mode Telegram sur le même dossier /data, l'ordre des messages et les écritures mémoire se corrompent mutuellement en quelques minutes. Lancez un seul gateway avec les blocs DISCORD_* et TELEGRAM_* réunis dans .env si vous voulez les deux surfaces : le runtime les multiplexe nativement.

Si le problème a l'air Discord mais que les symptômes sentent le général, le guide de dépannage Telegram traite plus en profondeur les soucis de gateway et de fournisseur, et la plupart sont indépendants de la surface.

Discord et Telegram, côte à côte

Sujet	Discord	Telegram
Temps de setup	15 min (app + intents + invitation)	5 min (un token BotFather)
Portée	Derrière un pare-feu (Gateway WebSocket)	Derrière un pare-feu (long-poll)
Champ d'allowlist	`DISCORD_ALLOWED_USERS` (IDs numériques)	`TELEGRAM_ALLOWED_USERS` (IDs numériques)
Idéal pour	Communautés, salons vocaux, serveurs de projet	Usage perso, mobile d'abord, notes vocales
Threads	Natifs (salons + threads)	Réponses citées uniquement
Voix	Rejoindre un salon vocal, STT/TTS en direct	Notes vocales, réponses transcrites

Les deux surfaces ne sont pas exclusives. Le même runtime Hermes peut servir les deux en même temps, pratique quand un chat perso Telegram et un salon vocal partagé Discord puisent dans la même mémoire.

Sautez la plomberie Discord

Les étapes sont simples, mais vous restez propriétaire de l'hôte : sauvegardes, TLS du tableau de bord, rotation des logs et cadence des mises à jour. Pour une installation perso, ça va. Pour un serveur qui veut le bot en ligne en quelques minutes et sans charge d'exploitation ensuite, Hermify provisionne un runtime Hermes managé sur Telegram, garde la mémoire persistante et fait tourner les tokens sans que vous touchiez un .env.

Vous apportez la clé du fournisseur de modèle et la surface que vous voulez ; la plateforme s'occupe de tout ce qui est en dessous. Si vous pesez ce compromis avant d'investir dans votre propre VPS, la comparaison auto-hébergement vs managé déroule les chiffres de coût et de maintenance.