Come collegare Hermes Agent a Telegram

In breve. Crea un bot con @BotFather su Telegram (/newbot) e copia il suo token. Dai a Hermes Agent il token e il tuo ID utente Telegram numerico: solo gli ID nella sua lista di utenti autorizzati, o le persone che approvi con un codice di abbinamento, possono parlargli; senza lista, uno sconosciuto riceve soltanto un codice di abbinamento che dovresti approvare tu. Sulla tua macchina si tratta di TELEGRAM_BOT_TOKEN e TELEGRAM_ALLOWED_USERS in ~/.hermes/.env, oppure di hermes gateway setup. Su PlayNHost incolli il token e il tuo ID nella pagina Agente e riavvii.

Verificato il 7 novembre 2026, valido per Hermes Agent v0.23.0.

Questa guida usa la documentazione di Hermes Agent su Telegram e sulla sicurezza e il pannello PlayNHost così come funziona oggi. Il supporto a Telegram è integrato nel gateway di messaggistica di Hermes Agent: non c'è nulla da installare in più.

Passo 1: crea il bot e copia il suo token

1. In Telegram, apri una chat con @BotFather (o t.me/BotFather). Controlla che il nome sia esattamente @BotFather.
2. Invia /newbot, scegli un nome visibile, poi un nome utente che finisce con bot.
3. BotFather risponde con il token, che ha questo aspetto: 123456789:ABCdefGHIjklMNOpqrSTUvwxYZ. Tienilo privato: chiunque lo abbia può controllare il tuo bot. Se trapela, revocalo con /revoke in BotFather.

Un solo programma per bot. Le FAQ di Hermes Agent dicono che ogni piattaforma di chat ha bisogno dell'uso esclusivo di un token del bot. Se una vecchia copia di Hermes Agent, o un altro programma, usa ancora lo stesso token, fermala prima oppure crea un nuovo bot.

Passo 2: trova il tuo ID utente Telegram

La lista di utenti autorizzati di Hermes Agent vuole il tuo ID utente numerico, un numero come 123456789, non il tuo @username. Ecco come ottenerlo:

• Su PlayNHost, dalla console. Scrivi al tuo bot prima di aver impostato qualsiasi ID: la console stampa il tuo ID. Dettagli nel Passo 3 qui sotto.
• Dal log di Hermes Agent. Quando qualcuno che non è in lista invia un messaggio diretto, il suo log (~/.hermes/logs/gateway.log) riceve un avviso che inizia con "Unauthorized user" e riporta l'ID numerico del mittente (tra parentesi dopo il nome quando gli sconosciuti sono impostati per essere ignorati, come su PlayNHost).
• Un bot di terzi. La documentazione di Hermes Agent suggerisce @userinfobot o @get_id_bot, che rispondono con il tuo ID.

Passo 3 su PlayNHost: incolla il token e il tuo ID

Nella stessa pagina ti serve una chiave di un provider IA. Senza, Avvia si ferma con "Your agent is not set up yet: it needs an API key from one AI provider and a Telegram or Discord bot token."

1. Apri il tuo server su panel.playnhost.com, poi la scheda Agente.
2. Sotto Provider IA, imposta una chiave se non l'hai ancora fatto (vedi quale chiave di un provider IA usare).
3. Sotto App di chat, premi Imposta su Token del bot Telegram, incolla il token di BotFather e premi Salva. Il pannello ne controlla la forma; un'incollatura sbagliata riceve "That is not a valid telegram bot token." Una volta salvato, la riga mostra solo gli ultimi quattro caratteri, e il token non viene più mostrato.
4. Non conosci ancora il tuo ID? Lascia vuoto ID utente Telegram e premi Avvia. Il primo avvio installa Hermes Agent, e nei nostri test ha richiesto circa da 2,5 a 4 minuti. Quando l'agente è attivo, la console stampa:

   [PlayNHost] Your agent is running
   [PlayNHost] Telegram: nobody can message your agent yet. Send your bot any message: your Telegram user ID appears here in the console. Put it on the Agent page, then restart.

   Invia un messaggio al tuo bot su Telegram. Non risponde, nemmeno con un codice di abbinamento: su PlayNHost, Hermes Agent ignora chiunque non sia in lista. Entro circa 20 secondi (la console controlla il log di Hermes Agent ogni 20 secondi) mostra il tuo ID:

   [PlayNHost] Telegram user 123456789 messaged your agent and was ignored. If that is you, add 123456789 to the Telegram user IDs on the Agent page, then restart.

5. Sotto Chi può scrivergli, digita il numero in ID utente Telegram e premi Salva. Più ID vanno sulla stessa riga, separati da virgole o spazi.
6. La pagina dice "Le modifiche si applicano al prossimo avvio del tuo agente." Premi Riavvia ora. La console poi conferma:

   [PlayNHost] Telegram: only user 123456789 can message your agent.

7. Scrivi al tuo bot. Il tuo agente risponde. I messaggi da qualsiasi altro account Telegram vengono ignorati, e ogni nuovo mittente che scrive direttamente al bot compare nella console una volta per avvio, così puoi aggiungere un amico allo stesso modo.

Che cosa imposta PlayNHost per te

• Gli ID nella pagina Agente arrivano a Hermes Agent come TELEGRAM_ALLOWED_USERS. Ogni altro modo di far entrare persone (interruttori "consenti tutti", altre liste, permessi di gruppo, approvazioni di abbinamento) viene disattivato a ogni avvio, e l'agente viene fermato se ne compare uno mentre è in esecuzione.
• Gli sconosciuti vengono ignorati (unauthorized_dm_behavior: ignore) invece di ricevere il codice di abbinamento predefinito di Hermes Agent, perché un server PlayNHost non ha una riga di comando con cui approvare un codice.
• Il token arriva a Hermes Agent come TELEGRAM_BOT_TOKEN. Una sua copia scritta in .hermes/.env viene rimossa al prossimo avvio, così il token nella pagina Agente è quello usato.
• Sono attivi solo Telegram e Discord. WhatsApp è rifiutato: la documentazione di Hermes Agent dice che il suo bridge WhatsApp emula una sessione di WhatsApp Web e comporta un rischio di ban.

Passo 3 sulla tua macchina

1. Lancia la procedura guidata e scegli Telegram. Chiede il token e gli ID utente autorizzati e li scrive per te:

   hermes gateway setup

2. Oppure aggiungili a mano in ~/.hermes/.env:

   TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
   TELEGRAM_ALLOWED_USERS=123456789

   Più ID sono separati da virgole.
3. Avvia il gateway con hermes gateway e scrivi al tuo bot. Per tenerlo attivo dopo il logout, vedi come eseguire Hermes Agent 24/7.

Senza alcuna lista di utenti autorizzati, Hermes Agent nega tutti. Il suo comportamento predefinito con gli sconosciuti è un codice di abbinamento che approvi con hermes pairing approve telegram <code>; i codici scadono dopo un'ora. La documentazione di Hermes Agent offre anche GATEWAY_ALLOW_ALL_USERS=true, e lo sconsiglia per un bot che può eseguire comandi.

Quando non risponde

Su PlayNHost, il log di Hermes Agent è .hermes/logs/gateway.log in Files. Vuoi anche Discord? Vedi collegare Hermes Agent a Discord. Non l'hai ancora configurato? Crea un server Hermes Agent.

PlayNHost non è affiliato a Nous Research. Hermes Agent è un software open source con licenza MIT.