Hermes Agent non risponde su Telegram: soluzioni veloci

Il bot funzionava, e ora no

Mandi un messaggio. Non torna nulla. Il bot è ancora nella tua chat, l'avatar è lì, ma la risposta non arriva. È il problema più comune di Hermes Agent su Telegram, e il motivo per cui ci si perde un'ora è quasi sempre lo stesso: si tira a indovinare i fix prima di sapere quale strato si è rotto.

Hermes su Telegram in realtà sono tre cose impilate. Il processo agente di Hermes (ragionamento e strumenti). Il gateway di Hermes (long-polling contro Telegram). E Telegram stesso (config di BotFather, allowed users, modalità privacy). Quando il bot si zittisce, il guasto vive esattamente in una di queste tre, e la strada più veloce per uscirne è isolare quale prima di toccare nulla.

Questa guida fa i controlli nell'ordine che intercetta più in fretta le cause più frequenti. Se hai già seguito la guida generale al troubleshooting di Telegram, questa è la versione corta e per sintomo per il caso preciso di "nessuna risposta".

Controllo 1: il tuo user ID è davvero nella lista permessa?

Nove volte su dieci è così. Hermes non risponde a nessuno il cui ID numerico di Telegram non sia in telegram_allowed_users. Il bot riceve il messaggio, il gateway lo instrada, e Hermes lo scarta in silenzio. Dal tuo lato sembra identico a un bot morto.

Due cose vanno storte qui:

Hai messo @utente invece dell'ID numerico. @utente non è quello che Hermes vuole. Manda /start a @userinfobot su Telegram, copia il numero della risposta e usa quello.
Hai aggiunto un utente nuovo dopo l'ultimo riavvio e non hai ricaricato la config. Hermes legge telegram_allowed_users all'avvio. Cambi, riavvii il gateway.

La config vive in config.yaml:

telegram_allowed_users: "123456789,987654321"

Se sei su Hermify, il campo equivalente è nel form delle credenziali del dashboard.

Controllo 2: dimostra che il gateway sta girando davvero

Prima di dare la colpa a Telegram, dimostra che il gateway è su.

hermes gateway status

Se non gira, il bug è quello. Avvialo:

hermes gateway start

Se gira ma il bot resta muto, segui il log mentre mandi un messaggio di test:

tail -f ~/.hermes/logs/agent.log

Stai cercando una di tre cose. Una riga "message received" vuol dire che il gateway sta facendo il suo mestiere e che è Hermes a scartare in silenzio (torna al Controllo 1). Una riga "409 Conflict" vuol dire che due processi stanno facendo polling sullo stesso token (vedi Controllo 4). Nulla del tutto vuol dire che il gateway non sta arrivando a Telegram (vedi Controllo 5).

Controllo 3: il bot token è ancora valido?

BotFather ti fa revocare i token ed è facile revocare quello di un vecchio bot di test, dimenticarlo e chiedersi perché niente funziona.

Apri Telegram, scrivi a @BotFather, manda /mybots, scegli il tuo bot, tocca API Token e confronta la stringa mostrata carattere per carattere con quella nella tua config Hermes. Se non coincidono, o incolli quella attuale in Hermes e riavvii, o premi Revoke current token in BotFather per generarne una nuova e incolli quella.

Un token non valido si presenta come errore "Unauthorized" nel log di Hermes all'avvio. Se vedi quell'errore, è sempre il token.

Controllo 4: due processi stanno pollando lo stesso bot?

La Bot API di Telegram permette esattamente un consumatore di long-poll per token del bot. Se due processi chiamano getUpdates contemporaneamente, Telegram risponde "409 Conflict: terminated by other getUpdates request" e gli update finiscono al processo che vince ogni ciclo, o a nessuno. Dal tuo lato sembra che il bot salti un messaggio sì e uno no.

Il modo più comune in cui succede non è esotico:

Una unit di systemd fa girare Hermes e tu hai anche aperto una sessione Hermes a mano in tmux.
Stai provando un bot di dev sul portatile ma l'istanza di produzione usa lo stesso token.
Hai tirato su un worker in background e hai dimenticato che il vecchio container è ancora attivo.

Trova il duplicato:

ps aux | grep -E 'telegram|hermes' | grep -v grep

Uccidi quello che non volevi tenere, poi riavvia il sopravvissuto. I 409 spariscono in pochi secondi perché Telegram libera la sessione di long-poll obsoleta appena il client perdente si disconnette.

Controllo 5: il silenzio nei gruppi di solito è la modalità privacy

Se il bot funziona in DM ma non in un gruppo, il colpevole è quasi sempre la modalità privacy dei bot di Telegram, non Hermes.

La modalità privacy è attiva di default in ogni bot nuovo. Vuol dire che il bot vede solo i messaggi che lo menzionano direttamente, che rispondono a un suo messaggio o che arrivano come comandi. Il chiacchiericcio normale del gruppo non arriva mai al tuo gateway Hermes.

Due modi per risolverlo:

Rendi il bot admin del gruppo. I bot admin vedono tutto, è l'opzione meno sorprendente.
Disattiva la modalità privacy. In BotFather manda /setprivacy, scegli il bot, seleziona Disable. Poi rimuovi il bot dal gruppo e riaggiungilo. Le modifiche alla modalità privacy hanno effetto solo al riaggiungerlo.

Se fai girare il bot in un topic o thread di forum, controlla anche che la config Hermes copra proprio quel thread in allowed_chats e negli ID di topic. Un bot autorizzato a parlare nel canale generale resterà muto in un thread operativo se quell'ID di topic non è nella lista.

Controllo 6: la tua rete sta uccidendo il long-poll

Se il bot risponde una volta all'avvio e poi tace esattamente per lo stesso tempo ogni volta prima di risvegliarsi, la tua rete sta chiudendo il long-poll inattivo prima che Telegram gli possa consegnare un update. Router domestici, VPS economici e reti aziendali lo fanno spesso con timeout NAT.

Attiva i log di debug e guarda:

export HERMES_LOG_LEVEL=debug
hermes gateway restart

Voci "connection reset" ripetute a intervalli fissi confermano la diagnosi. Accorcia il poll timeout di Hermes così si riconnette più spesso dell'idle timeout della tua rete:

hermes config set messaging.telegram.poll_timeout 30

Il default è 60. Scendi a 30 o meno e il problema del reset sparisce, perché chiudi e riapri il long-poll prima che la rete si stufi. È la stessa causa dietro tanti "funziona in locale, si rompe dopo il deploy" su infrastrutture economiche.

Controllo 7: il loop dell'agente è morto in silenzio per un errore del provider

Il gateway è su, il token va bene, la lista dei permessi è giusta, ma le risposte non arrivano lo stesso. Cerca nel log un errore del provider del modello vicino all'ultima risposta andata a buon fine. Rate limit, quote esaurite e risposte 5xx dal provider LLM possono far crashare il loop dell'agente in alcune versioni di Hermes senza riavvio. Il gateway continua a pollare, riceve il tuo nuovo messaggio, lo passa avanti, e dall'altro lato non c'è nessuno che risponda.

Il fix è un riavvio più un controllo sul dashboard del provider per la causa a monte. Se sei sul tier gratuito di un provider e hai esaurito la quota giornaliera a metà conversazione, il bot sembrerà "non risponde" finché la finestra di quota non gira. Passa a un piano a pagamento o cambia provider nella config Hermes verso un altro backend, poi riavvia il gateway.

Un ordine di diagnosi da due minuti che funziona

Quando hai fretta, segui questo ordine e atterri sulla causa in meno di due minuti su ogni caso reale che abbiamo visto:

hermes gateway status - è su?
tail -f ~/.hermes/logs/agent.log - un messaggio nuovo arriva davvero a Hermes?
Se sì, controlla telegram_allowed_users.
Se no, cerca "409 Conflict" (poller duplicato) o "Unauthorized" (token revocato) nel log.
Se niente di tutto ciò e il bot è muto solo nei gruppi, è la modalità privacy.
Se niente di tutto ciò e si zittisce a intervalli regolari, è l'idle timeout della tua rete.
Se niente di tutto ciò e si è azzittito dopo aver funzionato, è un crash del provider a monte.

Salta del tutto il loop di debug

Ogni controllo qui sopra esiste perché Telegram, il gateway, Hermes e il tuo provider sono quattro pezzi mobili che possono guastarsi in modo indipendente. Quando vivono tutti sulla tua infrastruttura, sei tu quello che riceve la chiamata ogni volta che uno inciampa.

Hermify è un Hermes Agent gestito su Telegram. Il tuo bot token, la lista degli utenti permessi e la chiave del provider vanno nel dashboard una volta. Gateway, riavvii, cattura dei log e logica di riconnessione tocca a noi. Quando qualcosa a monte fa i capricci, il card di stato nel dashboard ti dice quale strato, e un click lo riavvia. Non apri più ~/.hermes/logs/agent.log se non vuoi.

Inizia con Hermify e rimetti il bot online in circa un minuto, con memoria che resta tua.