Como Fazer o Deploy do Hermes Agent no Telegram

Por Que o Telegram É a Melhor Interface para o Hermes

A maioria das ferramentas de IA vive numa aba do navegador. Você vai até elas, digita algo, lê a resposta e fecha a aba. No momento em que fecha, o contexto vai embora.

O Telegram muda isso completamente. Se o Hermes roda como um bot no Telegram, você interage com seu agente pelo celular, de qualquer dispositivo, a qualquer hora, sem abrir um navegador ou lembrar de uma URL. As mensagens chegam como qualquer outra conversa. O agente responde com seu contexto persistente completo intacto.

É isso que significa "agente de IA sempre ativo" na prática: não um processo em background que você verifica quando lembra que existe, mas um contato no seu app de mensagens que fica pronto e lembra de tudo.

O Que Um Deploy Real no Telegram Exige

Colocar o Hermes no Telegram envolve mais do que um único comando. Um deploy real tem cinco partes distintas:

1. Criar o bot no BotFather

Abra o Telegram e pesquise por @BotFather. Envie /newbot, escolha um nome de exibição e um username terminando em bot, e copie o token da API que ele retornar. Esse token tem a aparência de 7123456789:ABCDef.... Guarde a string completa.

2. Escolher um provedor de modelos

O Hermes precisa de um LLM para gerar as respostas. OpenRouter é a escolha mais simples: uma API key dá acesso a Claude, GPT-4, Llama e outros sem gerenciar contas separadas. O guia de configuração do OpenRouter cobre isso em detalhes.

3. Configurar o runtime

No config.yaml, conecte sua chave de provedor, escolha o modelo e defina as configurações do Telegram:

provider: openrouter
model: anthropic/claude-3-5-sonnet
openrouter_api_key: sk-or-sua-chave-aqui
telegram_bot_token: 7123456789:ABCDef...
telegram_allowed_users: "SEU_ID_NUMERICO_DO_TELEGRAM"

O campo telegram_allowed_users é crítico. O Hermes só responde aos IDs de usuário do Telegram listados aqui. Obtenha seu ID numérico pelo @userinfobot no Telegram. Usernames não são aceitos.

4. Iniciar o gateway de mensagens

hermes gateway start --detach

O gateway roda como um processo em background que faz long-polling na API do Telegram e roteia as mensagens para o runtime do Hermes. Sem ele, seu bot aceita mensagens mas nunca responde.

5. Mantê-lo no ar

É aqui que a maioria dos deploys auto-gerenciados eventualmente trava. O bot funciona enquanto o processo está rodando, e para de funcionar quando o processo para. No laptop rodando WSL2, o processo morre quando o terminal é fechado. Num VPS barato, pode ser encerrado durante um ciclo de container. Um deploy em produção de verdade exige um servidor persistente com gerenciamento de processos (systemd, Docker com política de restart, ou hospedagem gerenciada).

Os Modos de Falha Mais Comuns

Bot silencioso: o bot está registrado no Telegram, mas não responde quando você manda mensagem. O gateway não está rodando (hermes gateway status) ou seu ID de usuário não está em telegram_allowed_users.

Erro "Unauthorized" nos logs: seu token de bot foi revogado ou está incorreto. Regenere-o pelo BotFather (/mybots → selecione o bot → API Token → Revoke) e atualize sua configuração.

Funciona uma vez e para: o processo do Hermes travou ou o gateway se desconectou. Verifique os logs para ver se há um erro antes do silêncio começar. Um erro de API de modelo (limite de taxa, cota esgotada) pode fazer a sessão encerrar em vez de se recuperar.

Funciona localmente, quebrado após o deploy: a causa mais comum é que a configuração no servidor é diferente da configuração local, especificamente o token ou a lista de usuários permitidos. Verifique o config.yaml do servidor diretamente, não o local.

O guia de troubleshooting do Telegram cobre cada um desses casos com detalhes completos e passos exatos para resolução.

O Custo de Tempo Que Ninguém Contabiliza

O comando de instalação leva cinco minutos. O caminho operacional é o que realmente custa tempo.

Quando o Hermes está rodando no Telegram com sucesso, é genuinamente útil. O problema é o tempo entre "quero isso" e "está rodando de forma confiável":

Configurar o VPS ou o ambiente de servidor
Armazenar as credenciais com segurança
Debugar na primeira vez que o gateway para de responder
Lidar com o restart do processo após uma atualização do sistema
Monitorar o uptime para perceber quando o bot fica silencioso

Nenhuma dessas etapas é difícil isoladamente. Juntas, representam uma responsabilidade operacional contínua. Se seu objetivo é usar o Hermes e não manter a infraestrutura ao redor dele, aqui está o ponto de fricção.

O Caminho Gerenciado: Hermify

A Hermify foi projetada especificamente para resolver o problema do deploy no Telegram. Em vez de montar o ambiente de servidor você mesmo, você:

Cria uma conta e escolhe um plano
Insere seu token de bot do Telegram e os IDs de usuários permitidos no formulário de onboarding
Adiciona sua chave de provedor de modelos (ou usa um plano com acesso a modelos incluído)
Clica em deploy

O runtime é provisionado em um servidor persistente, o gateway inicia automaticamente, e o bot fica ativo no Telegram. O dashboard mostra o status do runtime, permite atualizar credenciais e disparar restarts sem acesso via SSH.

Quando o bot fica silencioso em um deploy auto-gerenciado, você debugga o gateway. Quando fica silencioso na Hermify, você verifica o card de status e reinicia pelo dashboard.

Essa é a diferença prática: não se o deploy no Telegram é possível (claramente é), mas quem é responsável por mantê-lo saudável depois que está no ar.

Escolhendo Entre Auto-Hospedagem e Hospedagem Gerenciada

Os dois caminhos funcionam. A escolha depende do que você quer gerenciar:

Auto-hospede se: você se sente confortável com administração de servidores Linux, já opera esse tipo de infraestrutura e quer controle total sobre o ambiente, o armazenamento e a configuração.

Use hospedagem gerenciada se: você quer o Hermes disponível no Telegram de forma confiável, não quer gerenciar um servidor e está principalmente interessado em usar o agente, não em manter a stack ao redor dele.

A comparação entre hospedagem e auto-hospedagem aprofunda essa decisão, incluindo detalhamento de custos e expectativas de manutenção após o primeiro deploy.

Se você está pronto para começar, a página de deploy do Hermes Agent guia pelo setup gerenciado completo, da criação de conta até a primeira mensagem.