Hermes Agent no Telegram: controle seus agentes por nota de voz

Um board é onde você decide. Um chat é onde você opera. Rode os dois através do mesmo agente e o que nunca dorme vai engolir o que deveria pensar, a menos que você mantenha os dois como superfícies diferentes de propósito.

Eu rodo o gateway de Telegram do Hermes Agent como meu assistente pessoal. Falo com ele por voz, geralmente longe de um teclado, e ele abre issues no meu próprio board do Paperclip sem eu abrir o app web. Isto é do que esse gateway é realmente feito, verificado contra o código-fonte, e a regra pela qual eu rodo ele: o chat é onde você opera, não onde você decide.

Hermes Agent no Telegram: o que o gateway realmente faz

A integração do Hermes Agent com o Telegram é um dos 22 plugins de plataforma, construído sobre o python-telegram-bot, que transforma um chat do Telegram numa superfície para o mesmo agente que já roda o seu shell, a sua memória e as suas ferramentas MCP. Você cria o bot através do @BotFather, cola o token no ~/.hermes/.env como TELEGRAM_BOT_TOKEN, e o gateway conecta por long polling (o padrão, saindo do seu servidor) ou por webhook (entrando, para plataformas cloud que precisam dormir entre mensagens e despertar automaticamente com tráfego).

Nada aqui é encanamento exclusivo do Telegram parafusado num chatbot. O gateway é o mesmo processo que conversa com mais de 25 plataformas de mensagem, e o Telegram recebe o conjunto completo de features: threads e forum topics, edições de mensagem em streaming, mídia nativa, teclados inline, slash commands e um transporte de rede de fallback para quando a conexão principal não está saudável.

O que o Telegram toca num profile do Hermes

• ~/.hermes/// HERMES_HOME
  • .envsegredo// TELEGRAM_BOT_TOKEN, TELEGRAM_ALLOWED_USERS
  • config.yaml
    • platforms.telegram.extra// mentions, threads, proxy, status
    • stt// notas de voz chegando
    • tts// bolhas de voz saindo
    • mcp_servers// o board, conectado como client
  • pairing/// chmod 0600, uma linha por usuário aprovado

Pairing, allowlists e a sessão compartilhada de grupo

Só duas coisas decidem quem o bot responde: um ID numérico de usuário do Telegram na allowlist, ou um código de pairing que você aprovou. TELEGRAM_ALLOWED_USERS é uma lista estática de IDs separada por vírgula, lida na inicialização. O caminho mais útil para qualquer pessoa que não seja você é o pairing por DM: um remetente não aprovado recebe um código de uso único de volta, repassa ele para você por qualquer canal, e você roda hermes pairing approve telegram <code> sem reiniciar o gateway. Códigos expiram depois de uma hora, uma plataforma aceita no máximo três códigos pendentes por vez, cinco tentativas de aprovação falhas disparam um lockout de uma hora, e os registros de pairing em disco são chmod 0600. TELEGRAM_ALLOW_ALL_USERS existe e é documentado como só para dev, porque o bot tem acesso a shell.

Grupos adicionam uma camada que quase todo mundo erra uma vez: o modo de privacidade do Telegram vem ligado por padrão, então um bot num grupo só vê slash commands, respostas às próprias mensagens e eventos de serviço, nunca a conversa normal, até você desligar a privacidade no BotFather e remover e readicionar o bot (o Telegram guarda em cache a configuração antiga nas memberships existentes). Com telegram.require_mention: true, o Hermes só responde a um /comando, uma resposta, uma @menção ou um padrão configurado de wake-word. Adicione observe_unmentioned_group_messages: true em cima de um chat na allowlist e o bot acompanha sem responder: linhas sem menção são anexadas à transcrição compartilhada da sessão do chat ou tópico como contexto, cada uma marcada com nome e ID do remetente e carregando sua própria instrução por turno que diz ao modelo que essas linhas são contexto, não comandos. Uma menção posterior traz toda essa transcrição para dentro. Isso é a coisa mais parecida com uma sessão de grupo que o Hermes tem: uma transcrição por chat ou tópico, compartilhada por quem estiver na allowlist dele.

Aprovando um comando arriscado direto do chat

Quando o Hermes quer rodar um comando marcado como arriscado, ele posta um card com teclado inline no mesmo chat, com quatro botões: aprovar uma vez, aprovar para a sessão, sempre permitir, ou negar. O cabeçalho do card é literal: “Hermes wants to run a command that needs your OK”, com uma linha abaixo dizendo por que foi marcado. Silêncio é um não seguro: o timeout padrão de aprovação é 300 segundos, e o card avisa isso antes de expirar. Esse card é renderizado do mesmo jeito em toda superfície de mensagem, Telegram incluso, através de um módulo compartilhado, então o texto nunca diverge entre plataformas.

Essa é a parte de “operar pelo chat” que realmente importa. Um feed de notificação te diz o que aconteceu. Um card de aprovação deixa você decidir se vai acontecer, no mesmo thread em que você já estava, sem trocar para um terminal.

Notas de voz: transcrição automática sem saída do chat

Uma nota de voz que você envia no Telegram é transcrita automaticamente pelo provedor de speech-to-text que você configurou, e então injetada na conversa como texto. stt é uma seção de nível superior no config.yaml, não uma configuração específica do Telegram, então o mesmo provedor também cuida das suas notas de voz no Discord, Signal ou WhatsApp:

stt:
  enabled: true
  provider: "local" # "local" (free) | "groq" | "openai" | "mistral" | "xai"

tts:
  provider: "edge" # "edge" (free) | "elevenlabs" | "openai" | ...

Três deles vale a pena conhecer pelo nome: local roda o faster-whisper na máquina que hospeda o Hermes e não precisa de API key, groq chama o Groq Whisper e lê GROQ_API_KEY, openai chama o OpenAI Whisper e lê VOICE_TOOLS_OPENAI_KEY. Definir stt.enabled: false pula a transcrição completamente: o gateway ainda guarda o arquivo de áudio em cache e entrega ao agente o caminho dele em vez disso, útil se você quer um pipeline customizado (diarização, um modelo diferente) em vez do próprio do Hermes.

As respostas voltam do mesmo jeito. A saída de TTS é entregue como uma bolha de voz nativa do Telegram, aquela redonda e tocável inline, quando o provedor é OpenAI ou ElevenLabs (os dois produzem Opus direto). O Edge TTS, o default gratuito, gera MP3 e precisa de ffmpeg no host para converter para Opus e virar a bolha; sem ffmpeg ainda envia, só que como um arquivo de áudio normal.

O bot token é um segredo. Trate ele como um

TELEGRAM_BOT_TOKEN é marcado como password: true no próprio manifesto do plugin, e por um motivo que vai além de convenção: quem tiver ele consegue ler toda mensagem que o seu bot vê e enviar mensagens como se fosse ele. O Hermes vem com um caminho dedicado de mascaramento para essa string exata, embutido em agent/redact.py, que remove o token de qualquer URL api.telegram.org/bot<TOKEN>/... antes dela chegar numa linha de log.

Esse mascaramento tinha brechas, e os próprios testes de regressão do projeto documentam elas: quatro pontos de chamada no adaptador do Telegram construíam o texto de erro direto a partir da exceção crua em vez da versão mascarada, e o pior dos quatro persistia a URL sem mascarar num arquivo de status voltado ao dashboard, não só num log. Uma correção fechou os quatro. Eu trago isso porque eu mesmo já bati na versão geral desse bug: um dump do config.yaml dentro de uma sessão do Hermes uma vez escreveu meus tokens de API direto no log da sessão, e eu rotacionei eles. Código de mascaramento é uma mitigação, não uma garantia. Se um token pode ser impresso, assuma que ele eventualmente vai ser, e mantenha cada um deles a um /revoke de distância de estar morto.

Como eu rodo isso: o board decide, o chat opera

Três camadas, um harness

1. 1

   Paperclip

   O board. Trabalho estratégico e tático: heads rodam os próprios ciclos, especialistas entregam contra uma barra de aceitação, heads julgam o que volta, e eu decido no gate. Isso é onde eu decido.

   +
2. 2

   Telegram

   O chat. Trabalho operacional: faz isso agora, aprova esse comando, transcreve essa nota de voz. Isso é onde eu opero, na maior parte longe de um teclado.

   +
3. 3

   Hermes

   A memória. Mesmo harness, mesmos modelos, mesmos servidores MCP, mesmas skills, consultada pelas duas camadas acima dela.

O board é onde eu decido. O chat é onde eu opero. A memória do agente é o que as duas camadas leem.

O board do Paperclip está conectado ao meu Hermes voltado para o Telegram como um servidor MCP, o @paperclipai/mcp-server oficial, que expõe quarenta e uma ferramentas sobre a API do board. Ele fica no mesmo bloco mcp_servers do config.yaml que o Hermes usa para qualquer outro servidor MCP, com a URL do Paperclip e uma API key passadas no ambiente dele.

Fale uma linha do tipo “escreve um roteiro cobrindo o tema X” no Telegram, por voz ou por texto, e essa frase se transforma numa issue do Paperclip, através de uma dessas quarenta e uma ferramentas. Não é o Hermes fazendo o trabalho. É o Hermes arquivando o trabalho onde a minha empresa de agentes vai pegar na própria agenda dela. Operar e decidir ficam em dois lugares diferentes, de propósito.

Antes de construir desse jeito, eu explorei um design diferente: um cron job dentro do Paperclip que leria periodicamente as próprias exportações de sessão do Hermes e dobraria elas na memória do Paperclip, uma projeção de read-model em vez de uma bridge ao vivo. Ficou só na exploração. Eu nunca construí. O que foi lançado foi mais simples e baseado em push: o Telegram fala direto com o board, através de um servidor MCP, no momento em que eu peço.

No meu trabalho, um Hermes separado roda num cron job em vez de num chat: um briefing diário que lê as fontes MCP da empresa e escreve para mim, sem superfície de chat nenhuma. O chat não é o único jeito de operar um agente. É o jeito que deixa você interromper ele.

Hermes Agent vs OpenClaw no Telegram

No Telegram especificamente, Hermes Agent e OpenClaw vêm os dois como canal first-party com profundidade de features de verdade, mas eles discordam sobre quem começa a conversa. O Hermes só fala no Telegram quando você manda mensagem para ele ou um cron job dispara. O heartbeat do OpenClaw desperta o agente num timer, por padrão a cada 30 minutos (uma hora com OAuth da Anthropic), e deixa ele decidir se algo vale uma mensagem para você, sem ser provocado.

Onde os dois diferem num setup chat-first

Os dois rodam Telegram bem. A diferença real é quem começa a conversa.

	Hermes Agent	OpenClaw
Por trás	Nous Research, um laboratório de modelos	OpenClaw Foundation, uma 501(c)(3)
Desperta por conta própria	Só cron jobs, sem heartbeat ambiente	Heartbeat a cada 30 minutos por padrão
Custo do despertar ambiente	Nenhum: nada dispara sem um trigger	Cerca de 100k tokens por beat, 2k a 5k com isolatedSession
Memória na superfície de chat	MEMORY.md, USER.md, busca full-text de sessão	MEMORY.md, USER.md, notas diárias, consolidação dreaming

Se você quer que o bot comece a conversa por conta própria, o heartbeat do OpenClaw faz isso nativamente, a um custo de tokens que você ajusta com isolatedSession. Se um orquestrador ou um cron job já é o seu heartbeat, como é o meu, essa feature é overhead puro. A comparação mais longa, lida direto dos dois códigos-fonte, está em Hermes Agent vs OpenClaw.

Hermes Agent no iMessage: mesmo gateway, bridge diferente

O Hermes Agent alcança o iMessage através do BlueBubbles, um servidor macOS separado e open source que faz a ponte entre iMessage e qualquer dispositivo. É o mesmo agente, a mesma memória, os mesmos cards de aprovação, atrás de uma bridge diferente com um requisito rígido que o Telegram não tem: um Mac sempre ligado, logado no Messages.app, rodando o BlueBubbles Server. Você aponta o Hermes para ele com uma URL de servidor e uma senha, do mesmo jeito que você aponta para um bot token do Telegram, e o gateway trata isso como mais um adaptador de plataforma.

Se a sua superfície de operação precisa ser um número de telefone que a sua família já usa para mandar mensagem, esse é o motivo honesto para aceitar a dependência do Mac. Se não precisa, o Telegram só pede um bot gratuito e uma VPS, nada mais.

Hermes Agent no WhatsApp: a bridge que pode banir sua conta

Para quem está lendo do Brasil, o WhatsApp é o app de chat padrão, não o Telegram, então essa seção provavelmente importa mais do que a anterior. A integração padrão do Hermes Agent com o WhatsApp é o Baileys, uma bridge não oficial que emula uma sessão do WhatsApp Web. Sem conta de desenvolvedor da Meta, sem verificação de empresa, e um risco real (ainda que pequeno) de o WhatsApp marcar o número. O Hermes documenta dois modos: um número de bot dedicado (risco menor, mais limpo para múltiplos usuários) ou o seu próprio número num self-chat (mais rápido de configurar, pior para qualquer coisa além de teste). Para quem roda isso como mais que um experimento pessoal, o Hermes também traz o caminho oficial, a WhatsApp Business Cloud API, que troca a velocidade de configuração por uma conta Meta Business, um webhook público, e nenhum risco de ban.

O Telegram não tem uma divisão equivalente. Tem um bot, um token, uma API oficial, o que é parte do motivo de ser a superfície que eu rodo. Se o seu time já vive no WhatsApp, pesa o risco de ban contra a conveniência antes de decidir.

Antes do Telegram se tornar sua superfície de operação

• ✓Obrigatório:
  Você tem um board em outro lugar que já decide.Telegram é para operar, não para planejar. Se você só tem um chat, você tem uma lista de tarefas com passos extras.
• ✓Obrigatório:
  Você está numa allowlist ou em pairing por DM, não em TELEGRAM_ALLOW_ALL_USERS.Um bot com acesso a shell e sem allowlist é um terminal público com um nome simpático.
• ✓Obrigatório:
  Você já leu as quatro opções do card de aprovação antes de precisar delas.Uma vez, sessão, sempre, negar. Saber a diferença antes de um pedido de aprovação às 2 da manhã é melhor que ler só naquela hora.
• ✓Obrigatório:
  Você escolheu um provedor de STT de propósito.Local não precisa de key e roda na sua própria máquina. Groq e OpenAI precisam de API key e cobram por uso. Decida antes da primeira nota de voz, não depois.
• ✓Obrigatório:
  O bot token vive no .env, não numa mensagem que você pediu para o agente ler em voz alta.O mascaramento existe e já teve brechas. Rotacione ao menor sinal de suspeita, no mesmo dia.

Hermes Agent no Telegram, respostas rápidas

Como eu conecto o Hermes Agent ao Telegram?+

Crie um bot através do @BotFather, coloque o token em TELEGRAM_BOT_TOKEN dentro do ~/.hermes/.env, adicione seu ID numérico de usuário do Telegram em TELEGRAM_ALLOWED_USERS, e suba o gateway. O python-telegram-bot cuida da conexão, por long polling a menos que você configure um webhook.

O OpenClaw é melhor que o Hermes Agent no Telegram?+

Eles diferem em quem começa a conversa, não na profundidade do canal. O heartbeat do OpenClaw consegue mandar mensagem para você primeiro, num timer. O Hermes só fala no Telegram quando você manda mensagem para ele ou um cron job dispara. Escolha o que combina com se você quer um assistente ambiente ou um reativo.

O Hermes Agent suporta mensagem de voz no Telegram?+

Sim. Notas de voz que chegam são transcritas pelo provedor stt no config.yaml (local, gratuito; groq, precisa de GROQ_API_KEY; openai, precisa de VOICE_TOOLS_OPENAI_KEY) e injetadas como texto.

Respostas podem voltar como bolhas de voz nativas através do tts, usando OpenAI, ElevenLabs ou o provedor gratuito Edge TTS (o último precisa do ffmpeg instalado para produzir a bolha redonda em vez de um arquivo de áudio simples).

O Hermes Agent funciona com WhatsApp ou iMessage também?+

Sim, como adaptadores de plataforma separados, com o mesmo sistema de memória e aprovação por trás. O iMessage passa pelo BlueBubbles e precisa de um Mac sempre ligado. O caminho padrão do WhatsApp é uma bridge não oficial com um pequeno risco de ban; existe um caminho de WhatsApp Business Cloud API para quem precisa da rota oficial em vez disso.

O meu bot token do Telegram está seguro com o Hermes Agent?+

O Hermes marca ele como segredo e tem código dedicado para removê-lo de linhas de log e texto de erro. Esse mascaramento já teve brechas documentadas no passado, já corrigidas. Trate o token como qualquer outra credencial: mantenha fora de arquivos .env que outra pessoa consiga ler, e rotacione no momento em que suspeitar que ele foi impresso em algum lugar.

O que acontece se eu não aprovar um comando arriscado no Telegram?+

Nada roda. O card de aprovação expira depois de cinco minutos por padrão, e o próprio card avisa isso: silêncio é um não seguro, não um sim padrão.