Come collegare Hermes Agent a Telegram e gestire le attività dal telefono

Puoi inviare messaggi a Hermes Agent o dettargli attività su Telegram dal telefono quando sei lontano dal computer e ricevere il risultato nella stessa chat. I risultati delle attività programmate arrivano una volta nella chat che hai designato come chat principale.

Se non hai ancora Hermes, inizia con la guida su che cos'è questo agente e come installarlo, poi torna qui per collegare Telegram.

Sono disponibili ulteriori istruzioni nella documentazione di Ailoot.

Di cosa hai bisogno per collegare Hermes Agent a Telegram?#

Il comando hermes doctor controlla l'installazione di Hermes e la connessione al modello. Creeremo il bot nell'app Telegram e ti servirà un computer per eseguire i comandi nel terminale.

Come si crea un bot tramite BotFather?#

Ogni bot di Telegram ha un token, una chiave segreta per controllare il bot. Viene rilasciato dal bot ufficiale di Telegram, @BotFather.

1. Apri @BotFather

   Cerca @BotFather su Telegram oppure apri t.me/BotFather. Il vero BotFather ha un segno di spunta blu di verifica. Avvia la conversazione toccando «Start».

2. Invia il comando /newbot

   BotFather ti chiederà due nomi. Il primo è il nome visualizzato e può essere qualsiasi cosa, per esempio «Il mio agente». Il secondo è il nome utente: deve essere univoco e terminare con bot, per esempio moy_agent_bot.

3. Ottieni il token

   BotFather ti invierà un messaggio di congratulazioni e una lunga stringa nel formato 123456789:ABCdefGHIjklMNOpqrSTUvwxYZ. Questo è il token del bot. Copia l'intera stringa.

C'è anche un metodo rapido che non richiede una conversazione manuale con BotFather. Nella dashboard web di Hermes (hermes dashboard) e nell'app desktop, nella pagina «Messaging → Telegram», c'è un pulsante «Create with QR»: scansiona il codice con il telefono e Hermes crea un bot, rileva il tuo ID, salva il token nelle impostazioni e riavvia il gateway. I passaggi seguenti descrivono il metodo manuale; se hai scelto il QR, passa direttamente alla verifica della connessione.

Come trovi il tuo ID Telegram e perché ti serve?#

Un account Telegram ha due identificatori: un nome utente pubblico con il simbolo @ e un ID numerico interno. Hermes usa il numero.

Il metodo rapido «Crea con QR» descritto sopra rileva automaticamente il tuo ID. Annotalo accanto al token.

Come si fornisce il token a Hermes Agent e si avvia il gateway?#

1. Avvia la procedura guidata di configurazione

   hermes gateway setup
   

   Esegui il comando sulla macchina in cui è installato Hermes. La procedura guidata proporrà un elenco di app di messaggistica.

2. Seleziona Telegram e inserisci i tuoi dati

   La procedura guidata ti chiederà il token del bot e gli ID autorizzati (puoi inserirne diversi, separati da virgole) e salverà tutto direttamente nelle impostazioni.

3. Avvia il gateway

   hermes gateway
   

   Il gateway si avvierà e si connetterà a Telegram. Dopo qualche secondo, invia un messaggio qualsiasi al bot dall'app: se Hermes risponde, la connessione è pronta.

Il metodo manuale, in alternativa alla procedura guidata, funziona così: apri il file ~/.hermes/.env e aggiungi due righe, sostituendo il token di BotFather e il tuo ID numerico:

TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
TELEGRAM_ALLOWED_USERS=123456789

La seconda riga autorizza quelle persone in chat private e gruppi; un’autorizzazione separata della chat di gruppo può concedere ulteriore accesso. Separa le persone con virgole. Dopo aver salvato il file, avvia il gateway con lo stesso comando hermes gateway.

Se il bot non risponde nemmeno in una chat privata, controlla i log del gateway nello stesso terminale e verifica prima il token e il tuo ID nella lista di accesso; gli altri errori sono trattati nella tabella alla fine dell'articolo.

Cosa può fare il bot Telegram sul tuo telefono?#

Ci sono cinque funzionalità che ti serviranno più spesso sul telefono.

Messaggi di testo e vocali. Scrivi un'attività a parole o detta un messaggio vocale: se il riconoscimento vocale è configurato, Hermes lo trascriverà e lo capirà. Con un provider locale non servono chiavi: tutto viene elaborato sulla macchina in cui è in esecuzione l'agente.

File e immagini. Puoi inoltrare al bot un documento, un foglio di calcolo o una schermata: l'agente lo riceverà come allegato. Può anche rimandarti file generati: chiedi un rapporto e te lo invierà come file in chat.

Conferme per le azioni pericolose. Quando l'agente sta per fare qualcosa di rischioso, come eliminare file, prima te lo chiede in chat: rispondi «yes» o «y» e lo farà; rispondi «no» o «n» e annullerà.

Pulsanti al posto di rispondere digitando. Quando l'agente ha bisogno di chiarimenti, invia una domanda con pulsanti di opzione inline: tocca un'opzione e l'agente continua a lavorare. Il comando /model senza argomenti mostra un menu di selezione del modello con pulsanti dello stesso tipo.

Notifiche silenziose. Per impostazione predefinita, il telefono squilla solo per le risposte finali, le richieste di conferma e le conferme dei comandi. Le notifiche di servizio come «chiamata a uno strumento» e «compressione del contesto» arrivano in silenzio, così il telefono non squilla a ogni passaggio. Se vuoi le notifiche sonore a ogni passaggio, cambia la modalità nelle impostazioni.

Come ricevi i risultati delle attività in background nella chat?#

Chat principale per le attività programmate. Hermes supporta attività programmate: «ogni mattina alle 7:43, prepara un riepilogo per me». Invia i risultati alla chat principale, che designi una volta inviando il comando /sethome direttamente nella conversazione con il bot. Finché il gateway è in esecuzione, i riepiloghi arrivano automaticamente.

Attività in background. Puoi inviare un'attività lunga da eseguire in background e continuare la tua giornata: il bot ti scriverà quando sarà pronta. Un'attività avviata da un argomento restituirà la risposta nello stesso argomento, così non si perde nulla.

Limitazione importante: il bot risponde solo mentre il gateway è in esecuzione. Se spegni o metti in sospensione il computer che esegue Hermes, il bot non risponderà finché la macchina non sarà di nuovo in funzione. Per tenere il bot sempre online, sposta l'agente su un server: abbiamo una guida separata su come mantenere Hermes Agent in esecuzione 24 ore su 24. Per impostazione predefinita, il gateway interroga Telegram per i nuovi messaggi; per le piattaforme cloud che entrano in sospensione se non ricevono traffico, la documentazione offre una modalità webhook, che inverte la direzione della connessione in modo che sia Telegram a inviare richieste al bot.

Come impedisci agli estranei di usare il bot?#

Il tuo bot può essere trovato nella ricerca di Telegram tramite il suo nome utente, quindi la protezione si basa su due elementi: la lista di accesso e la segretezza del token.

Configura prima l’accesso dei mittenti con TELEGRAM_ALLOWED_USERS. Per i gruppi controlla anche TELEGRAM_GROUP_ALLOWED_CHATS: una chat elencata consente l’accesso a ogni membro, anche se il suo ID manca dalla lista personale. La sola lista personale vuota non dimostra quindi che tutti i gruppi siano chiusi.

In secondo luogo, c'è il token. Non deve finire in schermate, messaggi inoltrati o repository. Se il token viene divulgato, revocalo con il comando /revoke in BotFather. Poi inserisci il nuovo token nelle impostazioni e riavvia il gateway.

Nei gruppi, autorizzazione del mittente e della chat sono distinte. Un membro di un gruppo consentito da TELEGRAM_GROUP_ALLOWED_CHATS può usare il bot anche se non compare in TELEGRAM_ALLOWED_USERS. Se l’accesso deve restare individuale, non autorizzare l’intero gruppo; configura e verifica le restrizioni sui mittenti nella versione installata. Se vuoi che il bot risponda in un gruppo solo quando viene chiamato, c'è l'impostazione telegram.require_mention: in tal caso risponde a una menzione @, a una risposta a un suo messaggio, a un comando come /command@yourbot e alle corrispondenze con i tuoi schemi in telegram.mention_patterns, ignorando i normali messaggi del gruppo.

Perché il bot non risponde in un gruppo e come si risolve?#

I nuovi bot Telegram hanno la modalità privacy attiva per impostazione predefinita; la documentazione di Hermes la descrive come la fonte di confusione più comune con i bot nei gruppi. In questa modalità, il bot riceve solo i messaggi che iniziano con un comando /, le risposte ai propri messaggi e le notifiche di servizio. Semplicemente non riceve i normali messaggi del gruppo: Telegram non glieli invia e nessuna impostazione dell'agente può risolvere il problema.

Come risolvere:

1. Apri @BotFather e invia /mybots.
2. Seleziona il tuo bot.
3. Apri «Bot Settings» → «Group Privacy» → «Turn off».
4. Rimuovi il bot dal gruppo e aggiungilo di nuovo.

È facile dimenticare il quarto passaggio e poi dire che il bot «continua a non rispondere». Telegram ricorda l'impostazione privacy applicata quando il bot è entrato nel gruppo e non la aggiorna finché il bot non viene rimosso dal gruppo e aggiunto di nuovo.

Se non vuoi disattivare la privacy a livello globale, c'è una seconda opzione: rendi il bot amministratore del gruppo. I bot amministratori ricevono tutti i messaggi con qualsiasi modalità privacy.

Errori di connessione comuni e come risolverli#

Cos'altro chiedono le persone su Hermes Agent in Telegram?#

Quando sei pronto, scopri Ailoot.