Hermes Agent auf WhatsApp verbindet nicht: Lösungen

Der Bot antwortet nie und die Logs sind stumm

Sie haben Hermes Agent an WhatsApp angebunden, das Gateway startet fehlerfrei, und die Nummer, an die Sie schreiben, liegt da wie ein Stein. Kein eingehendes Event in den Logs, keine Zustellbestätigung auf dem Handy, kein klarer Hinweis, welches der zehn beweglichen Teile kaputt ist. WhatsApp ist der fragilste Kanal im Hermes-Stack, und fast jeder Fall einer stillen Verbindung lässt sich auf eine von vier Ursachen zurückführen.

Drei der vier scheitern absichtlich still, weshalb das Setup korrekt aussieht, während nichts funktioniert. Dieser Beitrag geht jede Ursache durch, zeigt, wie Sie bestätigen, dass es Ihre ist, und die genaue Lösung. Beginnen Sie oben - die Reihenfolge zählt, denn die erste Ursache ist die, die seit Mai 2026 jede Bereitstellung erwischt.

Ursache 1: WhatsApp Shortcake hat Ihre QR-Bibliothek zerstört

Wenn Sie Hermes Agent über Baileys, WAHA oder eine andere Bibliothek betreiben, die WhatsApp Web scrapt, und der QR-Code sich weigert, gescannt zu werden, oder den Bot direkt danach wieder ausloggt, treffen Sie den Shortcake-Rollout für verknüpfte Geräte. WhatsApp verlangt jetzt einen WebAuthn-Passkey auf dem verknüpften Gerät, und ein Headless-Server hat keinen Passkey vorzuzeigen: navigator.credentials.get() scheitert und die Verknüpfung wird mit einem 428 abgelehnt.

Symptom: Der QR wird gezeichnet, Ihr Handy scannt ihn, und entweder das Pairing kommt nie zustande oder die Session stirbt innerhalb weniger Minuten. Alte Sessions, die sich selbst neu verbunden haben, geben seit Mai 2026 aus demselben Grund Stream Errored (conflict) zurück. Wenn es im April lief und über Nacht aufhörte, ist das Ihre Ursache.

Die Lösung hat zwei Formen:

Wechseln Sie zur offiziellen Cloud API. Das ist der unterstützte Weg, er ist nicht davon bedroht, dass Meta an einem beliebigen Dienstag eine Scraping-Bibliothek zerstört, und der Rest dieses Beitrags nimmt ihn an. Konfigurieren Sie Hermes Agent mit WHATSAPP_ACCESS_TOKEN, WHATSAPP_PHONE_NUMBER_ID und WHATSAPP_WEBHOOK_VERIFY_TOKEN statt des QR-Flows. Der WhatsApp-Bereitstellungsleitfaden führt komplett durch den Anmeldetanz.
Bleiben Sie bei Baileys, wenn Sie keine andere Wahl haben, und pinnen Sie den exakten Upstream-Commit, der bei Ihnen noch funktioniert (die Maintainer verfolgen Passkey-Workarounds unter Issue #2672). Rechnen Sie damit, dass die nächste Meta-Änderung Sie wieder zerlegt. Das ist keine gute Wahl für etwas, worauf Sie sich tatsächlich verlassen.

Der Rest dieses Beitrags behandelt den Cloud-API-Weg.

Ursache 2: Ihre WABA ist nicht bei Ihrer App abonniert

Das ist der häufigste Cloud-API-Ausfall und der stillste. Sie tragen die Webhook-URL im App Dashboard ein, der GET zur Verifikation läuft durch, Meta zeigt ein grünes Häkchen neben dem Endpoint, und es kommt nie ein Nachrichten-Event an.

Was passiert: Die Webhook-URL an der App festzulegen ist nur die halbe Verkabelung. Jedes WhatsApp Business Account (WABA) muss sich zusätzlich separat bei dieser App abonnieren, damit seine Nachrichten an Ihren Endpoint geroutet werden. Das App Dashboard zeigt dieses Abonnement nirgends, und die Webhook-Oberfläche lässt Sie das Setup ohne angehängtes WABA abschließen. Meta nennt das das Shadow-Delivery-Problem, und die Lösung ist ein API-Aufruf, den der Setup-Assistent nirgends erwähnt.

Prüfen Sie zuerst:

curl -s "https://graph.facebook.com/v20.0/<WABA_ID>/subscribed_apps" \
  -H "Authorization: Bearer $WHATSAPP_ACCESS_TOKEN"

Wenn das data-Array leer ist oder die ID Ihrer App nicht enthält, ist das Ihr Problem.

Die Lösung:

curl -X POST "https://graph.facebook.com/v20.0/<WABA_ID>/subscribed_apps" \
  -H "Authorization: Bearer $WHATSAPP_ACCESS_TOKEN"

Der Aufruf gibt {"success": true} zurück, und die nächste eingehende Nachricht erreicht den Hermes-Agent-Webhook innerhalb von Sekunden. Sie müssen das Gateway nicht neu starten. Wenn Sie später den Access Token rotieren, führen Sie diesen Aufruf noch einmal aus: Das Abonnement hängt an der App, aber der Schreibvorgang verlangt einen Token mit der Berechtigung whatsapp_business_management.

Ursache 3: Sie nutzen noch den 24-Stunden-Temporär-Token

Der Token, den Meta im WhatsApp-Setup-Bildschirm zeigt, läuft nach exakt 24 Stunden ab. Wenn Sie ihn am Dienstagnachmittag in die .env von Hermes Agent kopiert haben und der Bot am Mittwochnachmittag verstummt ist, ist das der Grund.

Symptom: Ihr Gateway loggt OAuthException oder HTTP 401 beim nächsten ausgehenden Versand nach Ablauf. Eingehende Webhook-Aufrufe von Meta können weiter ankommen (sie brauchen Ihren Token nicht), aber jede Antwort, die Hermes zurückposten will, scheitert, also empfängt der Bot Ihre Nachricht, erzeugt eine Antwort und verliert sie auf dem Weg.

Die Lösung ist ein permanenter System-User-Token, kein längerer Temporär-Token:

In der Meta Business Suite öffnen Sie Users dann System Users und legen einen neuen System User mit der Rolle Admin an.
Weisen Sie Ihre WhatsApp-App und Ihr WhatsApp Business Account diesem System User mit Full control zu.
Klicken Sie Generate new token, wählen Sie Ihre App, und haken Sie sowohl whatsapp_business_messaging (nötig zum Senden) als auch whatsapp_business_management (nötig für den subscribed_apps-Aufruf aus Ursache 2) an.
Setzen Sie die Ablaufzeit auf Never. Token kopieren, in WHATSAPP_ACCESS_TOKEN eintragen, Gateway neu starten.

Prüfen Sie es, bevor Sie weggehen:

curl -s "https://graph.facebook.com/v20.0/me?access_token=$WHATSAPP_ACCESS_TOKEN"

Sollte die ID und den Namen Ihres System Users zurückgeben, nicht einen OAuth-Fehler.

Ursache 4: Sie senden an die falsche Phone Number ID

Die WhatsApp Cloud API nutzt drei IDs, und alle sind leicht zu verwechseln: die Telefonnummer selbst, die Phone Number ID und die WABA ID. Hermes Agent braucht die Phone Number ID, nicht die Nummer. Wenn Sie die Telefonnummer in WHATSAPP_PHONE_NUMBER_ID gesetzt haben, gibt jeder ausgehende Aufruf Object with ID '+49...' does not exist zurück, und jeder eingehende Aufruf kommt an, ohne dass es einen Rückweg gibt.

Zur Verwirrung: Die Phone Number ID ist eine 15- oder 16-stellige Zahl, die einer Telefonnummer sehr ähnlich sieht. Sie ist keine.

Wo Sie sie finden: Im App Dashboard öffnen Sie WhatsApp dann API Setup. Das From-Dropdown listet Ihre registrierten Nummern. Unter jeder Nummer steht in kleiner Schrift ein Feld Phone number ID. Das ist der Wert, den Hermes Agent braucht.

Prüfen Sie, dass der Wert, den Sie haben, echt ist:

curl -s "https://graph.facebook.com/v20.0/$WHATSAPP_PHONE_NUMBER_ID?access_token=$WHATSAPP_ACCESS_TOKEN"

Eine gültige ID liefert display_phone_number, verified_name und quality_rating. Eine falsche ID gibt einen Graph-API-Fehler zurück, dessen Meldung die nicht gefundene ID nennt.

Wo Sie schon dabei sind, prüfen Sie die Variable WHATSAPP_BUSINESS_ACCOUNT_ID: Das ist eine separate ID für die WABA, die die Nummer besitzt, benutzt vom Abonnement-Aufruf aus Ursache 2, und es ist leicht, die beiden beim Kopieren aus dem Dashboard zu vertauschen.

Zwei weitere Fallen, die es auszuschließen gilt

Wenn die vier Ursachen oben sauber sind und Nachrichten immer noch nicht fließen, prüfen Sie als nächstes:

Die App hängt im Dev-Modus fest. WhatsApp liefert nur Webhooks für Nachrichten, die der App-Besitzer in den letzten 24 Stunden gesendet oder empfangen hat, und nur von Nummern, die unter WhatsApp dann API Setup dann To explizit hinzugefügt wurden. Schalten Sie die App unter App Review auf Live, wenn Sie bereit für echten Nutzerverkehr sind.
Das Webhook-Feld messages ist nicht abonniert. Unter WhatsApp dann Configuration schauen Sie den Abschnitt Webhook fields an und bestätigen, dass messages ein grünes Häkchen hat. Meta lässt Sie eine Webhook-URL ohne abonnierte Felder speichern, und liefert dann still nichts.

Diagnose-Reihenfolge, die Zeit spart

Wenn der Bot stumm wird, arbeiten Sie die Ursachen in dieser Reihenfolge ab, statt alles neu zu installieren:

Sind Sie auf dem QR-Weg? Wenn ja, migrieren Sie zur Cloud API, bevor Sie eine weitere Minute an irgendetwas anderem verbringen. Shortcake geht nicht weg.
Ist Ihre WABA bei Ihrer App abonniert? Der eine curl-Aufruf oben beantwortet das in drei Sekunden. Höchste Trefferquote bei Cloud-API-Bereitstellungen.
Prüfen Sie den Token. curl /me scheitert sofort, wenn der Token tot, falsch oder ohne Scopes ist.
Verifizieren Sie die Phone Number ID. curl /$PHONE_NUMBER_ID liefert die Anzeigefelder der Nummer, wenn sie gültig ist.
Prüfen Sie Dev-Modus und abonnierte Felder. Langsamer zu inspizieren, seltener als Root Cause, aber vor einem Ticket bei Meta lohnt es sich, auszuschließen.

Für den vollständigen Erstinstallationsweg siehe den Hermes-Agent-WhatsApp-Bereitstellungsleitfaden. Wenn Telegram zu Ihrem Anwendungsfall passt, deckt der Telegram-vs-WhatsApp-Vergleich die Tradeoffs ab, bevor Sie sich festlegen.

Wenn Sie sich nicht jede Woche mit Meta streiten wollen

Meta liefert Webhook-UI-Änderungen aus, verschärft die Verifizierung und zerlegt den QR-Weg in ihrem eigenen Rhythmus. Wenn Sie es so lesen, dass ein persönlicher KI-Agent kein Business-Manager-Konto und keinen System-User-Token braucht, um Hallo zurück zu sagen, starten Sie mit Hermify. Hermify betreibt einen verwalteten Hermes Agent auf Telegram mit demselben Speicher und denselben Skills, in etwa einer Minute online, ohne die Meta-Konfiguration, die man pflegen müsste.