Pular para o conteúdo principal

Documentação oficial desta página · v0.20.6

Tutorial: assistente de time no Telegram

Montar um assistente de time no Telegram

Este tutorial mostra como montar um bot do Telegram movido pelo Hermes Agent que várias pessoas do time podem usar. No fim, o seu time vai ter um assistente de IA compartilhado, para quem mandar mensagem pedindo ajuda com código, pesquisa, administração de sistemas e o que mais aparecer — protegido por autorização por usuário.

O que vamos construir​

Um bot do Telegram que:

  • Qualquer pessoa autorizada do time pode chamar no privado — revisão de código, pesquisa, comandos de shell, depuração
  • Roda no seu servidor com acesso total às ferramentas — terminal, edição de arquivos, busca na web, execução de código
  • Sessões por usuário — cada pessoa tem o próprio contexto de conversa
  • Seguro por padrão — só usuários aprovados interagem, com dois métodos de autorização
  • Tarefas agendadas — reuniões diárias, verificações de saúde e lembretes entregues num canal do time

Pré-requisitos​

Antes de começar, confira se você tem:

  • O Hermes Agent instalado num servidor ou VPS (não no seu laptop — o bot precisa ficar rodando). Siga o guia de instalação se ainda não fez isso.
  • Uma conta do Telegram para você (o dono do bot)
  • Um provedor de LLM configurado — no mínimo, uma chave de API da OpenAI, da Anthropic ou de outro provedor suportado em ~/.hermes/.env
dica

Um VPS de US$ 5 por mês dá e sobra para rodar o gateway. O Hermes em si é leve — o que custa dinheiro são as chamadas de API do LLM, e elas acontecem remotamente.

Passo 1: crie um bot do Telegram​

Todo bot do Telegram começa no @BotFather — o bot oficial do Telegram para criar bots.

  1. Abra o Telegram e procure por @BotFather, ou vá em t.me/BotFather

  2. Mande /newbot — o BotFather vai pedir duas coisas:

    • Nome de exibição — o que os usuários veem (por exemplo, Team Hermes Assistant)
    • Nome de usuário — tem que terminar em bot (por exemplo, myteam_hermes_bot)

  3. Copie o token do bot — o BotFather responde com algo assim:

    Use this token to access the HTTP API:
    7123456789:AAH1bGciOiJSUzI1NiIsInR5cCI6Ikp...

    Guarde esse token — você vai precisar dele no próximo passo.

  4. Defina uma descrição (opcional, mas recomendado):

    /setdescription

    Escolha o seu bot e escreva algo como:

    Assistente de IA do time, movido pelo Hermes Agent. Me chame no privado para ajuda com código, pesquisa, depuração e mais.

  5. Defina os comandos do bot (opcional — dá aos usuários um menu de comandos):

    /setcommands

    Escolha o seu bot e cole:

    new - Começar uma conversa nova
    model - Mostrar ou trocar o modelo de IA
    status - Mostrar informações da sessão
    help - Mostrar os comandos disponíveis
    stop - Parar a tarefa atual
aviso

Mantenha o token do seu bot em segredo. Quem tiver o token controla o bot. Se ele vazar, use /revoke no BotFather para gerar um novo.

Passo 2: configure o gateway​

Você tem duas opções: o assistente interativo de configuração (recomendado) ou a configuração manual.

hermes gateway setup

Ele guia você por tudo, com seleção pelas setas do teclado. Escolha Telegram, cole o token do seu bot e digite o seu ID de usuário quando for pedido.

Opção B: configuração manual​

Acrescente estas linhas em ~/.hermes/.env:

# Token do bot do Telegram, obtido no BotFather
TELEGRAM_BOT_TOKEN=7123456789:AAH1bGciOiJSUzI1NiIsInR5cCI6Ikp...

# Seu ID de usuário do Telegram (numérico)
TELEGRAM_ALLOWED_USERS=123456789

Como descobrir o seu ID de usuário​

O seu ID de usuário do Telegram é um valor numérico (não é o seu nome de usuário). Para descobrir:

  1. Mande mensagem para o @userinfobot no Telegram
  2. Ele responde na hora com o seu ID numérico
  3. Copie esse número para TELEGRAM_ALLOWED_USERS
informação

IDs de usuário do Telegram são números permanentes, como 123456789. Eles são diferentes do seu @username, que pode mudar. Use sempre o ID numérico nas listas de permissão.

Passo 3: inicie o gateway​

Teste rápido​

Rode o gateway em primeiro plano primeiro, para conferir que tudo funciona:

hermes gateway

Você deve ver uma saída assim:

[Gateway] Starting Hermes Gateway...
[Gateway] Telegram adapter connected
[Gateway] Cron scheduler started (tick every 60s)

Abra o Telegram, encontre o seu bot e mande uma mensagem. Se ele responder, está tudo certo. Aperte Ctrl+C para parar.

Produção: instale como serviço​

Para uma implantação persistente, que sobrevive a reinicializações:

hermes gateway install
sudo hermes gateway install --system   # só no Linux: serviço de sistema, na inicialização

Isso cria um serviço em segundo plano: por padrão um serviço systemd de nível de usuário no Linux, um serviço launchd no macOS, ou um serviço de sistema do Linux na inicialização, se você passar --system.

# Linux — gerencie o serviço de usuário padrão
hermes gateway start
hermes gateway stop
hermes gateway status

# Ver os logs ao vivo
journalctl --user -u hermes-gateway -f

# Manter rodando depois de sair do SSH
sudo loginctl enable-linger $USER

# Servidores Linux — comandos explícitos de serviço de sistema
sudo hermes gateway start --system
sudo hermes gateway status --system
journalctl -u hermes-gateway -f
# macOS — gerencie o serviço
hermes gateway start
hermes gateway stop
tail -f ~/.hermes/logs/gateway.log
PATH no macOS

O plist do launchd captura o PATH do seu shell na hora da instalação, para que os subprocessos do gateway consigam encontrar ferramentas como Node.js e ffmpeg. Se você instalar ferramentas novas depois, rode hermes gateway install de novo para atualizar o plist.

Confirme que está rodando​

hermes gateway status

Depois mande uma mensagem de teste para o seu bot no Telegram. Você deve receber uma resposta em poucos segundos.

Passo 4: dê acesso ao time​

Agora vamos liberar acesso para os seus colegas. Existem duas abordagens.

Abordagem A: lista de permissão estática​

Junte o ID de usuário do Telegram de cada pessoa do time (peça para mandarem mensagem ao @userinfobot) e adicione todos em uma lista separada por vírgulas:

# Em ~/.hermes/.env
TELEGRAM_ALLOWED_USERS=123456789,987654321,555555555

Reinicie o gateway depois de mudar:

hermes gateway stop && hermes gateway start

O pareamento por DM é mais flexível — você não precisa juntar os IDs de usuário antes. Funciona assim:

  1. A pessoa manda mensagem privada ao bot — como ela não está na lista de permissão, o bot responde com um código de pareamento de uso único:

    🔐 Pairing code: XKGH5N7P
    Send this code to the bot owner for approval.

  2. A pessoa te manda o código (por qualquer canal — Slack, e-mail, pessoalmente)

  3. Você aprova no servidor:

    hermes pairing approve telegram XKGH5N7P

  4. Pronto — o bot passa a responder às mensagens dela na hora

Gerenciar usuários pareados:

# Ver todos os usuários pendentes e aprovados
hermes pairing list

# Revogar o acesso de alguém
hermes pairing revoke telegram 987654321

# Limpar códigos pendentes expirados
hermes pairing clear-pending
dica

O pareamento por DM é ideal para times porque você não precisa reiniciar o gateway ao acrescentar usuários novos. As aprovações valem na hora.

Considerações de segurança​

  • Nunca defina GATEWAY_ALLOW_ALL_USERS=true num bot com acesso ao terminal — qualquer pessoa que achar o seu bot poderia rodar comandos no seu servidor
  • Os códigos de pareamento expiram em 1 hora e usam aleatoriedade criptográfica
  • A limitação de taxa impede ataques de força bruta: 1 requisição por usuário a cada 10 minutos, no máximo 3 códigos pendentes por plataforma
  • Depois de 5 tentativas de aprovação falhas, a plataforma entra em bloqueio de 1 hora
  • Todos os dados de pareamento são guardados com permissão chmod 0600

Passo 5: configure o bot​

Defina um canal padrão​

Um canal padrão é onde o bot entrega os resultados das tarefas de cron e as mensagens proativas. Sem um, as tarefas agendadas não têm para onde mandar a saída.

Opção 1: use o comando /sethome em qualquer grupo ou conversa do Telegram em que o bot esteja.

Opção 2: defina na mão em ~/.hermes/.env:

TELEGRAM_HOME_CHANNEL=-1001234567890
TELEGRAM_HOME_CHANNEL_NAME="Novidades do Time"

Para descobrir o ID de um canal, adicione o @userinfobot ao grupo — ele informa o ID de chat do grupo.

Configure a exibição do progresso das ferramentas​

Controle quanto detalhe o bot mostra ao usar ferramentas. Em ~/.hermes/config.yaml:

display:
  tool_progress: new    # off | new | all | verbose
ModoO que você vê
offSó as respostas limpas — nenhuma atividade de ferramenta
newStatus curto de cada nova chamada de ferramenta (recomendado para mensageria)
allCada chamada de ferramenta, com detalhes
verboseSaída completa da ferramenta, inclusive os resultados dos comandos

Os usuários também podem mudar isso por sessão, com o comando /verbose no chat.

Monte uma personalidade com o SOUL.md​

Personalize o jeito de o bot se comunicar editando ~/.hermes/SOUL.md:

Para um guia completo, veja Usar o SOUL.md com o Hermes.

# Soul
Você é um assistente de time prestativo. Seja conciso e técnico.
Use blocos de código para qualquer código. Pule as formalidades — o time
valoriza objetividade. Ao depurar, sempre peça os logs de erro
antes de chutar soluções.

Acrescente contexto do projeto​

Se o seu time trabalha em projetos específicos, crie arquivos de contexto para o bot conhecer a sua pilha:

<!-- ~/.hermes/AGENTS.md -->
# Contexto do Time
- Usamos Python 3.12 com FastAPI e SQLAlchemy
- O frontend é React com TypeScript
- CI/CD roda no GitHub Actions
- Produção implanta no AWS ECS
- Sempre sugira escrever testes para código novo
informação

Arquivos de contexto são injetados no prompt de sistema de toda sessão. Mantenha-os concisos — cada caractere conta no seu orçamento de tokens.

Passo 6: monte tarefas agendadas​

Com o gateway rodando, você pode agendar tarefas recorrentes que entregam os resultados no canal do time.

Resumo diário da reunião​

Mande esta mensagem ao bot no Telegram:

Todo dia útil às 9h, verifique o repositório do GitHub em
github.com/myorg/myproject para:
1. Pull requests abertos/mesclados nas últimas 24 horas
2. Issues criadas ou fechadas
3. Qualquer falha de CI/CD na branch main
Formate como um resumo curto, estilo reunião diária.

O agente cria uma tarefa de cron automaticamente e entrega os resultados no chat onde você pediu (ou no canal padrão).

Verificação de saúde do servidor​

A cada 6 horas, verifique o uso de disco com 'df -h', a memória com 'free -h'
e o status dos contêineres Docker com 'docker ps'. Relate qualquer coisa fora do normal —
partições acima de 80%, contêineres que reiniciaram, ou uso alto de memória.

Gerenciar tarefas agendadas​

# Pela CLI
hermes cron list          # Ver todas as tarefas agendadas
hermes cron status        # Verificar se o agendador está rodando

# Pelo chat do Telegram
/cron list                # Ver as tarefas
/cron remove <job_id>     # Remover uma tarefa
aviso

Os prompts das tarefas de cron rodam em sessões totalmente novas, sem memória das conversas anteriores. Garanta que cada prompt tenha todo o contexto de que o agente precisa — caminhos de arquivo, URLs, endereços de servidor e instruções claras.

Dicas de produção​

Use Docker por segurança​

Num bot compartilhado do time, use o Docker como backend de terminal, para os comandos do agente rodarem num contêiner em vez de rodarem na sua máquina hospedeira:

# Em ~/.hermes/.env
TERMINAL_ENV=docker
TERMINAL_DOCKER_IMAGE=nikolaik/python-nodejs:python3.11-nodejs20

Ou em ~/.hermes/config.yaml:

terminal:
  backend: docker
  container_cpu: 1
  container_memory: 5120
  container_persistent: true

Assim, mesmo que alguém peça ao bot para rodar algo destrutivo, o seu sistema hospedeiro fica protegido.

Monitore o gateway​

# Verificar se o gateway está rodando
hermes gateway status

# Acompanhar os logs ao vivo (Linux)
journalctl --user -u hermes-gateway -f

# Acompanhar os logs ao vivo (macOS)
tail -f ~/.hermes/logs/gateway.log

Mantenha o Hermes atualizado​

Pelo Telegram, mande /update ao bot — ele baixa a versão mais nova e reinicia. Ou, pelo servidor:

hermes update
hermes gateway stop && hermes gateway start

Onde ficam os logs​

O quêLocal
Logs do gatewayjournalctl --user -u hermes-gateway (Linux) ou ~/.hermes/logs/gateway.log (macOS)
Saída das tarefas de cron~/.hermes/cron/output/{job_id}/{timestamp}.md
Definições das tarefas de cron~/.hermes/cron/jobs.json
Dados de pareamento~/.hermes/pairing/
Histórico de sessões~/.hermes/sessions/

Ir além​

Você já tem um assistente de time no Telegram funcionando. Aqui vão alguns próximos passos:

  • Guia de segurança — mergulho fundo em autorização, isolamento por contêiner e aprovação de comandos
  • Gateway de mensagens — referência completa da arquitetura do gateway, gerenciamento de sessões e comandos de chat
  • Configuração do Telegram — detalhes específicos da plataforma, inclusive mensagens de voz e TTS
  • Tarefas agendadas — agendamento avançado com cron, opções de entrega e expressões cron
  • Arquivos de contexto — AGENTS.md, SOUL.md e .cursorrules para conhecimento do projeto
  • Personalidade — predefinições de personalidade embutidas e definições de persona personalizadas
  • Adicione mais plataformas — o mesmo gateway roda Discord, Slack e WhatsApp ao mesmo tempo

Dúvidas ou problemas? Abra uma issue no GitHub — contribuições são bem-vindas.