Come configurare Hermes Agent su Discord (Bot + Voce)

Perché eseguire Hermes Agent in Discord

Se il tuo progetto, il tuo studio o il tuo giro di amici vive già su un server Discord, è lì che il tuo agente deve essere raggiungibile. Thread, canali vocali e stanze chiuse per ruolo danno a Hermes un contesto che una dashboard isolata non può offrire: chi sta chiedendo, in quale canale si trova, se sta parlando o scrivendo, e dove deve arrivare la risposta.

Hermes Agent porta un supporto Discord di prim'ordine che copre sia il lato testo sia il lato voce di un server. Il runtime si connette in uscita a Discord tramite il Gateway WebSocket standard, quindi può stare sul tuo portatile, su un piccolo VPS o dietro il NAT di casa e continuare a ricevere messaggi in tempo reale. Nessun webhook pubblico da esporre, nessuna porta in ingresso da aprire. Lo stesso runtime che risponde ai messaggi testuali può entrare in un canale vocale con /voice join, ascoltare tramite STT e rispondere ad alta voce tramite TTS.

Questa guida ti porta attraverso la configurazione completa dall'inizio alla fine: creare l'applicazione Discord, generare il token del bot, attivare gli intents che Discord pretende in silenzio, cablare l'allowlist e il canale home, invitare il bot con l'URL OAuth2 giusta e gli errori che colpiscono le prime distribuzioni.

Cosa ti serve prima di partire

Una distribuzione pulita su Discord richiede cinque cose pronte:

Un server Discord su cui hai il permesso di aggiungere bot. Se non è tuo, chiedi all'amministrazione: l'URL di invito funziona solo per chi ha "Gestisci server" sul server di destinazione.
Un'installazione di Hermes Agent in esecuzione. La guida a Hermes Agent con Docker è la strada più pulita; se sei su Windows, il setup con WSL2 è l'equivalente.
Una chiave API di un provider di modello. Anthropic, OpenAI, OpenRouter o qualsiasi endpoint OpenAI-compatibile vanno bene. Il runtime la usa per rispondere davvero.
Il tuo ID utente numerico di Discord per l'allowlist (Modalità sviluppatore → clic destro sul tuo nome → Copia ID utente).
Circa 15 minuti per la prima installazione. Le distribuzioni successive richiedono meno di un minuto.

Passo 1 - Crea l'applicazione Discord e il bot

Apri il Discord Developer Portal, clicca New Application, dai un nome (per esempio hermes-agent) e accetta i termini per sviluppatori. Questo crea un contenitore di applicazione che ospiterà l'utente bot, le credenziali OAuth2 e il token.

Dalla pagina dell'applicazione, vai su Bot nella barra laterale. Discord non richiede più di cliccare Add Bot sulle applicazioni nuove: l'utente bot viene creato in automatico. Quello che devi fare è dargli un nome visibile, un avatar e disattivare Public Bot se vuoi che l'URL di invito sia usabile solo da te.

Poi clicca Reset Token per rivelare il token del bot. Ha una forma tipo MTA…. Copialo una volta e incollalo direttamente nel tuo .env: Discord non te lo mostrerà mai più, potrà solo farti rigenerarlo.

Tratta questo token come una chiave SSH. Chiunque lo abbia può agire come il tuo bot, leggere tutti i messaggi di ogni canale in cui il bot si trova e bruciare i tuoi crediti del provider di modello facendo scattare l'agente.

Passo 2 - Attiva i Gateway Intents che Discord pretende

Questo è il passo che rompe in silenzio la maggior parte delle distribuzioni di bot Discord. Discord divide "cosa Discord manda al tuo bot" in intents. Alcuni sono privilegiati, cioè devi attivarli esplicitamente per ogni applicazione, altrimenti Discord aprirà il WebSocket, consegnerà gli eventi e semplicemente svuoterà i campi che non hai richiesto.

Sempre in Bot, scorri fino a Privileged Gateway Intents e attiva:

Message Content Intent - obbligatorio per leggere il testo dei messaggi. Senza, Hermes riceve gli eventi di messaggio con contenuto vuoto e resta muto per sempre.
Server Members Intent - obbligatorio per risolvere l'allowlist rispetto agli ID reali e vedere quando i membri entrano o escono.
Presence Intent - opzionale, utile se vuoi che il bot reagisca quando qualcuno si connette o entra in un canale vocale.

Clicca Save Changes in fondo. Va fatto nel Developer Portal: non c'è un interruttore in .env.

Quando il tuo bot sarà verificato e presente in più di 100 server, Discord ti costringerà a richiedere questi intents. Sotto quella soglia bastano gli interruttori.

Passo 3 - Trova il tuo ID utente numerico di Discord

Hermes Agent risponde solo agli ID che compaiono in DISCORD_ALLOWED_USERS. È il controllo di sicurezza più importante di tutto il setup e si aspetta ID numerici, non @handle.

In Discord, apri Impostazioni utente → Avanzate → attiva Modalità sviluppatore. Chiudi le impostazioni, clic destro sul tuo nome in un canale o nella lista membri e scegli Copia ID utente. L'ID ha questa forma: 284102345871466496. Ripeti per ogni collega che vuoi autorizzare.

Saltare l'allowlist equivale a pubblicare la chiave del tuo provider davanti all'intero server. Se un'istanza Hermes è raggiungibile da un server pubblico con l'allowlist vuota, ogni messaggio che il bot riesce a leggere brucerà i tuoi crediti e, in un canale vocale, ogni rumore che sente verrà trascritto.

Passo 4 - Configura il runtime di Hermes

Apri ~/.hermes/.env (o il .env letto dal tuo container) e aggiungi:

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

Una nota su ciascuno:

DISCORD_BOT_TOKEN - il token che hai copiato al Passo 1.
DISCORD_ALLOWED_USERS - lista separata da virgole di ID numerici. Il bot ignora tutti gli altri, inclusi gli admin del server e gli altri bot.
DISCORD_HOME_CHANNEL (opzionale) - l'ID del canale per messaggi proattivi, output di task pianificate e notifiche scatenate dalle skill. Clic destro sul canale in Discord → Copia ID canale. Se lasciato vuoto, l'output proattivo va nel DM del bot con il primo utente autorizzato.
DISCORD_HOME_CHANNEL_NAME (opzionale) - un'etichetta leggibile usata nei log, non incide sul routing.

chmod 600 ~/.hermes/.env dopo aver salvato. Il token dà accesso totale al tuo bot; trattalo come una chiave SSH.

Passo 5 - Invita il bot nel tuo server

I bot non entrano nei server, si invitano tramite un'URL OAuth2 che chiede subito gli scope e i permessi giusti. Quelli che Hermes si aspetta sono:

Scope: bot e applications.commands (il secondo abilita i slash command /voice).
Permissions integer: 274878286912, che copre Visualizza canali, Invia messaggi, Incorpora link, Allega file, Leggi cronologia messaggi, Invia messaggi nei thread e Aggiungi reazioni.

Prendi il Client ID della tua applicazione da General Information nel portale e mettilo in questo modello:

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

Apri l'URL, scegli il tuo server, conferma i permessi e Discord lascia il bot lì dentro come un membro. Puoi anche costruire l'URL da OAuth2 → URL Generator nel portale se preferisci spuntare caselle: il risultato è lo stesso.

Per la voce ti serviranno anche Connetti e Parla sul canale vocale specifico che vuoi usare. Se mancano dopo l'invito, aggiungi al bot un ruolo che li conceda o modifica direttamente le sovrascritture di permesso del canale.

Passo 6 - Avvia il gateway e manda il primo messaggio

Riavvia il gateway perché prenda il nuovo ambiente:

hermes gateway restart

Oppure, con Docker Compose:

docker compose restart gateway

Segui i log e aspetta l'handshake con Discord:

hermes gateway logs --follow

Cerchi due righe, in questo ordine:

discord: connecting to Gateway
discord: connected as il-tuo-nome-bot#1234 (guilds: 1)

Se vedi solo la prima e poi nulla, il token è sbagliato o è stato ruotato. Se il bot si connette ma non risponde nel canale, o il Message Content Intent è ancora spento sul portale, o il tuo ID non è in DISCORD_ALLOWED_USERS.

Una volta su, mandagli un DM o menzionalo con @ in un canale che riesce a vedere. Hermes risponde nella stessa conversazione, con memoria e contesto delle skill intatti. Da qui in poi, ogni capacità di Hermes, memoria persistente, task pianificate e skill personalizzate, funziona esattamente come sulla superficie Telegram.

Passo 7 - Accendi la voce (opzionale, ma divertente)

I canali vocali di Discord sono una superficie di prim'ordine per Hermes. Con il bot già nel server con Connetti e Parla, entra tu in un canale vocale e, in un qualsiasi canale testuale che il bot riesce a vedere, scrivi:

/voice join

Il bot entrerà nel canale vocale in cui sei, inizierà ad ascoltare tramite il provider STT che hai configurato e risponderà ad alta voce tramite il TTS. La superficie dei comandi è:

/voice join - entra nel tuo canale vocale attuale.
/voice channel - alias di /voice join.
/voice leave - si disconnette dal canale vocale.
/voice status - dice se la modalità vocale è attiva e in quale canale sta il bot.

Solo gli utenti in DISCORD_ALLOWED_USERS vengono trascritti; l'audio degli altri è ignorato, cosa che conta se il canale vocale è condiviso con persone che non hai autorizzato in modo esplicito. Per scegliere uno stack STT/TTS che funzioni bene sullo stream Opus di Discord, la panoramica sulla modalità vocale di Hermes è la lettura successiva.

Gli errori che mordono per primi

Cinque errori spiegano quasi tutti i thread di "il setup Discord è rotto":

Message Content Intent ancora spento. Il bot si connette, entra nel server e non risponde a nulla. Discord non ti avverte. Attivalo nel portale e riavvia il gateway.

DISCORD_ALLOWED_USERS vuoto. Il default è ignorare tutti. È un default sicuro voluto, ma fa sembrare il bot rotto a chi prova per la prima volta e dimentica di aggiungere il proprio ID.

Permessi sbagliati nell'invito. Se il bot non vede il canale o non ha Invia messaggi, resta muto anche per gli utenti autorizzati. Reinvitalo con il permissions integer 274878286912 o correggi il ruolo in Impostazioni server → Ruoli.

Permessi vocali mancanti su un canale specifico. Il bot ha Connetti e Parla a livello server, ma una sovrascrittura di canale glieli toglie. Discord mostra il bot come "connesso" ma non produce audio in nessuna direzione. Controlla la scheda permessi del canale vocale.

Due processi di gateway sullo stesso volume dati. Se avvii un gateway in modalità Discord e uno in modalità Telegram contro la stessa cartella /data, l'ordine dei messaggi e le scritture di memoria si corrompono a vicenda in pochi minuti. Fai girare un solo gateway con i blocchi DISCORD_* e TELEGRAM_* insieme in .env se vuoi entrambe le superfici: il runtime le multiplexa nativamente.

Se il problema sembra di Discord ma i sintomi sanno di generale, la guida al troubleshooting di Telegram copre più a fondo i problemi di gateway e provider, e la maggior parte è indipendente dalla superficie.

Discord e Telegram, uno accanto all'altro

Aspetto	Discord	Telegram
Tempo di setup	15 min (app + intents + invito)	5 min (un token BotFather)
Raggiungibilità	Dietro firewall (Gateway WebSocket)	Dietro firewall (long-poll)
Campo allowlist	`DISCORD_ALLOWED_USERS` (ID numerici)	`TELEGRAM_ALLOWED_USERS` (ID numerici)
Migliore per	Community, stanze vocali, server di progetto	Uso personale, mobile-first, note vocali
Thread	Nativi (canali + thread)	Solo risposte citate
Voce	Entrare in un canale vocale, STT/TTS in diretta	Note vocali, risposte trascritte

Le due superfici non si escludono. Lo stesso runtime di Hermes può servire entrambe insieme, utile quando una chat personale su Telegram e una stanza vocale condivisa su Discord attingono alla stessa memoria persistente.

Salta l'idraulica di Discord

I passaggi in sé sono lineari, ma il host resta a te: backup, TLS per la dashboard, rotazione dei log e cadenza di aggiornamento. Per un'installazione personale va bene. Per un server che vuole il bot online in pochi minuti e senza carico operativo dopo, Hermify mette a disposizione un runtime Hermes gestito su Telegram, tiene persistente la memoria e ruota i token senza che tu tocchi un .env.

Tu porti la chiave del provider di modello e la superficie che vuoi usare; la piattaforma gestisce tutto il resto. Se stai valutando questo compromesso prima di investire in un tuo VPS, il confronto self-hosting vs gestito passa in rassegna numeri di costo e manutenzione.