Hermes Agent Sprache geht nicht: Schritt für Schritt beheben

Wenn der Sprachmodus verstummt, liegt es fast nie an Hermes

Sie haben eine Sprachnachricht an Ihren Bot geschickt und nichts zurückbekommen. Oder der Agent antwortet in Text, obwohl Sie ihn auf Audio konfiguriert haben. Oder gestern hat es funktioniert und heute liegt die Datei einfach da, ungelesen. Ein stummer Sprachmodus ist das häufigste Problem bei Hermes Agent, und fast immer ist es eine von acht konkreten Sachen zwischen Ihrem Mikrofon und dem Modell.

Starten Sie mit Hermify, wenn Sie die gesamte Pipeline überspringen und einen verwalteten Hermes Agent mit bereits eingerichteter Sprache nutzen möchten. Andernfalls arbeiten Sie diese Liste der Reihe nach ab - die Prüfungen sind günstig und jede schließt eine ganze Fehlerklasse aus.

1. Der Bot kann auf Telegram nicht auf Sprachnachrichten zugreifen

Wenn Ihr Agent in Telegram lebt und Sprachnachrichten gar nicht ankommen - Text funktioniert, aber Audios werden ignoriert - schauen Sie zuerst auf die Datenschutzeinstellungen des Bots. Standardmäßig sieht ein Bot in einer Gruppe nur Nachrichten, die ihn erwähnen oder mit einem Slash-Befehl beginnen, sodass Sprachnachrichten stillschweigend verworfen werden.

Beheben Sie es in BotFather:

Öffnen Sie @BotFather und senden Sie /mybots.
Wählen Sie Ihren Bot, dann Bot Settings → Group Privacy.
Setzen Sie es auf Disabled.

Direktnachrichten an den Bot sind von dieser Einstellung nicht betroffen - wenn Ihr Bot in DMs funktioniert und nur in Gruppen scheitert, ist die Gruppen-Privatsphäre der Grund.

Es gibt einen zweiten, subtileren Fall: Der Absender-Account hat die Sprachnachrichten-Privatsphäre auf „nur Kontakte" gesetzt. Telegram gibt dann einen VOICE_MESSAGES_FORBIDDEN-Fehler zurück, wenn der Bot versucht, Audio zurückzusenden, obwohl die eingehende Sprache einwandfrei funktioniert hat. Wenn Ihr Bot Sprache empfängt, aber lautlos an der Audioantwort scheitert, prüfen Sie zuerst Ihre eigenen Telegram-Datenschutzeinstellungen.

2. Kein Speech-to-Text-Anbieter konfiguriert

Hermes benötigt ein Speech-to-Text-Backend (STT), um eingehendes Audio in einen Prompt umzuwandeln. Ohne Konfiguration werden Sprachnachrichten schlicht nicht verarbeitet - der Agent liest Text und ignoriert Audio.

Prüfen Sie den STT-Block in Ihrer Konfiguration:

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

Häufige Auslassungen:

Der OPENAI_API_KEY (oder ELEVENLABS_API_KEY oder der API-Schlüssel des jeweiligen Anbieters) ist nicht in den Prozess exportiert. Prüfen Sie das mit printenv OPENAI_API_KEY in derselben Shell, die Hermes startet.
Der Schlüssel existiert, ist aber falsch oder wurde widerrufen. Ein widerrufener Schlüssel liefert einen 401, den manche Hermes-Versionen einmal beim Start loggen und danach verschlucken.
Sie haben provider: whisper (lokales Whisper) konfiguriert, ohne das Extra zu installieren. Lokales Whisper braucht pip install "hermes-agent[voice]" und einen echten Modell-Download beim ersten Lauf.

Wenn Sie unsicher sind, welcher Anbieter aktiv ist, führen Sie hermes voice test aus (oder prüfen Sie hermes gateway logs auf eine stt.provider=-Zeile beim Start).

Ein Terminalfenster mit einem Hermes-Gateway-Log, in dem die STT-Anbieter-Zeile und ein API-Schlüsselfehler hervorgehoben sind

3. FFmpeg fehlt im Container

Das ist die häufigste Sprachpanne bei selbst gehosteten Bereitstellungen und aus den Logs nicht offensichtlich. Telegram liefert Sprachnachrichten als .ogg-Dateien mit OPUS-Codec, und die meisten STT-Anbieter (einschließlich lokalem Whisper) brauchen FFmpeg, um sie zu dekodieren. Fehlt FFmpeg im System-PATH, kommt das Audio an, scheitert beim Dekodieren und die Pipeline bricht mit einem Codec-Fehler ab, der wie ein Netzwerkproblem aussieht.

Auf einer Bare-Metal- oder VPS-Installation:

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

# Alpine (typisch in schlanken Docker-Images)
apk add --no-cache ffmpeg

In einem Docker-Container auf Basis von python:3.11-slim ist FFmpeg standardmäßig nicht enthalten. Das offizielle Hermes-Image bringt es mit; ein eigenes Dockerfile möglicherweise nicht. Prüfen Sie mit:

docker exec <container> which ffmpeg

Kommt nichts zurück, fügen Sie apt-get install -y ffmpeg in Ihr Dockerfile ein und bauen Sie neu.

4. Die Sprachnachricht ist zu groß oder im falschen Format

Die eigenen Limits von Telegram für Sprachnotizen sind großzügig, aber nicht unbegrenzt. Bots können Sprachnachrichten bis zu 50 MB senden, und Dateien über 20 MB kommen als reguläre Anhänge statt als abspielbare Sprachnotizen an. Eingehende Nutzer-Sprachnotizen sind immer OGG/OPUS, aber wenn Sie einen Workflow haben, der aufgezeichnetes Audio aus einer anderen Quelle durch den Bot schiebt (etwa einen mit Whisper transkribierten Podcast), zählt das Format.

Wenn Ihre ausgehende Sprachantwort als Datei-Anhang statt als Audio-Blase erscheint, ist die Datei entweder zu groß oder nicht audio/ogg. Kodieren Sie sie neu in OGG/OPUS mono unter 1 MB:

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

Whisper verlangt zusätzlich Mono-Input - Stereodateien verursachen einen Kanal-Mismatch-Fehler, der als „keine Transkription" auftaucht.

5. Der Container hatte keinen Arbeitsspeicher mehr und beendete den STT-Worker

Lokale Whisper-Modelle sind speicherhungrig. whisper-base braucht rund 1 GB RAM, whisper-large-v3 eher 10 GB. Auf einem 1-GB-VPS wird der Container fast sicher vom OOM-Killer beendet, sobald eine Sprachnotiz eintrifft, und Docker startet ihn stillschweigend neu.

Prüfen Sie den Exit-Code:

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

Ein Exit-Code 137 ist SIGKILL, was auf einem Host mit knappem Speicher fast immer den OOM-Killer bedeutet. Bestätigen Sie mit dmesg -T | grep -i "killed process" auf dem Host.

Die Lösung ist eine größere Maschine oder die gehostete API statt lokalem Whisper. Wenn Sie auf einem 1-GB-Droplet arbeiten und Sprache behalten möchten, stellen Sie stt.provider auf openai oder elevenlabs - der STT-Aufruf läuft übers Netz, sodass RAM für die Reasoning-Schleife frei bleibt.

Wenn der Container aus anderen Gründen als OOM neu startet, siehe unseren Docker-Guide für Hermes Agent für eine vollständige Checkliste.

6. TTS ist konfiguriert, liefert aber nie Audio

Der umgekehrte Fall: Der Agent transkribiert Ihre Sprache problemlos und erzeugt eine Textantwort, aber es kommt kein Audio zurück. Das ist fast immer ein Text-to-Speech-Problem (TTS), nicht STT.

Drei übliche Verdächtige:

Der TTS-Schlüssel hat sein Rate-Limit gerissen. Besonders ElevenLabs hat strenge Concurrency-Limits und Sekundengrenzen. Wird das Limit überschritten, liefert die API einen Fehler statt einer stummen Antwort, aber wenn Ihre Hermes-Version Upstream-Fehler des TTS-Workers nicht durchreicht, bekommen Sie eine reine Textantwort ohne Erklärung. Prüfen Sie das Dashboard des Anbieters auf einen Rate-Limit-Spike.
Die Synthese lief in ein Timeout. Für lange Antworten wartet der Standard-Endpoint von ElevenLabs, bis die gesamte Audiodatei generiert ist, bevor er antwortet. Antworten mit mehr als etwa 500 Wörtern können HTTP-Standard-Timeouts überschreiten. Aktivieren Sie Streaming-Synthese, wenn Ihre Hermes-Version das unterstützt, oder lassen Sie den Agenten kürzer antworten.
Das Audio wurde erzeugt, aber der Upload schlug fehl. Die Bot-API von Telegram hat für sendVoice ein Größenlimit von 1 MB, damit das Audio als abspielbare Blase erscheint. Darüber landet es als Datei. Wenn die erzeugte MP3 größer als 1 MB ist, senken Sie die Bitrate in der TTS-Konfiguration oder teilen Sie die Antwort auf.

Geteilte Ansicht eines Telefons mit einem Telegram-Chat und einer Sprachnotiz auf der einen Seite und einem Terminal mit einer Rate-Limit-Antwort der TTS-API auf der anderen

7. Das Gateway ist verbunden, aber die Sprach-Pipeline läuft nicht

Hermes betreibt die STT- und TTS-Pipeline als separaten Worker neben dem Haupt-Gateway. In manchen Setups startet das Gateway sauber, aber der Sprach-Worker scheitert beim Bootstrap - meist, weil eine Python-Abhängigkeit des Sprach-Extras bei der Installation nicht kompiliert werden konnte.

Diagnose:

hermes voice status

Wenn die Pipeline nicht läuft, starten Sie sie explizit neu:

hermes voice start

Scheitert der Start mit einem Import-Fehler, installieren Sie das Sprach-Extra neu:

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

Auf Android/Termux nutzen Sie das Termux-spezifische Extra:

pip install "hermes-agent[termux]"

8. Alles funktioniert lokal, aber nicht in Produktion

Wenn Sprache auf Ihrem Laptop läuft und auf der deployten Instanz scheitert, ist die Ursache fast immer eine von drei: FFmpeg fehlt im Produktions-Image, Umgebungsvariablen werden nicht an den Container durchgereicht, oder der Container läuft als Nicht-Root-Nutzer ohne Schreibrecht im Audio-Temporärverzeichnis.

Für den letzten Fall schreibt Hermes während der Transkription kurzlebige WAV-Dateien nach /tmp (oder in das konfigurierte voice.temp_dir). Kann der Container-Nutzer dort nicht schreiben, scheitert der STT-Aufruf beim Anlegen der Datei. Beheben Sie es, indem Sie ein beschreibbares Volume einhängen:

volumes:
  - hermes_tmp:/tmp

Oder verweisen Sie voice.temp_dir auf einen Pfad, der garantiert beschreibbar ist.

Wenn es günstiger ist, das Ganze abzugeben

Die acht Pannen oben sind alle behebbar, und wenn Sie zwanzig Minuten Zeit haben und gerne Codecs debuggen, werden Sie sie beheben. Wenn Sie lieber eine Pipeline hätten, die einfach läuft, betreibt Hermify einen verwalteten Hermes Agent auf Telegram, bei dem FFmpeg, STT, TTS, Speicher und Gateway für Sie erledigt sind. Der Sprachmodus ist standardmäßig aktiv, die Speicherdateien bleiben Ihnen und Live-Gehen dauert etwa eine Minute.

Zum Weiterlesen: Unser Setup-Guide zum Sprachmodus beschreibt den Happy Path im Detail, und unser Beitrag zu TTS-Anbietern vergleicht OpenAI, ElevenLabs und lokale Optionen, wenn Sie den Stack erstmals wählen.