Como conectar o Hermes Agent ao Telegram

Resposta curta. Crie um bot com o @BotFather no Telegram (/newbot) e copie o token dele. Dê ao Hermes Agent o token e o seu ID numérico de usuário do Telegram: só os IDs da lista de permitidos, ou pessoas que você aprovar com um código de pareamento, podem falar com ele; sem lista de permitidos, um desconhecido só recebe um código de pareamento que você teria de aprovar. Na sua própria máquina, isso são TELEGRAM_BOT_TOKEN e TELEGRAM_ALLOWED_USERS em ~/.hermes/.env, ou hermes gateway setup. Na PlayNHost você cola o token e o seu ID na página Agente e reinicia.

Verificado em 7 de novembro de 2026, correto para o Hermes Agent v0.23.0.

Este guia usa a documentação de Telegram e de segurança do Hermes Agent e o painel da PlayNHost como ele funciona hoje. O suporte ao Telegram já vem embutido no gateway de mensagens do Hermes Agent: não há nada extra para instalar.

Passo 1: crie o bot e copie o token

1. No Telegram, abra uma conversa com o @BotFather (ou t.me/BotFather). Confira se o nome é exatamente @BotFather.
2. Envie /newbot, escolha um nome de exibição e depois um nome de usuário que termine em bot.
3. O BotFather responde com o token, que tem este formato: 123456789:ABCdefGHIjklMNOpqrSTUvwxYZ. Mantenha-o em segredo: quem o tiver pode controlar o seu bot. Se ele vazar, revogue com /revoke no BotFather.

Um programa por bot. O FAQ do Hermes Agent diz que cada plataforma de chat precisa de uso exclusivo de um token de bot. Se uma cópia mais antiga do Hermes Agent, ou qualquer outro programa, ainda usa o mesmo token, pare-a primeiro ou crie um bot novo.

Passo 2: descubra o seu ID de usuário do Telegram

A lista de permitidos do Hermes Agent pede o seu ID de usuário numérico, um número como 123456789, e não o seu @usuário. Formas de obtê-lo:

• Na PlayNHost, pelo console. Mande uma mensagem ao seu bot antes de definir qualquer ID: o console mostra o seu ID. Os detalhes estão no passo 3 abaixo.
• Pelo log do Hermes Agent. Quando alguém que não está na lista envia uma mensagem direta, o log dele (~/.hermes/logs/gateway.log) recebe um aviso que começa com “Unauthorized user” e traz o ID numérico de quem enviou (entre colchetes depois do nome quando os desconhecidos estão configurados para serem ignorados, como na PlayNHost).
• Um bot de terceiros. A documentação do Hermes Agent sugere o @userinfobot ou o @get_id_bot, que respondem com o seu ID.

Passo 3 na PlayNHost: cole o token e o seu ID

Você precisa de uma chave de provedor de IA na mesma página. Sem ela, Iniciar para com “Your agent is not set up yet: it needs an API key from one AI provider and a Telegram or Discord bot token.” (a mensagem aparece em inglês).

1. Abra o seu servidor em panel.playnhost.com e depois a aba Agente.
2. Em Provedor de IA, defina uma chave se ainda não fez isso (veja qual chave de provedor de IA usar).
3. Em Apps de chat, clique em Definir em Token do bot do Telegram, cole o token do BotFather e clique em Salvar. O painel confere o formato; uma colagem errada recebe “That is not a valid telegram bot token.” (em inglês). Depois de salvo, a linha mostra só os quatro últimos caracteres, e o token nunca mais é exibido.
4. Ainda não sabe o seu ID? Deixe IDs de usuário do Telegram vazio e clique em Iniciar. A primeira inicialização instala o Hermes Agent, o que levou cerca de 2,5 a 4 minutos nos nossos testes. Quando o agente está no ar, o console imprime:

   [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.

   Envie uma mensagem ao seu bot no Telegram. Ele não responde, nem mesmo com um código de pareamento: na PlayNHost, o Hermes Agent ignora quem não está na lista. Em cerca de 20 segundos (o console confere o log do Hermes Agent a cada 20 segundos) ele mostra o seu 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. Em Quem pode falar com ele, digite o número em IDs de usuário do Telegram e clique em Salvar. Vários IDs vão em uma só linha, separados por vírgulas ou espaços.
6. A página diz “As alterações valem na próxima vez que o seu agente iniciar.” Clique em Reiniciar agora. O console então confirma:

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

7. Envie uma mensagem ao seu bot. O seu agente responde. Mensagens de qualquer outra conta do Telegram são ignoradas, e cada novo remetente que escreve diretamente ao bot aparece no console uma vez por inicialização, então você pode adicionar um amigo do mesmo jeito.

O que a PlayNHost define para você

• Os IDs da página Agente chegam ao Hermes Agent como TELEGRAM_ALLOWED_USERS. Qualquer outra forma de deixar pessoas entrarem (chaves de permitir todos, outras listas de permitidos, permissões de grupo, aprovações de pareamento) é desligada a cada inicialização, e o agente é parado se alguma aparecer enquanto ele roda.
• Desconhecidos são ignorados (unauthorized_dm_behavior: ignore) em vez de receberem o código de pareamento padrão do Hermes Agent, porque um servidor da PlayNHost não tem linha de comando para aprovar um código.
• O token chega ao Hermes Agent como TELEGRAM_BOT_TOKEN. Uma cópia dele escrita em .hermes/.env é removida na inicialização seguinte, então o token da página Agente é o que vale.
• Só Telegram e Discord estão ativos. O WhatsApp é recusado: a própria documentação do Hermes Agent diz que a ponte de WhatsApp dele emula uma sessão do WhatsApp Web e traz risco de banimento.

Passo 3 na sua própria máquina

1. Rode o assistente de configuração e escolha Telegram. Ele pede o token e os IDs de usuário permitidos e escreve tudo para você:

   hermes gateway setup

2. Ou adicione-os à mão em ~/.hermes/.env:

   TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
   TELEGRAM_ALLOWED_USERS=123456789

   Vários IDs são separados por vírgulas.
3. Inicie o gateway com hermes gateway e envie uma mensagem ao seu bot. Para mantê-lo rodando depois que você sair da sessão, veja como rodar o Hermes Agent 24/7.

Sem nenhuma lista de permitidos, o Hermes Agent nega acesso a todo mundo. O padrão para desconhecidos é um código de pareamento que você aprova com hermes pairing approve telegram <code>; os códigos expiram em uma hora. A documentação do Hermes Agent também oferece GATEWAY_ALLOW_ALL_USERS=true, e desaconselha isso para um bot que pode executar comandos.

Quando ele não responde

Na PlayNHost, o log do próprio Hermes Agent é .hermes/logs/gateway.log em Files. Quer o Discord também? Veja conectar o Hermes Agent ao Discord. Ainda não configurou? Crie um servidor Hermes Agent.

A PlayNHost não é afiliada à Nous Research. O Hermes Agent é um software de código aberto sob a licença MIT.