Hermes Agent sin voz: cómo arreglarlo paso a paso

Cuando el modo voz se queda mudo, el culpable casi nunca es Hermes

Le mandaste una nota de voz al bot y no recibiste nada. O el agente respondió en texto cuando lo configuraste para responder en audio. O ayer funcionaba y hoy el archivo se queda ahí, sin leer. Que el modo voz falle en silencio es el problema más habitual con Hermes Agent, y casi siempre es una de las ocho cosas concretas que se interponen entre tu micrófono y el modelo.

Empieza con Hermify si prefieres saltarte el pipeline entero y usar un Hermes Agent gestionado con la voz ya montada. Si no, ve por partes en este orden - las comprobaciones son baratas y cada una descarta una familia entera de fallos.

1. El bot no puede acceder a los mensajes de voz en Telegram

Si tu agente vive en Telegram y las notas de voz no llegan - el texto funciona, pero los audios se ignoran - lo primero es la configuración de privacidad del bot. Por defecto un bot en un grupo solo ve mensajes que lo mencionan o empiezan con un comando slash, así que los audios se descartan en silencio.

Ajústalo en BotFather:

Abre @BotFather y envía /mybots.
Elige tu bot, luego Bot Settings → Group Privacy.
Ponlo en Disabled.

Los mensajes directos al bot no se ven afectados - si tu bot funciona en DMs y solo falla en grupos, la privacidad de grupo es la razón.

Hay un segundo caso más sutil: la cuenta del remitente tiene la privacidad de mensajes de voz en "solo contactos". Telegram devuelve entonces un error VOICE_MESSAGES_FORBIDDEN cuando el bot intenta enviar audio de vuelta, aunque la voz entrante funcionase bien. Si tu bot recibe voz pero falla al responder con audio, revisa primero tu propia configuración de privacidad en Telegram.

2. No hay proveedor de speech-to-text configurado

Hermes necesita un backend de speech-to-text (STT) para convertir el audio entrante en un prompt. Si no hay ninguno configurado, los audios simplemente no se procesan - el agente lee texto e ignora la voz.

Comprueba el bloque STT de tu configuración:

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

Fallos habituales:

La OPENAI_API_KEY (o ELEVENLABS_API_KEY, o la clave del proveedor que elijas) no está exportada al proceso. Confírmalo con printenv OPENAI_API_KEY en el mismo shell que arranca Hermes.
La clave existe pero es incorrecta o ha sido revocada. Una clave revocada da un 401 que algunas versiones de Hermes registran una vez al arrancar y luego silencian.
Configuraste provider: whisper (Whisper local) sin instalar el extra. Whisper local necesita pip install "hermes-agent[voice]", más una descarga real del modelo la primera vez.

Si no sabes qué proveedor tienes, ejecuta hermes voice test (o revisa hermes gateway logs buscando una línea stt.provider= al arrancar).

Una ventana de terminal mostrando un log del gateway de Hermes con la línea del proveedor STT resaltada y un error de API key

3. Falta FFmpeg en el contenedor

Este es el fallo de voz más común en despliegues autoalojados, y no es obvio a partir de los logs. Telegram entrega los mensajes de voz como archivos .ogg codificados con OPUS, y la mayoría de proveedores STT (incluido Whisper local) necesitan FFmpeg para decodificarlos. Si FFmpeg no está en el path del sistema, el audio llega, no se decodifica y el pipeline muere con un error de códec que parece un problema de red.

En una instalación bare-metal o VPS:

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

# Alpine (habitual en imágenes Docker slim)
apk add --no-cache ffmpeg

Dentro de un contenedor Docker construido sobre python:3.11-slim, FFmpeg no viene incluido. La imagen oficial de Hermes lo trae; un Dockerfile propio puede que no. Verifícalo con:

docker exec <container> which ffmpeg

Si no devuelve nada, añade apt-get install -y ffmpeg a tu Dockerfile y reconstruye.

4. El mensaje de voz es demasiado grande o tiene un formato erróneo

Los límites de Telegram para las notas de voz son generosos pero no infinitos. Los bots pueden enviar mensajes de voz de hasta 50 MB, y los archivos por encima de 20 MB llegan como adjuntos en lugar de notas reproducibles. Las notas de voz entrantes son siempre OGG/OPUS, pero si tienes un flujo que empuja audio grabado a través del bot desde otra fuente (un podcast transcrito con Whisper, por ejemplo), el formato importa.

Si tu respuesta de voz sale como archivo adjunto en vez de burbuja de audio, es que pesa demasiado o no es audio/ogg. Recodifícalo a OGG/OPUS mono por debajo de 1 MB:

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

Whisper además requiere entrada mono - los archivos estéreo dan un error de canales que aparece como "sin transcripción".

5. El contenedor se quedó sin memoria y mató al worker de STT

Los modelos locales de Whisper consumen mucha RAM. whisper-base necesita alrededor de 1 GB para ejecutarse, y whisper-large-v3 acerca de 10 GB. En un VPS de 1 GB el contenedor casi seguro está siendo cerrado por OOM en cuanto llega una nota de voz, y Docker lo reinicia en silencio.

Revisa el código de salida:

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

Un exit code 137 es SIGKILL, que en una máquina con poca memoria casi siempre significa OOM killer. Confírmalo con dmesg -T | grep -i "killed process" en el host.

La solución es una máquina más grande o pasar a la API en la nube en lugar de Whisper local. Si estás en un droplet de 1 GB y quieres conservar la voz, cambia stt.provider a openai o elevenlabs - la llamada STT ocurre por red, así que la RAM queda libre para el bucle de razonamiento.

Si el contenedor se reinicia por motivos distintos a OOM, consulta nuestra guía de Docker para Hermes Agent para una checklist completa.

6. TTS está configurado pero nunca devuelve audio

El fallo opuesto: el agente transcribe tu voz sin problema y genera una respuesta de texto, pero no llega ningún audio. Casi siempre es un problema de text-to-speech (TTS), no de STT.

Tres sospechosos habituales:

La clave de TTS chocó con el rate limit. ElevenLabs, en particular, tiene límites estrictos de concurrencia y topes por segundo. Cuando se superan, la API devuelve un error en vez de una respuesta vacía, pero si tu versión de Hermes no expone los errores de proveedor del worker de TTS, obtienes una respuesta solo texto sin explicación. Revisa el panel del proveedor por si hay un pico de rate-limit.
La síntesis expiró por timeout. Para respuestas largas, el endpoint estándar de ElevenLabs espera a generar el audio completo antes de devolverlo. Respuestas de más de 500 palabras pueden pasarse del timeout HTTP por defecto. Activa la síntesis en streaming si tu versión de Hermes lo soporta, o pídele al agente que responda más corto.
El audio se generó pero falló al subirse. La Bot API de Telegram tiene un límite de 1 MB en sendVoice para que el audio se renderice como burbuja reproducible. Por encima, llega como archivo. Si el MP3 generado pasa de 1 MB, baja el bitrate en la config de TTS o divide la respuesta.

Vista dividida de un móvil con un chat de Telegram mostrando una nota de voz en un panel y un terminal con una respuesta de rate-limit del TTS en el otro

7. El gateway está conectado pero el pipeline de voz no arrancó

Hermes ejecuta el pipeline de STT y TTS como un worker separado del gateway principal. En algunos setups, el gateway arranca limpio pero el worker de voz no llega a inicializar - normalmente porque una dependencia de Python del extra de voz falló al compilar en la instalación.

Diagnóstico:

hermes voice status

Si el pipeline no está corriendo, reinícialo explícitamente:

hermes voice start

Si el start falla con un error de importación, reinstala el extra de voz:

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

En Android/Termux usa el extra específico de Termux:

pip install "hermes-agent[termux]"

8. Todo funciona en local pero no en producción

Si la voz funciona en tu portátil y falla en la instancia desplegada, la causa suele ser una de tres: FFmpeg no está en la imagen de producción, las variables de entorno no se pasan al contenedor, o el contenedor corre como usuario no-root sin permiso para escribir en el directorio temporal de audio.

Para el último caso, Hermes escribe archivos WAV efímeros en /tmp (o el voice.temp_dir configurado) durante la transcripción. Si el usuario del contenedor no puede escribir ahí, la llamada de STT falla al crear el archivo. Arréglalo montando un volumen escribible:

volumes:
  - hermes_tmp:/tmp

O apunta voice.temp_dir a una ruta que sepas que es escribible.

Cuándo sale más barato delegarlo

Los ocho fallos anteriores son todos arreglables, y si tienes veinte minutos y disfrutas depurando códecs, los arreglarás. Si prefieres que el pipeline simplemente funcione, Hermify ejecuta un Hermes Agent gestionado en Telegram donde FFmpeg, STT, TTS, memoria y el gateway están resueltos por ti. El modo voz viene activado por defecto, los archivos de memoria siguen siendo tuyos y estar en el aire lleva cerca de un minuto.

Para leer más, nuestra guía de configuración del modo voz cubre el camino feliz en detalle, y nuestro post sobre proveedores de TTS compara OpenAI, ElevenLabs y opciones locales si estás eligiendo stack por primera vez.