Hermes Agent no Telegram: vale a pena usar o agente pelo mensageiro em vez do terminal?

Fala aí, beleza? Teu agente não precisa mais morar num terminal aberto esperando você lembrar dele

Ele pode simplesmente te chamar no chat, igual qualquer contato

O Hermes Agent é um agente de IA open source da Nous Research, publicado sob licença MIT no repositório NousResearch/hermes-agent, com 222,6 mil estrelas no GitHub segundo o star-history (dado com referência de 30/07/2026)

E aí vem a pergunta que move este post: pra quê serve conversar com ele pelo mensageiro, se o terminal já está ali? 🙂

Bora destrinchar isso

Como o Hermes chega no Telegram: TUI, gateway e painel web

O Hermes tem dois pontos de entrada oficiais, e um painel de administração por cima

O primeiro é a TUI: o comando hermes abre a interface de terminal e você conversa ali mesmo

O segundo é o gateway de mensageria, que é onde o Telegram entra

E o que é esse gateway? É um único processo em segundo plano que conecta todas as plataformas configuradas (Telegram, Discord, Slack, WhatsApp, Signal ou e-mail), cuida das sessões, roda os cron jobs e entrega as mensagens de voz

Se você conhece aquele daemon que fica de plantão no fundo enquanto tu faz outra coisa, é exatamente essa vibe: um processo só, várias portas de entrada

E dá pra ter mais de um? Dá, o Hermes trabalha com perfis, e aí a regra é um gateway por perfil, cada perfil com o próprio token de bot (voltamos nisso lá nos problemas comuns)

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 116 aulas
• 4 projetos
• 9h 23min

Conhecer formação

A integração com o Telegram é construída sobre a biblioteca python-telegram-bot, e aceita texto, voz, imagens e anexos de arquivo

E tem o terceiro elemento, que muita gente ignora: o painel web oficial, que roda localmente em http://127.0.0.1:9119, tudo na própria máquina

Por ele você administra configuração, chaves de API, gateway, memória, sessões, logs, cron jobs e skills

O painel ainda traz uma aba Chat embutida com o TUI via PTY/WebSocket, ou seja: dá pra conversar por ali também, mas o espírito dele é administrar

Telegram x terminal x painel web: o que cada interface entrega

Antes da tabela, um aviso: as três interfaces falam com o MESMO agente

Não é um Hermes do Telegram e outro do terminal, é o mesmo bicho com portas diferentes

Dois pontos dessa tabela são onde o mensageiro REALMENTE muda o jogo

O primeiro é a entrega: quando o Hermes roda uma tarefa agendada, quem entrega a resposta final é o próprio sistema, no destino configurado

Rodando /sethome no chat que você quiser (DM ou grupo), aquele chat vira o canal de entrega

Traduzindo: o agente te procura, você não precisa procurar ele

O segundo ponto é a mão dupla

Por padrão a entrega de uma tarefa agendada é sem retorno, tipo um recado colado na geladeira

Mas se o job for marcado como continuable, o resumo entregue vira uma conversa em que dá pra responder ali mesmo, com o contexto preservado

É a diferença entre receber um relatório e poder perguntar "e por que esse número subiu?" sem abrir mais nada 😀

Em que tarefas o mensageiro ganha do terminal

Agora vamos ao concreto, porque interface bonita sem caso de uso é só enfeite

Briefing diário. A documentação oficial tem um guia de bot de briefing diário, que é exatamente esse padrão: a tarefa agendada roda sozinha e o resumo cai no mensageiro

Casa perfeito com o /sethome e com o continuable

Assistente de time. Também existe um guia oficial de assistente de time no Telegram, com autorização por usuário pro uso compartilhado

Aqui o mensageiro ganha por um motivo bobo e decisivo: o time JÁ está lá

Grupo sem bagunça de contexto. Em grupos, o Hermes usa por padrão sessões separadas por usuário (group_sessions_per_user: true)

Então duas pessoas no mesmo canal não compartilham histórico nem poluem o contexto uma da outra

E dá pra dar prompts de sistema efêmeros pra grupos ou tópicos específicos: eles são injetados a cada turno e nunca gravados no histórico da transcrição

Trocar de modelo sem sair do chat. O comando /model sem argumentos abre um teclado inline dentro do Telegram, com navegação por provedor e paginação editando a mesma mensagem (Prev/Next, Back, Cancel)

Isso é mto massa pra quem quer testar modelo diferente no meio de uma conversa

Ditar em vez de digitar. A transcrição de áudio pode rodar local com faster-whisper ou por API, com as chaves definidas no arquivo de ambiente do Hermes

Andando na rua, mandar áudio é imbatível

Agora o contraponto honesto, porque não é tudo festa

Memória e histórico são do AGENTE, não do Telegram

As sessões guardam metadados em SQLite (~/.hermes/state.db) e transcrições brutas em JSONL (~/.hermes/sessions/), e existe a ferramenta session_search, que faz busca full-text do SQLite (FTS5) nas conversas passadas, sem chamada de LLM e sem resumo

A memória persistente é coisa separada do histórico: fica em arquivos em ~/.hermes/memories/, injetada no system prompt como snapshot no início da sessão, e o próprio agente gerencia isso com a ferramenta memory

Ou seja: o chat do Telegram é uma janela bonita pra esse acervo, não é o acervo

Quem vive em sessão longa e quer retomar do ponto exato continua muito bem servido pela TUI, que imprime um comando de retomada ao sair e restaura o histórico completo do SQLite

Se você ainda está decidindo qual agente colocar pra rodar, vale olhar essa comparação entre Hermes e OpenClaw antes de investir tempo na configuração

Como conectar o Hermes Agent ao Telegram

Aqui vai o caminho curto, só com o que está documentado

1. Crie o bot no @BotFather e copie o token. O @BotFather (t.me/BotFather) é a ferramenta oficial do Telegram pra gerenciar bots, e é ele quem emite o token

Guarde esse token como se fosse senha, porque é

O erro comum deste passo: colar o token em lugar público e achar que não deu nada

Se vazar, o /revoke no próprio BotFather invalida o token vazado

2. Descubra o seu ID numérico de usuário. Mande uma mensagem pro @userinfobot e ele te devolve o ID (algo no formato 123456789)

O erro comum deste passo: usar o @username no lugar do ID numérico

A allowlist do Hermes trabalha com ID numérico, ponto

3. Rode o assistente de configuração do gateway. É ele quem pergunta o token do bot e os IDs de usuário permitidos e escreve a configuração pra você

hermes gateway setup

Na hora de escolher a plataforma, selecione Telegram e responda o que ele pedir

O erro comum deste passo: deixar a lista de usuários permitidos vazia achando que "depois eu preencho"

Sem ela, o gateway nega todos os usuários por padrão, por segurança

4. Confira onde as coisas ficam. Os arquivos de configuração do Hermes moram no diretório ~/.hermes

~/.hermes/config.yaml
~/.hermes/.env
~/.hermes/logs/gateway.log

As credenciais do Telegram ficam em duas variáveis:

TELEGRAM_BOT_TOKEN=token_gerado_pelo_botfather
TELEGRAM_ALLOWED_USERS=123456789,987654321

Repare que os IDs numéricos vão separados por vírgula

5. No chat, defina o canal de entrega. Rode /sethome no chat do Telegram que você quer usar (DM ou grupo) e é ali que as tarefas agendadas vão entregar o resultado

A variável correspondente é TELEGRAM_HOME_CHANNEL

O erro comum deste passo: rodar o /sethome no chat errado e depois procurar a entrega no lugar onde ela nunca foi mandada

Quem já mexeu com agente por mensageiro reconhece o padrão: é bem parecido com o fluxo de conversar com o agente pelo WhatsApp, muda o mensageiro e muda a burocracia de credencial

Problemas comuns do Hermes no Telegram (e como evitar)

Tome cuidado com estes três, porque eles parecem bug e não são

Sintoma: o bot não responde a ninguém.

Causa: TELEGRAM_ALLOWED_USERS vazio

O gateway nega todos os usuários por padrão quando não existe allowlist, e isso é decisão de segurança, não falha

Solução: preencher a variável com os IDs numéricos separados por vírgula (de novo: ID numérico, não @username)

Sintoma: o polling é rejeitado quando você sobe um segundo gateway.

Causa: o mesmo token de bot reutilizado em dois perfis rodando ao mesmo tempo

O Telegram rejeita o polling concorrente

Solução: um token de bot por perfil, um gateway por perfil

Sintoma: confusão sobre quem pode acionar o bot e qual sessão de grupo serve de contexto.

Causa: são DUAS chaves diferentes fazendo coisas diferentes, e é fácil trocar uma pela outra

Solução: allowed_chats controla onde o bot responde, e group_allowed_chats autoriza a sessão de grupo usada como contexto observado

Pra prevenção, três hábitos simples

Primeiro: acompanhe o log em ~/.hermes/logs/gateway.log, que é onde a verdade aparece

Segundo: ligue o indicador de status (status_indicator), que altera a descrição curta do perfil do bot pra Online ao conectar e Offline no desligamento limpo, com textos personalizáveis

Assim você bate o olho no perfil e já sabe se o gateway está de pé

Terceiro: ajuste o menu de comandos do bot com max_commands (padrão 60) e priority_mode em prepend, append ou replace

Veredito: quando usar o Telegram e quando voltar para o terminal

Sem cima de muro, vamos lá

Use o Telegram quando o trabalho for assíncrono, agendado, em grupo ou móvel

Briefing que chega sozinho, time compartilhando o mesmo assistente com autorização por usuário, anexo entregue como arquivo nativo pela tag MEDIA, áudio ditado no caminho de casa

Aqui o mensageiro ganha porque ele NOTIFICA e porque você responde de dentro da própria entrega

Volte pro terminal quando a sessão for longa e contínua, com você sentado na máquina

A TUI imprime o comando de retomada ao sair e restaura o histórico completo a partir do SQLite, o que é o ambiente natural de quem está no meio de um trabalho pesado

Use o painel web quando o assunto for administrar, e não conversar

Chaves de API, gateway, memória, sessões, logs, cron jobs e skills: é tudo local, em http://127.0.0.1:9119

E o ponto mais importante do veredito: a escolha é POR TAREFA, não por lealdade a uma interface

Como o histórico e a memória são do agente e valem pros dois pontos de entrada, trocar de porta não te custa contexto

Conclusão

O mensageiro ganha do terminal em três coisas bem específicas: notificação (o agente te procura), mão dupla (você responde de dentro da entrega, se o job for continuable) e histórico da conversa como registro do que foi pedido, guardado em sessão e pesquisável pelo session_search

O terminal segue imbatível na sessão longa, e o painel web é o lugar de administrar

Se quiser sentir a diferença na prática antes de decidir onde o teu agente vai morar, o roteiro é curto: cria o bot no BotFather, roda o hermes gateway setup com o teu ID numérico na allowlist, dá /sethome no chat certo e monta um cron de briefing marcado como continuável

Aí é só esperar a primeira mensagem chegar sozinha e ver se você volta pro terminal ou não 😀

até o próximo post!