Hermes Agent mit Telegram verbinden: KI-Bot von überall steuern

Über Telegram lässt sich der selbst­ge­hos­te­te Hermes Agent un­ab­hän­gig vom ver­wen­de­ten Endgerät aus der Ferne steuern. Der Zugriff erfolgt über einen eigenen Bot und wird durch die Freigabe be­stimm­ter Telegram-User-IDs ab­ge­si­chert; für eine dau­er­haf­te Er­reich­bar­keit kann das Gateway auf einem Linux-Server oder VPS betrieben werden.

Wie lässt sich Hermes Agent mit Telegram verbinden?

Das Hermes Agent Messaging-Gateway ist die native Schnitt­stel­le, die den selbst­ge­hos­te­ten autonomen Hermes Agent mit externen Chat-Platt­for­men wie Telegram verbindet. Es nimmt Nach­rich­ten entgegen, ordnet sie einer Sitzung zu, übergibt sie an den Agenten und sendet dessen Antworten an­schlie­ßend an den je­wei­li­gen Telegram-Chat zurück.

Durch diese Ver­bin­dung können Sie Hermes Agent über die Telegram-App auf dem Smart­phone, Tablet oder einem anderen Computer an­spre­chen. Der KI-Agent selbst läuft weiterhin auf Ihrem eigenen Rechner oder Server. Telegram dient lediglich als leicht er­reich­ba­re Be­dien­ober­flä­che, über die Nach­rich­ten und Antworten aus­ge­tauscht werden.

Die Ein­rich­tung besteht aus drei we­sent­li­chen Kom­po­nen­ten: einem Telegram-Bot, einem geheimen Bot-Token und einer Freigabe Ihrer per­sön­li­chen Telegram-User-ID. An­schlie­ßend wird das Messaging-Gateway von Hermes gestartet und bei Bedarf als dau­er­haf­ter Hin­ter­grund­dienst auf einem Linux-Server ein­ge­rich­tet.

Vor­aus­set­zun­gen für die Telegram-Ver­bin­dung

Bevor Sie beginnen, sollte Hermes Agent bereits in­stal­liert und grund­sätz­lich funk­ti­ons­fä­hig sein. Öffnen Sie dazu ein Terminal und starten Sie Hermes zunächst ohne Telegram:

hermes

Stellen Sie eine einfache Frage und prüfen Sie, ob der Agent antwortet.

Zu­sätz­lich benötigen Sie:

• ein Telegram-Konto,
• Zugriff auf das Terminal des Rechners, auf dem Hermes läuft,
• einen bereits ein­ge­rich­te­ten Mo­dell­an­bie­ter,
• eine In­ter­net­ver­bin­dung auf dem Hermes-System.

Telegram-Bot über BotFather erstellen

Ein Telegram-Bot ist ein spe­zi­el­les Telegram-Konto, das nicht von einer Person, sondern von einer Software gesteuert wird. Für die Er­stel­lung stellt Telegram den of­fi­zi­el­len Ver­wal­tungs­bot @BotFather bereit. Öffnen Sie Telegram und suchen Sie nach dem Account @BotFather. Achten Sie darauf, tat­säch­lich den of­fi­zi­el­len BotFather zu öffnen. Senden Sie ihm an­schlie­ßend den Befehl:

/newbot

BotFather führt Sie nun durch die Er­stel­lung.

1. An­zei­ge­na­men festlegen: Zuerst fragt BotFather nach einem Namen für den Bot. Dieser Name wird später im Telegram-Chat angezeigt. Der An­zei­ge­na­me muss nicht eindeutig sein und kann später geändert werden.
2. Ein­deu­ti­gen Be­nut­zer­na­men wählen: Danach benötigt der Bot einen ein­deu­ti­gen Telegram-Be­nut­zer­na­men. Dieser muss mit „bot“ enden, bei­spiels­wei­se „mein_hermes_agent_bot“. Ist der ge­wünsch­te Name bereits vergeben, müssen Sie eine andere Variante auswählen.
3. Bot-Token kopieren: Nach er­folg­rei­cher Er­stel­lung sendet BotFather einen so­ge­nann­ten API-Token. Der Token weist Hermes gegenüber Telegram als Betreiber dieses Bots aus. Er funk­tio­niert daher ähnlich wie ein Passwort.

Eigene Telegram-User-ID ermitteln

Neben dem Token benötigt Hermes Ihre per­sön­li­che Telegram-User-ID. Dabei handelt es sich um eine feste nu­me­ri­sche Kennung. Die User-ID ist nicht mit Ihrem sicht­ba­ren Telegram-Namen oder Ihrem Be­nut­zer­na­men identisch. Ein Be­nut­zer­na­me kann geändert werden, während Hermes für seine Zu­griffs­kon­trol­le die nu­me­ri­sche ID verwendet.

Öffnen Sie in Telegram den Bot @user­in­fo­bot und starten Sie den Chat be­zie­hungs­wei­se senden Sie eine beliebige Nachricht. Der Bot antwortet mit ver­schie­de­nen In­for­ma­tio­nen zu Ihrem Konto. Kopieren Sie daraus den Wert, der als User-ID be­zeich­net wird.

Benötigte Telegram-Daten im Überblick

Für eine per­sön­li­che Hermes-In­stal­la­ti­on tragen Sie nor­ma­ler­wei­se nur Ihre eigene User-ID ein. Sollen später mehrere Personen Zugriff erhalten, können deren IDs durch Kommas getrennt hin­ter­legt werden.

Hermes Agent Gateway über die CLI kon­fi­gu­rie­ren

Hermes besitzt einen in­ter­ak­ti­ven As­sis­ten­ten, der die Telegram-Kon­fi­gu­ra­ti­on Schritt für Schritt im CLI abfragt. Öffnen Sie auf dem Rechner, auf dem Hermes Agent in­stal­liert ist, ein Terminal und geben Sie folgenden Befehl ein:

hermes gateway setup

Der Kon­fi­gu­ra­ti­ons­as­sis­tent zeigt die un­ter­stütz­ten Messaging-Platt­for­men an. Wählen Sie mit den Pfeil­tas­ten Telegram aus und be­stä­ti­gen Sie Ihre Auswahl mit der Ein­ga­be­tas­te. An­schlie­ßend werden die folgenden In­for­ma­tio­nen abgefragt:

• die ge­wünsch­te Plattform,
• das Telegram-Bot-Token,
• die erlaubten Telegram-User-IDs.

Fügen Sie beim Bot-Token den Wert ein, den Sie von BotFather erhalten haben. Bei den erlaubten User-IDs tragen Sie Ihre zuvor er­mit­tel­te nu­me­ri­sche Telegram-ID ein. Der Setup-Assistent speichert diese Angaben in der Hermes-Kon­fi­gu­ra­ti­on. Das Bot-Token stellt die Ver­bin­dung zu dem von Ihnen er­stell­ten Telegram-Bot her.

User-ID als wichtige Si­cher­heits­bar­rie­re

Hermes Agent kann je nach Kon­fi­gu­ra­ti­on auf Dateien zugreifen, Programme ausführen, Ter­mi­nal­be­feh­le verwenden und weitere Werkzeuge aufrufen. Ein frei zu­gäng­li­cher Bot wäre deshalb deutlich riskanter als ein ge­wöhn­li­cher FAQ-Chatbot. Hermes verwendet für das Messaging-Gateway eine „Default-Deny“-Logik: Ist weder eine Frei­ga­be­lis­te noch eine aus­drück­li­che globale Freigabe ein­ge­rich­tet, werden un­be­kann­te User nicht zur Aus­füh­rung durch den Agenten zu­ge­las­sen. Erst wenn eine User-ID frei­ge­ge­ben wurde, darf das ent­spre­chen­de Telegram-Konto mit Hermes in­ter­agie­ren. Für einen aus­schließ­lich privat genutzten Bot ist die feste User-ID-Liste die ein­fachs­te und nach­voll­zieh­bars­te Ab­si­che­rung.

Vermeiden Sie ins­be­son­de­re folgende Ein­stel­lung: GATEWAY_ALLOW_ALL_USERS=true. Sie würde die globale Zu­gangs­be­schrän­kung bewusst aufheben. Für einen Hermes Agent mit System- und Ter­mi­nal­zu­griff sollte diese Ein­stel­lung nur in besonders kon­trol­lier­ten Um­ge­bun­gen verwendet werden.

Mehrere Personen freigeben

Sollen mehrere ver­trau­ens­wür­di­ge Personen auf denselben Bot zugreifen, tragen Sie die Telegram-IDs durch Kommas getrennt ein:

TELEGRAM_ALLOWED_USERS=123456789,987654321,555555555

Alle ein­ge­tra­ge­nen Personen erhalten in der Stan­dard­kon­fi­gu­ra­ti­on grund­sätz­lich Zugriff auf denselben Agenten und dessen ver­füg­ba­re Werkzeuge. Eine User-ID sollte daher nur auf­ge­nom­men werden, wenn die be­tref­fen­de Person tat­säch­lich Zugriff auf das System erhalten soll. Hermes verwaltet Gespräche zwar in ge­trenn­ten Sitzungen, die zugrunde liegenden Agen­ten­funk­tio­nen bleiben jedoch gemeinsam verfügbar.

Telegram-Gateway ak­ti­vie­ren und Ver­bin­dung testen

Nach der Kon­fi­gu­ra­ti­on sollte das Gateway zunächst testweise direkt im Terminal gestartet werden. Verwenden Sie dafür:

hermes gateway run

Der Gateway-Prozess läuft nun im Vor­der­grund. Das bedeutet, dass Sie die laufenden Status- und Feh­ler­mel­dun­gen direkt im Terminal sehen. Lassen Sie dieses Fenster während des Tests geöffnet. Bei er­folg­rei­cher Ver­bin­dung sollte eine Meldung er­schei­nen, die darauf hinweist, dass der Telegram-Adapter verbunden wurde. Öffnen Sie an­schlie­ßend in Telegram den von Ihnen er­stell­ten Bot und senden Sie eine Nachricht.

Führen Sie nach­ein­an­der folgende Tests durch:

1. Sta­tus­be­fehl senden: Senden Sie /status. Hermes sollte nun In­for­ma­tio­nen zur aktuellen Sitzung zu­rück­ge­ben.
2. Normale Frage stellen: Stellen Sie eine Frage an Ihren Agenten, zum Beispiel: „Welche System-Tools stehen dir aktuell zur Verfügung? Nenne nur die Namen und führe noch keines davon aus.“ Damit prüfen Sie, ob eine ge­wöhn­li­che Nachricht an Hermes über­tra­gen, dort ver­ar­bei­tet und die Antwort wieder an Telegram zu­rück­ge­sen­det wird.
3. Neue Un­ter­hal­tung starten: Senden Sie /new. Dieser Befehl startet eine neue Sitzung ohne den bis­he­ri­gen Ge­sprächs­kon­text. Antwortet der Bot auf diese Nach­rich­ten, funk­tio­niert die Zwei-Wege-Kom­mu­ni­ka­ti­on.

Beenden Sie den Testlauf im Terminal mit der Tas­ten­kom­bi­na­ti­on Strg+C.

Gateway als Hin­ter­grund­dienst in­stal­lie­ren

Damit Sie nicht dauerhaft ein offenes Ter­mi­nal­fens­ter benötigen, können Sie das Gateway als Dienst in­stal­lie­ren:

hermes gateway install

Danach lässt es sich mit folgenden Befehlen steuern:

hermes gateway start
hermes gateway stop
hermes gateway status

Nach Än­de­run­gen an der Telegram-Kon­fi­gu­ra­ti­on empfiehlt sich ein Neustart:

hermes gateway stop
hermes gateway start

Al­ter­na­tiv steht auch ein direkter Neu­start­be­fehl zur Verfügung:

hermes gateway restart

hermes gateway start startet den zuvor in­stal­lier­ten Hin­ter­grund­dienst. Ist noch kein Dienst in­stal­liert, verwenden Sie daher zuerst hermes gateway install. Der Befehl hermes gateway run ist dagegen für einen direkt sicht­ba­ren Testlauf im Vor­der­grund vor­ge­se­hen.

Über­prü­fen Sie an­schlie­ßend den Zustand:

hermes gateway status

Senden Sie danach erneut eine Nachricht an den Telegram-Bot. Er sollte nun auch antworten, obwohl kein Hermes-Ter­mi­nal­fens­ter mehr geöffnet ist.

Was tun, wenn der Bot nicht antwortet?

Führen Sie als ersten Dia­gno­se­schritt folgenden Befehl aus:

hermes doctor

Hermes überprüft damit unter anderem die In­stal­la­ti­on, wichtige Kon­fi­gu­ra­ti­ons­wer­te und benötigte Ab­hän­gig­kei­ten. Gefundene Probleme werden zusammen mit möglichen Lösungen im Terminal angezeigt. Einige Fehler kann Hermes auf Wunsch au­to­ma­tisch zu beheben versuchen:

hermes doctor --fix

Prüfen Sie an­schlie­ßend, ob das Gateway läuft. Antwortet der Bot weiterhin nicht, kon­trol­lie­ren Sie die Ein­rich­tung manuell:

Prüfen Sie der Reihe nach:

• Ist der Bot-Token voll­stän­dig und ohne zu­sätz­li­che Leer­zei­chen ein­ge­tra­gen?
• Stimmt die nu­me­ri­sche User-ID?
• Wurde tat­säch­lich die User-ID und nicht der Telegram-Be­nut­zer­na­me ein­ge­tra­gen?
• Läuft das Gateway laut hermes gateway status?
• Funk­tio­niert Hermes direkt im Terminal ohne Telegram?
• Hat der Rechner eine aktive In­ter­net­ver­bin­dung?

Für einen sicht­ba­ren Feh­ler­test können Sie den Hin­ter­grund­dienst stoppen und das Gateway wieder direkt im Terminal starten:

hermes gateway stop
hermes gateway run

Fehler beim Ver­bin­dungs­auf­bau werden dann un­mit­tel­bar im Terminal angezeigt.

Hermes Agent mit Telegram rund um die Uhr betreiben

Läuft Hermes auf Ihrem Laptop oder Desktop-PC, ist der Telegram-Bot nur er­reich­bar, solange der Rechner ein­ge­schal­tet, mit dem Internet verbunden und das Gateway aktiv ist. Wird das Gerät her­un­ter­ge­fah­ren oder in den Ru­he­zu­stand versetzt, kann Hermes keine Telegram-Nach­rich­ten mehr ver­ar­bei­ten.

Für einen dau­er­haf­ten 24/7-Betrieb kann Hermes deshalb auf einem Linux-Server oder Virtual Private Server, kurz VPS, in­stal­liert werden. Ein VPS ist ein dauerhaft er­reich­ba­rer vir­tu­el­ler Computer in einem Re­chen­zen­trum. Sie greifen in der Regel über eine ver­schlüs­sel­te SSH-Ver­bin­dung auf dessen Terminal zu.

Emp­foh­le­ner Ablauf für den Umzug

In­stal­lie­ren Sie Hermes zunächst auf dem Linux-Server und richten Sie dort den Mo­dell­an­bie­ter ein. Testen Sie an­schlie­ßend einen normalen Hermes-Chat. Führen Sie danach erneut den Gateway-As­sis­ten­ten aus:

hermes gateway setup

Sie können dasselbe Telegram-Bot-Token und dieselbe frei­ge­ge­be­ne User-ID verwenden. Stoppen Sie jedoch das lokale Gateway, bevor Sie den Bot dauerhaft auf dem Server starten. Dadurch vermeiden Sie, dass zwei Hermes-In­stal­la­tio­nen gleich­zei­tig versuchen, denselben Bot zu bedienen.

Auf einem dauerhaft laufenden Linux-Server empfiehlt sich ein Sys­tem­dienst, der bereits beim Hoch­fah­ren des Servers gestartet wird:

sudo hermes gateway install --system
sudo hermes gateway start --system

Den Status prüfen Sie mit:

sudo hermes gateway status --system

Die aktuellen Pro­to­koll­mel­dun­gen lassen sich mit folgendem Befehl anzeigen:

journalctl -u hermes-gateway -f

systemd sorgt dafür, dass das Gateway im Hin­ter­grund läuft und nach einem Neustart des Servers wieder gestartet werden kann. Hermes un­ter­schei­det dabei zwischen einem be­nut­zer­be­zo­ge­nen Dienst für Ar­beits­rech­ner und einem sys­tem­wei­ten Dienst für dauerhaft laufende, mo­ni­tor­lo­se Server. Für einen VPS sollten Sie Hermes nicht unnötig mit Ad­mi­nis­tra­tor­rech­ten betreiben. Verwenden Sie möglichst einen eigenen Linux-User ohne un­ein­ge­schränk­ten Root-Zugriff.

Al­ter­na­ti­ve: Hermes in Docker betreiben

Docker führt An­wen­dun­gen in von­ein­an­der ab­ge­grenz­ten Con­tai­nern aus. Das er­leich­tert die dau­er­haf­te Aus­füh­rung und kann ver­hin­dern, dass Agen­ten­be­feh­le un­mit­tel­bar auf dem ei­gent­li­chen Server-System aus­ge­führt werden. Nach der ein­ma­li­gen Kon­fi­gu­ra­ti­on kann der of­fi­zi­el­le Hermes-Container bei­spiels­wei­se so im Hin­ter­grund gestartet werden:

docker run -d \
    --name hermes \
    --restart unless-stopped \
    -v ~/.hermes:/opt/data \
    nousresearch/hermes-agent gateway run

Die Option --restart unless-stopped sorgt dafür, dass der Container nach einem Absturz oder Server-Neustart wieder gestartet wird, sofern er zuvor nicht bewusst gestoppt wurde. Das ein­ge­bun­de­ne Ver­zeich­nis ~/.hermes speichert Kon­fi­gu­ra­ti­on, Sitzungen und Zu­gangs­da­ten außerhalb des kurz­le­bi­gen Con­tai­ners.

Telegram-Gateway auf dem Server sicher betreiben

Für die Ver­bin­dung über Telegram muss nor­ma­ler­wei­se kein öf­fent­li­cher Server-Port geöffnet werden. Das Hermes-Gateway verwendet stan­dard­mä­ßig Long Polling. Dabei baut Hermes selbst eine aus­ge­hen­de Ver­bin­dung zu Telegram auf und fragt re­gel­mä­ßig nach neuen Nach­rich­ten. Telegram muss daher nicht direkt von außen auf den Server zugreifen.

Wenn Sie aus­schließ­lich Telegram als Be­dien­ober­flä­che verwenden, sollten Sie den internen Hermes-API-Port nicht öf­fent­lich freigeben. Jeder zu­sätz­li­che offene Port macht den Server aus dem Internet er­reich­bar und kann die mögliche An­griffs­flä­che ver­grö­ßern.

Si­cher­heits­check vor dem 24/7-Betrieb

Prüfen Sie vor dem dau­er­haf­ten Start des Gateways folgende Ein­stel­lun­gen:

• Der Telegram-Bot-Token ist nur in der ge­schütz­ten Hermes-Kon­fi­gu­ra­ti­on ge­spei­chert.
• In TELEGRAM_ALLOWED_USERS stehen aus­schließ­lich die nu­me­ri­schen IDs aus­drück­lich be­rech­tig­ter Personen.
• GATEWAY_ALLOW_ALL_USERS ist nicht aktiviert.
• Hermes wird nicht unnötig mit Root- be­zie­hungs­wei­se Ad­mi­nis­tra­tor­rech­ten aus­ge­führt.
• Nicht benötigte Server- und API-Ports bleiben ge­schlos­sen.
• Zu­gangs­da­ten werden weder in öf­fent­li­che Git-Re­po­si­to­ries noch in frei zu­gäng­li­che Pro­to­koll­da­tei­en kopiert.
• Das Be­triebs­sys­tem und Hermes Agent werden re­gel­mä­ßig ak­tua­li­siert.
• Werkzeuge mit weit­rei­chen­dem Datei- oder Ter­mi­nal­zu­griff werden möglichst in einer iso­lier­ten - Umgebung aus­ge­führt.

Für pro­duk­ti­ve In­stal­la­tio­nen empfiehlt sich bei­spiels­wei­se ein iso­lier­tes Terminal-Backend auf Basis von Docker. Dadurch werden vom Agenten aus­ge­führ­te Befehle innerhalb eines Con­tai­ners statt un­mit­tel­bar auf dem ei­gent­li­chen Server aus­ge­führt. Diese Isolation ersetzt jedoch nicht die Telegram-Frei­ga­be­lis­te oder den Schutz des Bot-Tokens, sondern ergänzt beide Si­cher­heits­maß­nah­men.

Fazit

Für die Ver­bin­dung von Hermes Agent mit Telegram benötigen Sie lediglich einen über BotFather er­stell­ten Telegram-Bot, dessen geheimen API-Token und Ihre nu­me­ri­sche Telegram-User-ID. Der Befehl hermes gateway setup führt durch die Kon­fi­gu­ra­ti­on und hin­ter­legt Ihre ID als Zu­griffs­be­schrän­kung. Nach einem ersten Test können Sie das Gateway als Hin­ter­grund­dienst in­stal­lie­ren und dauerhaft ak­ti­vie­ren. Auf einem Linux-Server oder VPS bleibt der Agent dadurch auch er­reich­bar, wenn Ihr eigener Computer aus­ge­schal­tet ist. Ent­schei­dend ist, den Bot-Token geheim zu halten, nur aus­drück­lich erlaubte User-IDs ein­zu­tra­gen und die Sys­tem­werk­zeu­ge des Agenten möglichst von der ei­gent­li­chen Ser­ver­um­ge­bung zu isolieren.