Hermes Agent voix HS : comment réparer étape par étape

Quand le mode voix devient muet, ce n'est presque jamais Hermes

Vous avez envoyé une note vocale à votre bot et rien n'est revenu. Ou l'agent a répondu en texte alors que vous l'aviez configuré pour répondre en audio. Ou hier ça marchait, aujourd'hui le fichier reste là, non lu. Le mode voix qui tombe en silence est le problème le plus courant avec Hermes Agent, et c'est presque toujours l'une des huit choses précises qui se glissent entre votre micro et le modèle.

Commencez avec Hermify si vous préférez sauter le pipeline entier et utiliser un Hermes Agent géré avec la voix déjà branchée. Sinon, avancez dans l'ordre - les vérifications sont bon marché et chacune écarte une famille entière de pannes.

1. Le bot ne peut pas accéder aux messages vocaux sur Telegram

Si votre agent vit sur Telegram et que les notes vocales n'arrivent pas du tout - le texte marche, mais les vocaux sont ignorés - la première chose à regarder est la configuration de confidentialité du bot. Par défaut, un bot dans un groupe ne voit que les messages qui le mentionnent ou qui commencent par une commande slash, donc les vocaux sont écartés en silence.

Réglez ça dans BotFather :

Ouvrez @BotFather et envoyez /mybots.
Choisissez votre bot, puis Bot Settings → Group Privacy.
Mettez-le sur Disabled.

Les messages directs au bot ne sont pas concernés par ce réglage - si votre bot marche en DM et échoue seulement en groupe, c'est la confidentialité de groupe.

Il existe un deuxième cas plus subtil : le compte de l'expéditeur a la confidentialité des messages vocaux réglée sur « contacts uniquement ». Telegram renvoie alors une erreur VOICE_MESSAGES_FORBIDDEN quand le bot tente d'envoyer un audio de retour, même si la voix entrante fonctionnait très bien. Si votre bot reçoit la voix mais échoue silencieusement à répondre en audio, vérifiez d'abord vos propres réglages de confidentialité Telegram.

2. Aucun fournisseur speech-to-text n'est configuré

Hermes a besoin d'un backend speech-to-text (STT) pour transformer l'audio entrant en prompt. Si aucun n'est configuré, les vocaux ne sont simplement pas traités - l'agent lit le texte et ignore la voix.

Vérifiez le bloc STT dans votre configuration :

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

Oublis fréquents :

La clé OPENAI_API_KEY (ou ELEVENLABS_API_KEY, ou celle du fournisseur choisi) n'est pas exportée dans le processus. Vérifiez avec printenv OPENAI_API_KEY dans le même shell qui lance Hermes.
La clé existe mais est fausse ou a été révoquée. Une clé révoquée produit un 401 que certaines versions de Hermes loggent une fois au démarrage puis avalent ensuite.
Vous avez configuré provider: whisper (Whisper local) sans installer l'extra. Whisper local a besoin de pip install "hermes-agent[voice]", plus un vrai téléchargement du modèle au premier lancement.

Si vous n'êtes pas sûr du fournisseur en place, lancez hermes voice test (ou regardez hermes gateway logs à la recherche d'une ligne stt.provider= au démarrage).

Une fenêtre de terminal montrant un log du gateway Hermes avec la ligne du fournisseur STT surlignée et une erreur de clé API

3. FFmpeg est absent du conteneur

C'est la panne vocale la plus fréquente sur les déploiements auto-hébergés, et elle n'est pas évidente dans les logs. Telegram livre les messages vocaux en fichiers .ogg encodés en OPUS, et la plupart des fournisseurs STT (Whisper local inclus) ont besoin de FFmpeg pour les décoder. Si FFmpeg n'est pas dans le PATH système, l'audio arrive, échoue au décodage, et le pipeline sort sur une erreur de codec qui ressemble à un problème réseau.

Sur une installation bare-metal ou VPS :

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

# Alpine (courant dans les images Docker slim)
apk add --no-cache ffmpeg

Dans un conteneur Docker basé sur python:3.11-slim, FFmpeg n'est pas inclus par défaut. L'image officielle Hermes le contient ; un Dockerfile personnalisé peut ne pas l'avoir. Vérifiez avec :

docker exec <container> which ffmpeg

Si ça ne renvoie rien, ajoutez apt-get install -y ffmpeg à votre Dockerfile et reconstruisez.

4. Le message vocal est trop lourd ou dans le mauvais format

Les limites de Telegram lui-même sur les notes vocales sont généreuses mais pas infinies. Les bots peuvent envoyer des messages vocaux jusqu'à 50 Mo, et les fichiers au-dessus de 20 Mo arrivent en pièce jointe plutôt qu'en note vocale lisible. Les vocaux entrants sont toujours en OGG/OPUS, mais si vous avez un flux qui pousse de l'audio enregistré à travers le bot depuis une autre source (un podcast transcrit par Whisper, par exemple), le format compte.

Si votre réponse vocale sort en pièce jointe au lieu de bulle audio, le fichier est soit trop lourd, soit pas au format audio/ogg. Ré-encodez en OGG/OPUS mono sous 1 Mo :

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

Whisper exige en plus une entrée mono - les fichiers stéréo remontent une erreur de canaux qui apparaît comme « pas de transcription ».

5. Le conteneur a manqué de mémoire et tué le worker STT

Les modèles Whisper locaux sont gourmands en mémoire. whisper-base a besoin d'environ 1 Go de RAM pour tourner, et whisper-large-v3 avoisine les 10 Go. Sur un VPS de 1 Go, le conteneur est presque à coup sûr tué par l'OOM dès qu'un vocal arrive, et Docker le redémarre en silence.

Regardez le code de sortie :

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

Un exit code 137 correspond à SIGKILL, ce qui sur une machine à faible mémoire signifie presque toujours l'OOM killer. Confirmez avec dmesg -T | grep -i "killed process" sur l'hôte.

La solution, c'est soit une machine plus grosse, soit l'API hébergée à la place de Whisper local. Si vous êtes sur un droplet de 1 Go et voulez garder la voix, passez stt.provider à openai ou elevenlabs - l'appel STT part sur le réseau, donc la RAM reste libre pour la boucle de raisonnement.

Si le conteneur redémarre pour d'autres raisons qu'OOM, voyez notre guide Docker pour Hermes Agent pour une checklist complète.

6. Le TTS est configuré mais ne renvoie jamais d'audio

La panne inverse : l'agent transcrit votre voix sans souci et génère une réponse texte, mais aucun audio ne revient. C'est presque toujours un problème de text-to-speech (TTS), pas de STT.

Trois suspects habituels :

La clé TTS a heurté un rate limit. ElevenLabs, en particulier, a des limites strictes de concurrence et des plafonds par seconde. Quand la limite est dépassée, l'API renvoie une erreur au lieu d'une réponse silencieuse, mais si votre version de Hermes ne remonte pas les erreurs upstream du worker TTS, vous obtenez une réponse en texte seul sans explication. Vérifiez le tableau de bord du fournisseur pour un pic de rate-limit.
La synthèse a dépassé le timeout. Pour les réponses longues, l'endpoint standard d'ElevenLabs attend la fin de la génération audio avant de renvoyer. Des réponses de plus de 500 mots environ peuvent dépasser les timeouts HTTP par défaut. Activez la synthèse en streaming si votre version de Hermes le supporte, ou demandez à l'agent de raccourcir ses réponses.
L'audio a été généré mais l'upload a échoué. La Bot API de Telegram a une limite de 1 Mo sur sendVoice pour que l'audio s'affiche comme bulle lisible. Au-dessus, il revient en fichier. Si le MP3 généré dépasse 1 Mo, baissez le bitrate dans la config TTS ou découpez la réponse.

Vue divisée d'un téléphone montrant une conversation Telegram avec une note vocale d'un côté et un terminal affichant une réponse de rate-limit de l'API TTS de l'autre

7. Le gateway est connecté mais le pipeline vocal n'est pas démarré

Hermes fait tourner le pipeline STT et TTS comme un worker distinct du gateway principal. Sur certains setups, le gateway démarre proprement mais le worker vocal échoue à se lancer - généralement parce qu'une dépendance Python de l'extra vocal a échoué à compiler à l'installation.

Diagnostic :

hermes voice status

Si le pipeline ne tourne pas, redémarrez-le explicitement :

hermes voice start

Si le start échoue sur une erreur d'import, réinstallez l'extra vocal :

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

Sur Android/Termux, utilisez l'extra spécifique à Termux :

pip install "hermes-agent[termux]"

8. Tout marche en local mais pas en production

Si la voix marche sur votre portable et échoue sur l'instance déployée, la cause est presque toujours l'une de trois : FFmpeg absent de l'image de production, variables d'environnement non transmises au conteneur, ou conteneur qui tourne en utilisateur non-root sans permission d'écrire dans le répertoire audio temporaire.

Pour ce dernier cas, Hermes écrit des fichiers WAV éphémères dans /tmp (ou le voice.temp_dir configuré) pendant la transcription. Si l'utilisateur du conteneur ne peut pas y écrire, l'appel STT échoue à la création du fichier. Corrigez en montant un volume inscriptible :

volumes:
  - hermes_tmp:/tmp

Ou pointez voice.temp_dir vers un chemin dont vous savez qu'il est inscriptible.

Quand c'est moins cher de déléguer

Les huit pannes ci-dessus sont toutes réparables, et si vous avez vingt minutes et que vous aimez déboguer des codecs, vous les réparerez. Si vous préférez que le pipeline fonctionne tout seul, Hermify fait tourner un Hermes Agent géré sur Telegram où FFmpeg, STT, TTS, mémoire et gateway sont déjà réglés pour vous. Le mode voix est actif par défaut, les fichiers de mémoire restent à vous, et être en ligne prend environ une minute.

Pour aller plus loin, notre guide de configuration du mode voix couvre le chemin heureux en détail, et notre article sur les fournisseurs TTS compare OpenAI, ElevenLabs et les options locales si vous choisissez une stack pour la première fois.