Hermes Agent su Discord non risponde: soluzioni

Il tuo bot è online e ti ignora

Il pallino verde è acceso. Il bot compare nella lista membri del tuo server. Lo @menzioni, mandi uno slash command, scrivi un messaggio normale e non torna niente. Nessun errore nei log, nessuna risposta nel canale. Discord mostra il bot come attivo e Hermes Agent mostra il gateway come connesso.

Quasi ogni caso che vediamo si riduce a una di quattro cause. Tre di queste falliscono in silenzio per design, ed è per questo che il bot sembra in salute mentre non fa nulla. Questo post ripassa ogni causa, come confermare che sia la tua e la soluzione esatta.

Causa 1: il Message Content Intent è disattivato

È la causa più comune di un bot Discord che si connette e poi ignora ogni messaggio normale. Sintomo: i tuoi slash command funzionano ma non succede nulla quando scrivi un messaggio o una risposta ordinaria. Nei log vedi arrivare eventi MESSAGE_CREATE, ma il campo content è vuoto.

Cosa succede: Message Content è un intent privilegiato del gateway. Discord lo consegna disattivato di default. Senza, il tuo bot riceve ogni evento messaggio ma non può vedere il testo, quindi qualsiasi handler che prova a fare match per parola chiave, menzione o prefisso fallisce in silenzio.

La soluzione: apri il Discord Developer Portal, scegli la tua applicazione, entra in Bot dalla barra laterale, scorri fino a Privileged Gateway Intents e attiva Message Content Intent. Salva.

Per bot in meno di 100 server non serve approvazione, il toggle ha effetto subito. Sopra i 100 server devi mandare l'app in verifica e Discord approva l'intent a parte.

Non serve riavviare Hermes Agent dopo lo switch. Il prossimo messaggio in arrivo avrà già il campo content popolato.

Causa 2: hai invitato l'applicazione sbagliata

Questa fa male perché a prima vista sembra tutto corretto. C'è un bot nel tuo server, è online, ha l'avatar giusto. Ma qualsiasi cosa tu scriva, non risponde mai.

Cosa succede: probabilmente durante la configurazione hai creato più applicazioni Discord (una di test, quella vera, una rinominata), e l'URL di invito che hai usato punta a un'applicazione diversa da quella il cui token sta facendo girare Hermes Agent. Discord connette volentieri entrambe le app al gateway, entrambe risultano online, ma solo l'app di cui hai il token riceve eventi dal tuo server, e se quell'app non è invitata non riceve niente.

Controlla prima: nel Developer Portal apri l'applicazione il cui token è nel tuo .env di Hermes Agent e copia l'Application ID da General Information. Poi, nel tuo server Discord, fai click destro sul bot nella lista membri e scegli Copia ID utente. Se questi due ID non coincidono, hai invitato un'altra app.

La soluzione: rigenera l'URL di invito OAuth2 per l'applicazione giusta (gli scope esatti sono nella Causa 3), butta fuori dal server il bot sbagliato e invita quello giusto. Conferma che gli ID coincidano prima di andare avanti.

Pannello del Discord Developer Portal con il campo Application ID accanto a una scheda membro del server con un User ID identico a quello del bot

Causa 3: l'invito era senza bot o applications.commands

Se il tuo bot compare nel server ma non riceve mai slash command, o non compare come vero bot user, l'URL di invito OAuth2 è stato generato con gli scope sbagliati.

L'OAuth2 di Discord richiede due scope distinti per un'installazione bot completa:

bot, che è ciò che rende l'applicazione invitata un utente bot nel server.
applications.commands, che è ciò che permette al bot di registrare e ricevere slash command.

Senza il primo, Discord installa l'app come integrazione e non come membro bot, e il token non ha nulla a cui agganciarsi. Senza il secondo, il bot è un membro reale ma gli slash command non si registrano, quindi /qualsiasicosa restituisce L'interazione è fallita o non fa neanche autocompletamento.

La soluzione: nel Developer Portal vai su OAuth2 nella barra laterale, entra in URL Generator, spunta bot e applications.commands nella sezione Scopes, e nel pannello Bot Permissions che compare sotto spunta almeno:

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

Copia l'URL generato in fondo alla pagina, aprila nel browser, scegli il tuo server e conferma. Un URL minimo valido è così:

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

Se il tuo bot deve entrare nei canali vocali per rispondere in TTS, spunta anche Connect e Speak nella griglia permessi e re-invita. Discord aggiorna l'iscrizione esistente invece di creare un duplicato.

Causa 4: il canale nega il ruolo del bot

I permessi a livello di server sono solo metà della storia. Discord sovrappone override di canale e di categoria sopra ai permessi di ruolo, e un singolo deny a livello di canale su Send Messages o Read Message History fa ammutolire un bot che funziona nel resto del server.

Sintomo: il tuo bot risponde in alcuni canali e in altri no. O il bot è muto in ogni canale, ma solo in questo server, anche se lo stesso bot funziona nel tuo server di test.

Cosa succede: gli override di canale battono i permessi di ruolo. Se qualcuno del tuo server ha negato Send Messages per @everyone in questo canale, o lo ha ristretto a un ruolo che il tuo bot non ha, il tuo bot non può postare lì anche con Send Messages concesso a livello server. Read Message History è un permesso distinto da View Channel, quindi un bot può vedere arrivare un nuovo messaggio e comunque fallire nel rispondere se la history è negata, perché alcune skill di Hermes Agent leggono contesto recente prima di rispondere.

Controlla prima: click destro sul canale interessato, Modifica canale, Permessi, e guarda il ruolo del tuo bot (o @everyone se il bot non ha ruolo assegnato). Cerca una X rossa su uno tra: View Channel, Send Messages, Read Message History, Send Messages in Threads, Use Application Commands.

La soluzione: aggiungi un ✓ esplicito per il ruolo del bot sul canale interessato, oppure rimuovi il deny a livello di categoria (i deny di categoria si propagano a tutti i canali contenuti). Se il tuo bot deve rispondere dentro ai thread, Send Messages in Threads è un permesso a sé e ha bisogno del proprio grant. Vedi il thread di supporto Discord sugli override di canale per le regole complete di precedenza.

Pannello permessi di canale Discord che mostra un ruolo bot con spunte verdi su Send Messages e Read Message History

Ordine di diagnosi che fa risparmiare tempo

Quando un bot ammutolisce, ripassa le cause in questo ordine invece di saltare alla correzione più vistosa:

Confronta Application ID e User ID del bot. Sessanta secondi, prende il caso dell'app sbagliata prima che tu tocchi qualsiasi altra cosa.
Controlla il Message Content Intent. Sessanta secondi nel Developer Portal, sistema la grossa fetta di bot muti con un solo toggle.
Guarda gli eventi in ingresso. Se avvii Hermes Agent con HERMES_LOG_LEVEL=debug, vedi se il bot riceve eventi e se il campo content dei messaggi è vuoto.
Ricontrolla gli scope di invito. Se il sintomo sono gli slash command, quella è quasi sempre la risposta. Re-invita con entrambi gli scope spuntati.
Fai un audit degli override di canale. Vale la pena solo dopo aver escluso i primi quattro, perché è il più lento da verificare e la causa meno frequente quando il bot è muto ovunque.

Per il percorso completo di installazione Discord da zero, vedi la guida di setup di Hermes Agent su Discord. Se il tuo bot non riesce nemmeno a connettersi a Discord (invece che connettersi e restare muto), il post Hermes Agent Docker container keeps restarting copre i crash loop del gateway.

Quando preferisci non litigare con Discord ogni settimana

Gli intent, il modello di scope e la matrice di override per canale di Discord sono quelli. Se pensi che un semplice agente conversazionale non dovrebbe richiedere un flusso OAuth e una revisione di intent privilegiato per dire ciao, inizia con Hermify. Hermify gestisce un Hermes Agent su Telegram con la stessa memoria e le stesse skill, attivo in circa un minuto, senza configurazioni di gateway da tenere d'occhio.