Configuração do Hermes Agent no Telegram: Problemas Comuns e Como Resolver

O Telegram É Onde a Maioria dos Deploys do Hermes Trava

O quickstart do Hermes é rápido. A configuração do Telegram é onde a maioria dos usuários encontra problemas. Não é que o processo seja complicado, é que cada etapa tem algumas formas de dar errado, e quando várias coisas falham silenciosamente, fica difícil saber onde procurar.

Este guia cobre os problemas mais comuns na ordem em que normalmente aparecem.

Obtendo o Token de Bot do Telegram

O token vem do BotFather, a interface oficial de gerenciamento de bots do Telegram. Essa etapa parece simples, mas tem algumas formas de dar errado.

Como fazer certo:

1. Abra o Telegram e pesquise por @BotFather.
2. Envie /newbot.
3. O BotFather pede um nome (nome de exibição) e um username (deve terminar em bot).
4. Após a criação, o BotFather envia uma mensagem com o token. Parece com 7123456789:ABCDef....
5. Copie o token completo, incluindo os dois pontos e tudo que vem depois.

Erros comuns:

• Copiar apenas o ID numérico: o token é a string completa após os dois pontos, não só o número antes deles.
• Usar um bot de teste de um ambiente de desenvolvimento: se você criou um bot há meses e esqueceu qual token vai com qual bot, o BotFather pode mostrar os bots existentes com /mybots. Você pode então revogar e regenerar os tokens.
• Espaços ou quebras de linha no token colado: alguns fluxos de cópia adicionam espaço em branco. Cole em um editor de texto simples primeiro para verificar que o token está limpo antes de usá-lo.

A Configuração TELEGRAM_ALLOWED_USERS

Essa é a parte mais comumente mal configurada de um deploy Hermes no Telegram.

O Hermes exige que você especifique quais IDs de usuário do Telegram têm permissão para enviar mensagens ao bot. Sem isso, o bot não vai responder a ninguém. Com um valor incorreto, o bot não vai responder a você mesmo que aparente estar rodando.

O que você precisa:

Um ID de usuário do Telegram é um número, não um username. @username não é o que o Hermes quer. Você precisa do ID numérico, que parece com 123456789.

Como obter seu ID de usuário do Telegram:

Abra o Telegram, pesquise por @userinfobot e envie /start. Ele vai responder com seu ID de usuário.

Como configurar:

No config.yaml:

telegram_allowed_users: "123456789"

Para múltiplos usuários, use uma lista separada por vírgulas:

telegram_allowed_users: "123456789,987654321"

Nota Hermify: no fluxo de onboarding da Hermify, você insere seu ID de usuário do Telegram (ou uma lista separada por vírgulas) no formulário de credenciais. Esse campo é separado do campo de token do bot. Ambos são obrigatórios.

Problema: O Bot Não Responde de Jeito Nenhum

Se você manda uma mensagem para seu bot e nada acontece, percorra este checklist:

1. O gateway do Hermes está rodando?

hermes gateway status

Se o gateway não estiver rodando, o bot não tem listener. Inicie-o:

hermes gateway start

2. Seu ID de usuário está na lista de permitidos?

Verifique novamente o telegram_allowed_users na config. Essa é a causa mais comum de bot silencioso. O processo está rodando, o gateway está conectado, mas o Hermes está deliberadamente ignorando suas mensagens porque seu ID não está na lista.

3. O token do bot expirou ou foi revogado?

O BotFather permite revogar tokens. Se você regenerou o token depois de adicioná-lo ao Hermes, o token antigo não funciona mais. Verifique no BotFather com /mybots, selecione seu bot, vá em API Token e confirme que o token na sua config corresponde.

4. O bot já está em outro chat?

Os bots do Telegram respondem ao chat específico em que recebem mensagens. Se você adicionou o bot a um grupo anteriormente e o Hermes está configurado para responder a mensagens de grupo de forma diferente, talvez precise iniciar a conversa em um chat direto (DM) com o bot.

Problema: Erro "Unauthorized" nos Logs

Esse erro significa que o token é inválido ou foi revogado. A correção é sempre regenerar o token no BotFather e atualizar sua configuração do Hermes com o novo valor.

No BotFather:

1. Envie /mybots.
2. Selecione seu bot.
3. Vá em API Token → Revoke current token.
4. Copie o novo token.
5. Atualize o config.yaml ou o formulário de credenciais do dashboard da Hermify.
6. Reinicie o Hermes (ou o runtime da Hermify).

Problema: Bot Responde Uma Vez e Para

Isso geralmente significa que o processo do Hermes parou ou o gateway se desconectou. Causas comuns:

O processo foi encerrado. Em deploys locais ou hospedagem compartilhada barata, os processos são encerrados quando a memória está apertada ou quando o host recicla containers. Verifique seus logs de processo por um crash ou evento de OOM (out of memory).

A sessão WSL2 encerrou. Se você está rodando o Hermes dentro do WSL2, fechar o terminal para o processo. Veja o guia de WSL2 para rodar o Hermes de forma persistente.

O loop de polling do Telegram expirou. O gateway do Hermes usa long-polling para receber mensagens do Telegram. Ocasionalmente a conexão cai e não é restabelecida automaticamente. Reiniciar o gateway (hermes gateway restart) resolve isso.

Um erro de modelo causou um crash. Se a API do LLM retornou um erro (limite de taxa, cota esgotada, resposta ruim), algumas versões do Hermes podem encerrar a sessão em vez de se recuperar. Verifique a saída do terminal ou os logs por uma mensagem de erro recente antes do silêncio começar.

Problema: Mensagens Chegam Mas o Agente Ignora o Conteúdo

Isso é diferente de um bot silencioso. O bot está recebendo mensagens, mas as respostas do agente parecem erradas ou vazias.

Causa mais provável: a janela de contexto do modelo está cheia. O Hermes lê seu MEMORY.md e o histórico de conversa em cada prompt. Se o contexto combinado for muito longo para a janela do modelo, o modelo recebe um prompt truncado e a qualidade da resposta degrada ou fica vazia.

Soluções:

• Mude para um modelo com janela de contexto maior (Claude e Gemini suportam 128k+).
• Reduza manualmente seu MEMORY.md se ele cresceu muito.
• Use hermes memory compact se disponível na sua versão para resumir e compactar a memória.

Causa menos provável: problema de correspondência parcial na lista de usuários permitidos. Se sua config de usuários permitidos contém 12345 e seu ID de usuário real é 123456789, o Hermes não vai corresponder corretamente. Verifique o ID numérico completo, não uma versão truncada.

Problema: Funciona Bem Localmente, Quebrado Após o Deploy

A causa mais comum aqui é uma incompatibilidade entre o ambiente que você testou e o ambiente do servidor.

Verifique essas coisas em ordem:

1. O token está correto na config do servidor, não na config local. É fácil atualizar o arquivo errado.
2. O servidor consegue alcançar a API do Telegram. Alguns provedores de hospedagem bloqueiam conexões de saída. Teste com curl https://api.telegram.org/bot<SEU_TOKEN>/getMe a partir do servidor.
3. O processo do Hermes iniciou com sucesso. Verifique os logs do container ou do processo por erros de inicialização.
4. O diretório de memória está montado. Se você estiver usando Docker, confirme que o volume de dados está anexado. Um agente que inicia sem seu diretório de dados vai se comportar de forma estranha.

Pulando Tudo Isso com Hospedagem Gerenciada

O motivo pelo qual a maioria das pessoas enfrenta problemas de configuração do Telegram é que está gerenciando o deploy por conta própria, lidando com tokens, arquivos de configuração, processos e ambientes de servidor simultaneamente.

A Hermify foi projetada especificamente para resolver esse problema. O fluxo de onboarding cuida da configuração do Telegram: você fornece o token do bot e os IDs de usuários permitidos uma vez, e a plataforma os armazena criptografados, os injeta no runtime e gerencia o processo do gateway.

Se o bot parar de responder na Hermify, você não debugga o gateway, você verifica o card de status no dashboard e dispara um restart se necessário. O loop operacional é baseado no dashboard, não em SSH.

Essa é a principal mudança que a hospedagem gerenciada do Telegram traz: não a configuração do Telegram em si, mas quem é responsável por mantê-la saudável. Você pode comparar essa abordagem diretamente com um setup de VPS auto-gerenciado na comparação de hospedagem vs auto-hospedagem.