Hermes Agent su Telegram: Problemi Comuni e Come Risolverli

Telegram: Il Punto dove la Maggior Parte delle Distribuzioni Hermes si Blocca

Il quickstart di Hermes è veloce. La configurazione di Telegram è dove la maggior parte degli utenti incontra problemi. Non è che il processo sia complicato: ogni passaggio ha diversi modi per andare storto, e quando più cose falliscono silenziosamente, è difficile capire da dove iniziare.

Questa guida tratta i problemi più comuni nell'ordine in cui tendono a presentarsi.

Ottenere il Token del Bot Telegram

Il token proviene da BotFather, l'interfaccia ufficiale di Telegram per la gestione dei bot. Questo passaggio sembra semplice ma ha diverse modalità di errore.

Come farlo correttamente:

1. Apri Telegram e cerca @BotFather.
2. Invia /newbot.
3. BotFather chiede un nome (nome visualizzato) e un username (deve terminare con bot).
4. Dopo la creazione, BotFather ti invia un messaggio contenente il token. Ha un aspetto simile a 7123456789:ABCDef....
5. Copia il token completo, inclusi i due punti e tutto ciò che segue.

Errori comuni:

• Copiare solo l'ID numerico: il token è l'intera stringa dopo i due punti, non solo il numero prima di essi.
• Usare un bot di test da un ambiente di sviluppo: se hai creato un bot mesi fa e non ricordi quale token corrisponde a quale bot, BotFather può mostrarti i bot esistenti con /mybots. Puoi quindi revocare e rigenerare i token.
• Spazi o interruzioni di riga nel token incollato: alcuni flussi di copia aggiungono spazi. Prima di usarlo, incolla il token in un editor di testo semplice per verificare che sia pulito.

La Configurazione TELEGRAM_ALLOWED_USERS

Questa è la parte più frequentemente configurata in modo errato in una distribuzione Hermes su Telegram.

Hermes richiede di specificare quali ID utente Telegram sono autorizzati a inviare messaggi al bot. Senza questa configurazione, il bot non risponde a nessuno. Con un valore errato, il bot non risponderà nemmeno a te, anche se sembra essere in esecuzione.

Di cosa hai bisogno:

Un ID utente Telegram è un numero, non un username. @username non è quello che Hermes si aspetta. Hai bisogno dell'ID numerico, che ha un aspetto simile a 123456789.

Come ottenere il tuo ID utente Telegram:

Apri Telegram, cerca @userinfobot e invia /start. Ti risponderà con il tuo ID utente.

Come configurarlo:

In config.yaml:

telegram_allowed_users: "123456789"

Per più utenti, usa un elenco separato da virgole:

telegram_allowed_users: "123456789,987654321"

Nota Hermify: Nel flusso di onboarding di Hermify, inserisci il tuo ID utente Telegram (o un elenco separato da virgole) nel modulo delle credenziali. Questo campo è separato da quello del token del bot. Entrambi sono obbligatori.

Problema: Il Bot Non Risponde Affatto

Se invii un messaggio al tuo bot e non succede nulla, segui questa checklist:

1. Il gateway Hermes è in esecuzione?

hermes gateway status

Se il gateway non è in esecuzione, il bot non ha un listener. Avvialo:

hermes gateway start

2. Il tuo ID utente è nell'elenco degli autorizzati?

Verifica nuovamente la configurazione telegram_allowed_users. Questa è la causa più comune di un bot silenzioso: il processo è in esecuzione, il gateway è connesso, ma Hermes ignora deliberatamente i tuoi messaggi perché il tuo ID non è nell'elenco.

3. Il token del bot è scaduto o è stato revocato?

BotFather consente di revocare i token. Se hai rigenerato il token dopo averlo aggiunto a Hermes, il vecchio token non funziona più. Controlla BotFather con /mybots, seleziona il tuo bot, vai su API Token e verifica che il token nella tua configurazione corrisponda.

4. Il bot è già in un'altra chat?

I bot Telegram rispondono alla chat specifica da cui ricevono i messaggi. Se in precedenza hai aggiunto il bot a un gruppo e Hermes è configurato per rispondere diversamente ai messaggi di gruppo, potrebbe essere necessario avviare la conversazione in una chat diretta (DM) con il bot.

Problema: Errore "Unauthorized" nei Log

Questo errore significa che il token non è valido o è stato revocato. La soluzione è sempre rigenerare il token in BotFather e aggiornare la configurazione di Hermes con il nuovo valore.

In BotFather:

1. Invia /mybots.
2. Seleziona il tuo bot.
3. Vai su API Token → Revoke current token.
4. Copia il nuovo token.
5. Aggiorna config.yaml o il modulo delle credenziali nella dashboard di Hermify.
6. Riavvia Hermes (o il runtime Hermify).

Problema: Il Bot Risponde una Volta, poi Si Azzittisce

Di solito significa che il processo Hermes si è fermato o il gateway si è disconnesso. Cause comuni:

Il processo è stato terminato. Nelle distribuzioni locali o su hosting condiviso economico, i processi vengono terminati quando la memoria è insufficiente o quando l'host ricicla i container. Controlla i log del processo per un crash o un evento OOM (out of memory).

La sessione WSL2 è terminata. Se stai eseguendo Hermes all'interno di WSL2, chiudere il terminale arresta il processo. Consulta la guida WSL2 per eseguire Hermes in modo persistente.

Il loop di polling Telegram è andato in timeout. Il gateway Hermes usa il long-polling per ricevere i messaggi Telegram. Occasionalmente la connessione si interrompe e non viene ristabilita automaticamente. Riavviare il gateway (hermes gateway restart) risolve il problema.

Un errore del modello ha causato un crash. Se l'API LLM ha restituito un errore (limite di frequenza, quota esaurita, risposta errata), alcune versioni di Hermes possono terminare la sessione invece di recuperare. Controlla l'output del terminale o i log per un messaggio di errore recente prima che si verificasse il silenzio.

Problema: I Messaggi Arrivano ma l'Agente Ignora il Contenuto

Questo è diverso da un bot silenzioso. Il bot riceve i messaggi ma le risposte dell'agente sembrano errate o vuote.

Causa più probabile: la finestra di contesto del modello è piena. Hermes legge il tuo MEMORY.md e la cronologia della conversazione in ogni prompt. Se il contesto combinato è troppo lungo per la finestra del modello, il modello riceve un prompt troncato e la qualità della risposta degrada o diventa vuota.

Soluzioni:

• Passa a un modello con una finestra di contesto più ampia (Claude e Gemini supportano 128k+).
• Riduci manualmente il tuo MEMORY.md se è diventato molto grande.
• Usa hermes memory compact se disponibile nella tua versione per riassumere e comprimere la memoria persistente.

Causa meno probabile: l'elenco degli utenti autorizzati ha un problema di corrispondenza parziale. Se la configurazione degli utenti autorizzati contiene 12345 e il tuo ID utente effettivo è 123456789, Hermes non farà la corrispondenza correttamente. Verifica l'ID numerico completo, non una versione troncata.

Problema: Funziona Bene in Locale, Rotto dopo la Distribuzione

La causa più comune qui è una discrepanza tra l'ambiente in cui hai testato e l'ambiente del server.

Controlla queste cose nell'ordine:

1. Il token è corretto nella configurazione del server, non in quella locale. È facile aggiornare il file sbagliato.
2. Il server può raggiungere l'API di Telegram. Alcuni provider di hosting bloccano le connessioni in uscita. Testa con curl https://api.telegram.org/bot<IL_TUO_TOKEN>/getMe dal server.
3. Il processo Hermes si è avviato correttamente. Controlla i log del container o del processo per errori di avvio.
4. La directory di memoria è montata. Se stai usando Docker, verifica che il volume dei dati sia collegato. Un agente che si avvia senza la sua directory dei dati si comporterà in modo anomalo.

Evitare Tutto Questo con l'Hosting Gestito

Il motivo per cui la maggior parte delle persone incontra problemi di configurazione Telegram è che gestiscono la distribuzione da soli, occupandosi contemporaneamente di token, file di configurazione, processi e ambienti server.

Hermify è progettato specificamente per questo problema. Il flusso di onboarding gestisce il collegamento Telegram: fornisci il token del bot e gli ID utente autorizzati una sola volta, e la piattaforma li archivia in modo cifrato, li inietta nel runtime e gestisce il processo del gateway.

Se il bot smette di rispondere su Hermify, non è necessario eseguire il debug del gateway: basta controllare la scheda di stato nella dashboard e avviare un riavvio se necessario. Il ciclo operativo è basato sulla dashboard, non su SSH.

Questo è il cambiamento principale che l'hosting Telegram gestito porta: non la configurazione Telegram in sé, ma chi è responsabile di mantenerla funzionante. Puoi confrontare direttamente questo approccio con una configurazione VPS autogestita nel confronto hosting vs self-hosting.