Hermes Agent voce non funziona: come sistemarlo passo a passo

Quando la modalità vocale ammutolisce, la colpa quasi mai è di Hermes

Hai mandato una nota vocale al bot e non è tornato niente. Oppure l'agente ha risposto in testo pur essendo configurato per rispondere in audio. Oppure ieri funzionava e oggi il file resta lì, non letto. La modalità vocale che si guasta in silenzio è il problema più comune con Hermes Agent, e quasi sempre è una di otto cose precise tra il tuo microfono e il modello.

Inizia con Hermify se preferisci saltare del tutto la pipeline e usare un Hermes Agent gestito con la voce già cablata. Altrimenti procedi in ordine: i controlli costano poco e ognuno esclude un'intera famiglia di guasti.

1. Il bot non riesce ad accedere ai messaggi vocali su Telegram

Se il tuo agente vive su Telegram e le note vocali non arrivano proprio - il testo funziona, ma gli audio vengono ignorati - la prima cosa da controllare sono le impostazioni di privacy del bot. Di default un bot in un gruppo vede solo i messaggi che lo menzionano o iniziano con un comando slash, quindi gli audio finiscono scartati in silenzio.

Sistemalo in BotFather:

Apri @BotFather e manda /mybots.
Scegli il tuo bot, poi Bot Settings → Group Privacy.
Impostalo su Disabled.

I messaggi diretti al bot non sono toccati da questa impostazione - se il tuo bot funziona nelle DM e cade solo nei gruppi, la privacy di gruppo è il motivo.

C'è un secondo caso più sottile: l'account del mittente ha la privacy dei messaggi vocali su "solo contatti". Telegram restituisce allora un errore VOICE_MESSAGES_FORBIDDEN quando il bot prova a inviare audio di ritorno, anche se la voce in ingresso funzionava bene. Se il tuo bot riceve voce ma fallisce silenziosamente a rispondere in audio, controlla prima le tue impostazioni di privacy Telegram.

2. Nessun provider di speech-to-text è configurato

Hermes ha bisogno di un backend di speech-to-text (STT) per trasformare l'audio in ingresso in un prompt. Se non è configurato nessuno, gli audio semplicemente non vengono processati - l'agente legge testo e ignora la voce.

Controlla il blocco STT nella tua configurazione:

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

Dimenticanze frequenti:

La OPENAI_API_KEY (o ELEVENLABS_API_KEY, o la chiave API del provider che hai scelto) non è esportata nel processo. Verifica con printenv OPENAI_API_KEY nella stessa shell che avvia Hermes.
La chiave esiste ma è sbagliata o è stata revocata. Una chiave revocata produce un 401 che alcune versioni di Hermes loggano una volta all'avvio e poi ingoiano.
Hai configurato provider: whisper (Whisper locale) senza installare l'extra. Whisper locale vuole pip install "hermes-agent[voice]", più uno scaricamento vero del modello al primo run.

Se non sei sicuro di quale provider hai, lancia hermes voice test (o guarda hermes gateway logs cercando una riga stt.provider= all'avvio).

Una finestra di terminale che mostra un log del gateway Hermes con la riga del provider STT evidenziata e un errore di chiave API

3. Manca FFmpeg nel container

È il guasto vocale più comune sui deploy self-hosted e non è ovvio dai log. Telegram consegna i messaggi vocali come file .ogg codificati in OPUS, e la maggior parte dei provider STT (Whisper locale incluso) ha bisogno di FFmpeg per decodificarli. Se FFmpeg non è nel PATH di sistema, l'audio arriva, fallisce la decodifica e la pipeline muore con un errore di codec che sembra un problema di rete.

Su un'installazione bare-metal o VPS:

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

# Alpine (comune nelle immagini Docker slim)
apk add --no-cache ffmpeg

Dentro un container Docker basato su python:3.11-slim, FFmpeg non è incluso di default. L'immagine ufficiale di Hermes ce l'ha; un Dockerfile custom potrebbe non averla. Verifica con:

docker exec <container> which ffmpeg

Se non torna nulla, aggiungi apt-get install -y ffmpeg al tuo Dockerfile e ricompila.

4. Il messaggio vocale è troppo grande o nel formato sbagliato

I limiti di Telegram stesso sulle note vocali sono generosi ma non infiniti. I bot possono inviare messaggi vocali fino a 50 MB, e i file oltre i 20 MB arrivano come allegati normali invece che come note vocali riproducibili. Le note vocali in ingresso sono sempre OGG/OPUS, ma se hai un flusso che spinge audio registrato attraverso il bot da un'altra sorgente (un podcast trascritto con Whisper, per esempio), il formato conta.

Se la tua risposta vocale esce come allegato invece che come bolla audio, il file o è troppo grande o non è audio/ogg. Ricodificalo in OGG/OPUS mono sotto 1 MB:

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

Whisper richiede in più input mono - i file stereo producono un errore di canali che appare come "nessuna trascrizione".

5. Il container ha finito la memoria e ha ucciso il worker STT

I modelli locali di Whisper sono affamati di memoria. whisper-base chiede circa 1 GB di RAM per girare, e whisper-large-v3 si avvicina ai 10 GB. Su un VPS da 1 GB il container quasi sicuramente viene ucciso dall'OOM appena arriva una nota vocale, e Docker lo riavvia in silenzio.

Controlla l'exit code:

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

Un exit code 137 è SIGKILL, che su una macchina con poca memoria significa quasi sempre OOM killer. Conferma con dmesg -T | grep -i "killed process" sull'host.

Il fix è una macchina più grande o l'API hosted al posto di Whisper locale. Se sei su un droplet da 1 GB e vuoi tenere la voce, cambia stt.provider in openai o elevenlabs - la chiamata STT va sulla rete, quindi la RAM resta libera per il ciclo di ragionamento.

Se il container si riavvia per motivi diversi dall'OOM, vedi la nostra guida Docker per Hermes Agent per una checklist completa.

6. Il TTS è configurato ma non torna mai audio

Il guasto opposto: l'agente trascrive la tua voce senza problemi e genera una risposta in testo, ma non torna alcun audio. Quasi sempre è un problema di text-to-speech (TTS), non di STT.

Tre sospetti abituali:

La chiave TTS ha sbattuto contro il rate limit. ElevenLabs, in particolare, ha limiti stringenti di concorrenza e tetti al secondo. Quando il limite viene superato, l'API restituisce un errore invece di una risposta muta, ma se la tua versione di Hermes non espone gli errori upstream dal worker TTS, ricevi una risposta solo testo senza spiegazione. Controlla la dashboard del provider per un picco di rate-limit.
La sintesi è andata in timeout. Per risposte lunghe, l'endpoint standard di ElevenLabs aspetta di generare l'intero file audio prima di rispondere. Risposte oltre le circa 500 parole possono superare i timeout HTTP di default. Attiva la sintesi in streaming se la tua versione di Hermes lo supporta, o chiedi all'agente di rispondere più corto.
L'audio è stato generato ma l'upload è fallito. La Bot API di Telegram ha un limite di 1 MB su sendVoice perché l'audio venga renderizzato come bolla riproducibile. Sopra, torna come file. Se l'MP3 generato supera 1 MB, abbassa il bitrate nella config TTS o dividi la risposta.

Vista divisa di un telefono con una chat Telegram che mostra una nota vocale in un pannello e un terminale con una risposta di rate-limit dell'API TTS nell'altro

7. Il gateway è connesso ma la pipeline vocale non è partita

Hermes gestisce la pipeline STT e TTS come un worker separato dal gateway principale. Su alcuni setup il gateway parte pulito ma il worker vocale fallisce l'avvio, di solito perché una dipendenza Python dell'extra vocale non è riuscita a compilare in installazione.

Diagnostica:

hermes voice status

Se la pipeline non gira, riavviala esplicitamente:

hermes voice start

Se lo start fallisce con un errore di import, reinstalla l'extra vocale:

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

Su Android/Termux usa l'extra specifico per Termux:

pip install "hermes-agent[termux]"

8. Tutto funziona in locale ma non in produzione

Se la voce funziona sul tuo laptop e fallisce sull'istanza in deploy, la causa è quasi sempre una di tre: FFmpeg manca nell'immagine di produzione, le variabili d'ambiente non arrivano al container, oppure il container gira come utente non-root senza permesso di scrivere nella directory temporanea audio.

Per quest'ultimo caso, Hermes scrive file WAV effimeri in /tmp (o nel voice.temp_dir configurato) durante la trascrizione. Se l'utente del container non può scrivere lì, la chiamata STT fallisce nella creazione del file. Risolvi montando un volume scrivibile:

volumes:
  - hermes_tmp:/tmp

Oppure fai puntare voice.temp_dir a un percorso che sai essere scrivibile.

Quando conviene delegare tutto

Gli otto guasti qui sopra sono tutti risolvibili, e se hai venti minuti e ti diverti a fare debug di codec, li risolverai. Se preferisci una pipeline che funzioni e basta, Hermify gestisce un Hermes Agent su Telegram dove FFmpeg, STT, TTS, memoria e gateway sono già a posto per te. La modalità vocale è attiva di default, i file di memoria restano tuoi e andare live richiede circa un minuto.

Per approfondire, la nostra guida al setup della modalità vocale copre il percorso felice in dettaglio, e il nostro post sui provider TTS confronta OpenAI, ElevenLabs e le opzioni locali se stai scegliendo lo stack per la prima volta.