Hermes Agent Telegram-Einrichtung: Häufige Probleme und Lösungen

Bei Telegram bleiben die meisten Hermes-Bereitstellungen hängen

Der Hermes-Schnellstart geht schnell. Bei der Telegram-Einrichtung stoßen die meisten Benutzer auf Probleme. Es liegt nicht daran, dass der Vorgang kompliziert ist, sondern daran, dass jeder Schritt auf mehrere Weisen schiefgehen kann, und wenn mehrere Dinge stillschweigend fehlschlagen, ist es schwer zu wissen, wo man suchen muss.

Dieser Leitfaden behandelt die häufigsten Probleme in der Reihenfolge, in der sie typischerweise auftreten.

Das Telegram-Bot-Token beziehen

Das Token stammt von BotFather, der offiziellen Bot-Verwaltungsoberfläche von Telegram. Dieser Schritt erscheint einfach, hat aber einige Fehlerquellen.

So machen Sie es richtig:

1. Öffnen Sie Telegram und suchen Sie nach @BotFather.
2. Senden Sie /newbot.
3. BotFather fragt nach einem Namen (Anzeigename) und einem Benutzernamen (muss auf bot enden).
4. Nach der Erstellung sendet Ihnen BotFather eine Nachricht mit dem Token. Es sieht aus wie 7123456789:ABCDef....
5. Kopieren Sie das vollständige Token einschließlich des Doppelpunkts und allem, was danach folgt.

Häufige Fehler:

• Nur die numerische ID kopieren: Das Token ist die vollständige Zeichenfolge nach dem Doppelpunkt, nicht nur die Zahl davor.
• Einen Test-Bot aus einer Entwicklungsumgebung verwenden: Wenn Sie vor Monaten einen Bot erstellt und vergessen haben, welches Token zu welchem Bot gehört, kann BotFather Ihnen mit /mybots die vorhandenen Bots anzeigen. Sie können dann Tokens widerrufen und neu generieren.
• Leerzeichen oder Zeilenumbrüche im eingefügten Token: Manche Kopiervorgänge fügen Leerzeichen hinzu. Fügen Sie es zuerst in einen reinen Texteditor ein, um sicherzustellen, dass das Token sauber ist, bevor Sie es verwenden.

Die Konfiguration TELEGRAM_ALLOWED_USERS

Dies ist der am häufigsten falsch konfigurierte Teil einer Hermes-Telegram-Bereitstellung.

Hermes verlangt von Ihnen, anzugeben, welche Telegram-Benutzer-IDs Nachrichten an den Bot senden dürfen. Ohne dies antwortet der Bot niemandem. Mit einem falschen Wert antwortet der Bot Ihnen nicht, obwohl er scheinbar läuft.

Was Sie benötigen:

Eine Telegram-Benutzer-ID ist eine Zahl, kein Benutzername. @username ist nicht das, was Hermes will. Sie benötigen die numerische ID, die wie 123456789 aussieht.

So ermitteln Sie Ihre Telegram-Benutzer-ID:

Öffnen Sie Telegram, suchen Sie nach @userinfobot und senden Sie /start. Es antwortet Ihnen mit Ihrer Benutzer-ID.

So konfigurieren Sie sie:

In config.yaml:

telegram_allowed_users: "123456789"

Für mehrere Benutzer verwenden Sie eine durch Kommas getrennte Liste:

telegram_allowed_users: "123456789,987654321"

Hermify-Hinweis: Im Onboarding-Ablauf von Hermify geben Sie Ihre Telegram-Benutzer-ID (oder eine durch Kommas getrennte Liste) im Anmeldedaten-Formular ein. Dies ist getrennt vom Feld für das Bot-Token. Beide sind erforderlich.

Problem: Der Bot antwortet überhaupt nicht

Wenn Sie eine Nachricht an Ihren Bot senden und nichts passiert, arbeiten Sie diese Checkliste durch:

1. Läuft das Hermes-Gateway?

hermes gateway status

Wenn das Gateway nicht läuft, hat der Bot keinen Listener. Starten Sie es:

hermes gateway start

2. Steht Ihre Benutzer-ID in der Liste der zugelassenen Benutzer?

Überprüfen Sie die Konfiguration telegram_allowed_users doppelt. Dies ist die häufigste Ursache für einen stummen Bot. Der Prozess läuft, das Gateway ist verbunden, aber Hermes ignoriert Ihre Nachrichten absichtlich, weil Ihre ID nicht auf der Liste steht.

3. Ist das Bot-Token abgelaufen oder widerrufen worden?

BotFather erlaubt es Ihnen, Tokens zu widerrufen. Wenn Sie das Token neu generiert haben, nachdem Sie es zu Hermes hinzugefügt haben, funktioniert das alte Token nicht mehr. Prüfen Sie BotFather mit /mybots, wählen Sie Ihren Bot aus, gehen Sie zu API Token und überprüfen Sie, ob das Token in Ihrer Konfiguration übereinstimmt.

4. Befindet sich der Bot bereits in einem anderen Chat?

Telegram-Bots antworten in dem konkreten Chat, in dem sie Nachrichten empfangen. Wenn Sie den Bot zuvor zu einer Gruppe hinzugefügt haben und Hermes so konfiguriert ist, dass es auf Gruppennachrichten anders reagiert, müssen Sie die Konversation möglicherweise in einem Direktchat (DM) mit dem Bot beginnen.

Problem: Fehler „Unauthorized" in den Logs

Dieser Fehler bedeutet, dass das Token entweder ungültig ist oder widerrufen wurde. Die Lösung besteht immer darin, das Token in BotFather neu zu generieren und Ihre Hermes-Konfiguration mit dem neuen Wert zu aktualisieren.

In BotFather:

1. Senden Sie /mybots.
2. Wählen Sie Ihren Bot aus.
3. Gehen Sie zu API Token → Revoke current token.
4. Kopieren Sie das neue Token.
5. Aktualisieren Sie config.yaml oder das Anmeldedaten-Formular im Hermify-Dashboard.
6. Starten Sie Hermes (oder die Hermify-Laufzeitumgebung) neu.

Problem: Der Bot antwortet einmal und verstummt dann

Das bedeutet normalerweise, dass der Hermes-Prozess gestoppt wurde oder das Gateway die Verbindung verloren hat. Häufige Ursachen:

Der Prozess wurde beendet. Bei lokalen Bereitstellungen oder günstigem Shared Hosting werden Prozesse beendet, wenn der Speicher knapp wird oder der Host Container recycelt. Prüfen Sie Ihre Prozess-Logs auf einen Absturz oder ein OOM-Ereignis (Out of Memory).

Die WSL2-Sitzung wurde beendet. Wenn Sie Hermes innerhalb von WSL2 ausführen, stoppt das Schließen des Terminals den Prozess. Im WSL2-Leitfaden erfahren Sie, wie Sie Hermes dauerhaft ausführen.

Die Telegram-Polling-Schleife ist abgelaufen. Das Hermes-Gateway verwendet Long-Polling, um Telegram-Nachrichten zu empfangen. Gelegentlich bricht die Verbindung ab und wird nicht automatisch wiederhergestellt. Ein Neustart des Gateways (hermes gateway restart) behebt dies.

Ein Modellfehler hat einen Absturz verursacht. Wenn die LLM-API einen Fehler zurückgegeben hat (Rate-Limit, erschöpftes Kontingent, fehlerhafte Antwort), beenden manche Versionen von Hermes die Sitzung, anstatt sich zu erholen. Prüfen Sie die Terminalausgabe oder die Logs auf eine kürzliche Fehlermeldung, bevor die Stille begann.

Problem: Nachrichten kommen an, aber der Agent ignoriert den Inhalt

Dies unterscheidet sich von einem stummen Bot. Der Bot empfängt Nachrichten, aber die Antworten des Agenten erscheinen falsch oder leer.

Wahrscheinlichste Ursache: Das Kontextfenster des Modells ist voll. Hermes liest Ihre MEMORY.md und den Konversationsverlauf in jeden Prompt ein. Wenn der kombinierte Kontext zu lang für das Fenster des Modells ist, erhält das Modell einen abgeschnittenen Prompt und die Antwortqualität verschlechtert sich oder wird leer.

Lösungen:

• Wechseln Sie zu einem Modell mit einem größeren Kontextfenster (Claude und Gemini unterstützen 128k+).
• Kürzen Sie Ihre MEMORY.md manuell, wenn sie sehr groß geworden ist.
• Verwenden Sie hermes memory compact, falls in Ihrer Version verfügbar, um den Speicher zusammenzufassen und zu komprimieren.

Weniger wahrscheinliche Ursache: Die Liste der zugelassenen Benutzer hat ein Teilstring-Übereinstimmungsproblem. Wenn Ihre Konfiguration der zugelassenen Benutzer 12345 enthält und Ihre tatsächliche Benutzer-ID 123456789 lautet, stimmt Hermes nicht korrekt überein. Überprüfen Sie die vollständige numerische ID, nicht eine gekürzte Version.

Problem: Funktioniert lokal einwandfrei, kaputt nach der Bereitstellung

Die häufigste Ursache hier ist eine Diskrepanz zwischen der Umgebung, in der Sie getestet haben, und der Serverumgebung.

Prüfen Sie diese Dinge der Reihe nach:

1. Das Token ist in der Serverkonfiguration korrekt, nicht in der lokalen Konfiguration. Es ist leicht, die falsche Datei zu aktualisieren.
2. Der Server kann die API von Telegram erreichen. Manche Hosting-Anbieter blockieren ausgehende Verbindungen. Testen Sie mit curl https://api.telegram.org/bot<YOUR_TOKEN>/getMe vom Server aus.
3. Der Hermes-Prozess ist erfolgreich gestartet. Prüfen Sie die Container- oder Prozess-Logs auf Startfehler.
4. Das Speicherverzeichnis ist eingebunden. Wenn Sie Docker verwenden, stellen Sie sicher, dass das Daten-Volume angehängt ist. Ein Agent, der ohne sein Datenverzeichnis startet, verhält sich seltsam.

Das alles mit verwaltetem Hosting überspringen

Der Grund, warum die meisten Menschen auf Telegram-Konfigurationsprobleme stoßen, ist, dass sie die Bereitstellung selbst verwalten und gleichzeitig mit Tokens, Konfigurationsdateien, Prozessen und Serverumgebungen jonglieren.

Hermify ist speziell um dieses Problem herum konzipiert. Der Onboarding-Ablauf übernimmt die Telegram-Verdrahtung: Sie geben das Bot-Token und die zugelassenen Benutzer-IDs einmal an, und die Plattform speichert sie verschlüsselt, injiziert sie in die Laufzeitumgebung und verwaltet den Gateway-Prozess.

Wenn der Bot auf Hermify nicht mehr antwortet, debuggen Sie nicht das Gateway, sondern prüfen die Statuskarte im Dashboard und lösen bei Bedarf einen Neustart aus. Die Betriebsschleife ist Dashboard-basiert, nicht SSH-basiert.

Das ist die wichtigste Sache, die verwaltetes Telegram-Hosting ändert: nicht die Telegram-Konfiguration selbst, sondern wer dafür verantwortlich ist, sie funktionsfähig zu halten. Sie können diesen Ansatz direkt mit einer selbst verwalteten VPS-Einrichtung im Vergleich zwischen Hosting und Selbst-Hosting vergleichen.