Hermes Agent sem voz: como consertar passo a passo

Quando o modo voz emudece, a culpa quase nunca é do Hermes

Você mandou um áudio para o bot e não voltou nada. Ou o agente respondeu em texto quando você configurou para responder em áudio. Ou ontem funcionava e hoje o arquivo fica lá parado, sem ser lido. O modo voz falhando em silêncio é o problema mais comum com o Hermes Agent, e quase sempre é uma de oito coisas específicas entre o seu microfone e o modelo.

Comece com a Hermify se preferir pular o pipeline inteiro e usar um Hermes Agent gerenciado com a voz já ligada. Se não, siga esta lista em ordem - as verificações são baratas e cada uma descarta uma família inteira de falhas.

1. O bot não consegue acessar mensagens de voz no Telegram

Se o seu agente vive no Telegram e as notas de voz não chegam - texto funciona, mas áudios são ignorados - o primeiro lugar a olhar é a configuração de privacidade do bot. Por padrão, um bot em um grupo só vê mensagens que o mencionam ou começam com um comando slash, então os áudios são descartados em silêncio.

Ajuste no BotFather:

1. Abra @BotFather e envie /mybots.
2. Escolha seu bot, depois Bot Settings → Group Privacy.
3. Deixe em Disabled.

Mensagens diretas para o bot não são afetadas por essa configuração - se o bot funciona em DMs e só falha em grupos, a privacidade de grupo é o motivo.

Há um segundo caso mais sutil: a conta do remetente está com a privacidade de mensagens de voz em "apenas contatos". O Telegram então devolve um erro VOICE_MESSAGES_FORBIDDEN quando o bot tenta mandar áudio de volta, mesmo que o áudio de entrada tenha funcionado. Se o seu bot recebe voz mas silenciosamente falha em responder com áudio, veja primeiro a sua própria configuração de privacidade no Telegram.

2. Não há um provedor de speech-to-text configurado

O Hermes precisa de um backend de speech-to-text (STT) para transformar o áudio recebido em prompt. Se nenhum estiver configurado, os áudios simplesmente não são processados - o agente lê texto e ignora voz.

Veja o bloco STT no seu config:

voice:
  stt:
    provider: openai
    api_key: ${OPENAI_API_KEY}

Falhas comuns:

• A OPENAI_API_KEY (ou ELEVENLABS_API_KEY, ou a chave do provedor que você escolheu) não está exportada para o processo. Confirme com printenv OPENAI_API_KEY no mesmo shell que inicia o Hermes.
• A chave existe mas está errada ou foi revogada. Uma chave revogada gera um 401 que algumas versões do Hermes logam uma vez na subida e depois silenciam.
• Você configurou provider: whisper (Whisper local) sem instalar o extra. Whisper local precisa de pip install "hermes-agent[voice]", além do download real do modelo na primeira execução.

Se estiver em dúvida sobre qual provedor tem, rode hermes voice test (ou olhe hermes gateway logs procurando uma linha stt.provider= na inicialização).

3. Falta o FFmpeg no contêiner

Essa é a falha de voz mais comum em deploys auto-hospedados e não é óbvia nos logs. O Telegram entrega mensagens de voz como arquivos .ogg codificados em OPUS, e a maioria dos provedores de STT (incluindo Whisper local) precisa do FFmpeg para decodificar. Se o FFmpeg não estiver no PATH do sistema, o áudio chega, falha na decodificação e o pipeline morre com um erro de codec que parece problema de rede.

Numa instalação bare-metal ou VPS:

# Debian/Ubuntu
sudo apt update && sudo apt install -y ffmpeg

# Alpine (comum em imagens Docker slim)
apk add --no-cache ffmpeg

Dentro de um contêiner Docker baseado em python:3.11-slim, o FFmpeg não vem incluído por padrão. A imagem oficial do Hermes já traz; um Dockerfile customizado pode não trazer. Verifique com:

docker exec <container> which ffmpeg

Se não retornar nada, adicione apt-get install -y ffmpeg no seu Dockerfile e faça o rebuild.

4. A mensagem de voz é grande demais ou está no formato errado

Os limites do próprio Telegram para notas de voz são generosos mas não infinitos. Bots podem enviar mensagens de voz de até 50 MB, e arquivos acima de 20 MB chegam como anexos comuns em vez de notas de voz reproduzíveis. Notas de voz recebidas são sempre OGG/OPUS, mas se você tem um fluxo que empurra áudio gravado através do bot vindo de outra fonte (um podcast transcrito com Whisper, por exemplo), o formato importa.

Se a sua resposta de voz está saindo como anexo em vez de bolha de áudio, o arquivo é grande demais ou não é audio/ogg. Recodifique para OGG/OPUS mono abaixo de 1 MB:

ffmpeg -i input.wav -c:a libopus -b:a 32k -ac 1 output.ogg

O Whisper além disso exige entrada mono - arquivos estéreo dão um erro de canais que aparece como "sem transcrição".

5. O contêiner ficou sem memória e matou o worker de STT

Modelos locais de Whisper são famintos por memória. whisper-base precisa de cerca de 1 GB de RAM para rodar, e whisper-large-v3 fica perto de 10 GB. Num VPS de 1 GB, o contêiner quase certamente está sendo morto por OOM assim que uma nota de voz chega, e o Docker o reinicia em silêncio.

Cheque o exit code:

docker inspect <container> --format='{{.State.ExitCode}}'

Um exit code 137 é SIGKILL, que numa máquina com pouca memória quase sempre significa OOM killer. Confirme com dmesg -T | grep -i "killed process" no host.

A solução é uma máquina maior ou a API hospedada em vez do Whisper local. Se você está num droplet de 1 GB e quer manter voz, troque stt.provider para openai ou elevenlabs - a chamada STT acontece pela rede, então a RAM fica livre para o loop de raciocínio.

Se o contêiner reinicia por motivos diferentes de OOM, veja nosso guia de Docker para Hermes Agent para uma checklist completa.

6. TTS está configurado mas nunca devolve áudio

A falha inversa: o agente transcreve sua voz normalmente e gera uma resposta em texto, mas nenhum áudio volta. Quase sempre é um problema de text-to-speech (TTS), não de STT.

Três culpados usuais:

• A chave de TTS bateu no rate limit. O ElevenLabs, em particular, tem limites rígidos de concorrência e teto por segundo. Quando o limite estoura, a API devolve um erro em vez de uma resposta silenciosa, mas se sua versão do Hermes não expõe erros upstream do worker de TTS, você recebe uma resposta só texto sem explicação. Cheque o painel do provedor por um pico de rate-limit.
• A síntese estourou o timeout. Para respostas longas, o endpoint padrão do ElevenLabs espera gerar o áudio inteiro antes de retornar. Respostas com mais de umas 500 palavras podem estourar o timeout HTTP padrão. Ative a síntese em streaming se sua versão do Hermes suportar, ou peça respostas mais curtas ao agente.
• O áudio foi gerado mas falhou no upload. A Bot API do Telegram tem um limite de 1 MB no sendVoice para o áudio renderizar como bolha reproduzível. Acima disso, volta como arquivo. Se o MP3 gerado passa de 1 MB, reduza o bitrate na config de TTS ou divida a resposta.

7. O gateway está conectado mas o pipeline de voz não subiu

O Hermes roda o pipeline de STT e TTS como um worker separado do gateway principal. Em alguns setups, o gateway sobe limpo mas o worker de voz falha ao iniciar - normalmente porque uma dependência Python do extra de voz falhou na compilação durante a instalação.

Diagnóstico:

hermes voice status

Se o pipeline não estiver rodando, reinicie explicitamente:

hermes voice start

Se o start falhar com erro de import, reinstale o extra de voz:

pip install --force-reinstall "hermes-agent[voice]"

No Android/Termux use o extra específico do Termux:

pip install "hermes-agent[termux]"

8. Tudo funciona local mas não em produção

Se a voz funciona no seu notebook e falha na instância deployada, a causa costuma ser uma de três: falta FFmpeg na imagem de produção, as variáveis de ambiente não são passadas para o contêiner, ou o contêiner roda como usuário não-root sem permissão para escrever no diretório temporário de áudio.

Para o último caso, o Hermes escreve arquivos WAV temporários em /tmp (ou no voice.temp_dir configurado) durante a transcrição. Se o usuário do contêiner não pode escrever ali, a chamada de STT falha na criação do arquivo. Resolva montando um volume com escrita:

volumes:
  - hermes_tmp:/tmp

Ou aponte voice.temp_dir para um caminho onde sabe que se pode escrever.

Quando sai mais barato delegar

As oito falhas acima são todas consertáveis, e se você tiver vinte minutos e gostar de depurar codecs, vai consertá-las. Se preferir que o pipeline simplesmente funcione, a Hermify roda um Hermes Agent gerenciado no Telegram onde FFmpeg, STT, TTS, memória e gateway já estão resolvidos por você. O modo voz vem ativado por padrão, os arquivos de memória continuam seus e ir ao ar leva cerca de um minuto.

Para se aprofundar, nosso guia de configuração do modo voz cobre o caminho feliz em detalhes, e nosso post sobre provedores de TTS compara OpenAI, ElevenLabs e opções locais se você está escolhendo a stack pela primeira vez.

Sources

• Telegram Bot API - referência do sendVoice
• Discussão sobre a exigência de FFmpeg no Whisper
• Limites de concorrência do ElevenLabs em produção
• Como lidar com rate limits da API do ElevenLabs