Hermes Agent auf Slack einrichten (Socket Mode)

Warum Hermes Agent in Slack betreiben

Wenn Ihr Team ohnehin schon in Slack lebt, sollte auch Ihr KI-Agent dort leben. Browser-Tabs und eigenständige Dashboards verlieren den Kontext, den Channels, Threads und Direktnachrichten bereits kostenlos liefern: wer fragt, worüber gerade gesprochen wurde und wo die Antwort landen soll.

Hermes Agent bringt erstklassige Slack-Unterstützung über Socket Mode mit, sodass die Laufzeitumgebung auf Ihrem Laptop, auf einem $5-VPS oder hinter einer Unternehmens-Firewall sitzen und trotzdem Nachrichten in Echtzeit streamen kann. Es gibt keinen öffentlichen Webhook freizugeben, keinen Reverse-Proxy zu warten und keinen eingehenden Port zu öffnen. Der Agent baut die Verbindung nach außen zu Slack auf, hält einen WebSocket offen und liefert jede Nachricht und Antwort über diesen einen Kanal aus.

Diese Anleitung führt Sie durch die gesamte Einrichtung von Anfang bis Ende: das Erstellen der Slack-App aus dem mitgelieferten Manifest, das Generieren von Bot- und App-Level-Tokens, das Einrichten von Home-Channel und Allowlist, das Starten des Gateways sowie die Fehlerquellen, die Erstbereitstellungen als Erstes treffen.

Was Sie brauchen, bevor Sie beginnen

Eine saubere Slack-Bereitstellung benötigt fünf Dinge:

Einen Workspace, in dem Sie die Berechtigung haben, Apps zu installieren. Die meisten Workspaces verlangen standardmäßig, dass ein Administrator Installationen genehmigt - prüfen Sie Settings & administration → Workspace settings → Permissions, falls Sie kein Administrator sind.
Eine laufende Hermes-Agent-Installation. Der Hermes Agent Docker-Leitfaden beschreibt den saubersten Weg, eine in Betrieb zu nehmen; falls Sie unter Windows arbeiten, ist das WSL2-Setup das Äquivalent.
Einen Schlüssel eines Modell-Anbieters. Anthropic, OpenAI, OpenRouter und jeder OpenAI-kompatible Endpunkt funktionieren. Die Laufzeitumgebung nutzt diesen, um die Nachrichten tatsächlich zu beantworten.
Ihre numerische Slack-Benutzer-ID für die Allowlist (mehr dazu weiter unten).
Etwa 15 Minuten für die erste Installation. Spätere erneute Bereitstellungen dauern unter einer Minute.

Schritt 1 - Das Slack-App-Manifest generieren

Slack-Apps werden durch ein YAML-Manifest definiert, das Scopes, Event-Subscriptions, Slash-Befehle und Socket Mode in einem Rutsch deklariert. Hermes liefert ein Manifest, das auf seinen integrierten Slack-Handler zugeschnitten ist, sodass Sie die Liste der Scopes nicht von Hand zusammenstellen müssen:

hermes slack manifest --write ./hermes-slack-manifest.yaml

Öffnen Sie https://api.slack.com/apps, klicken Sie auf Create New App, wählen Sie From an app manifest, wählen Sie Ihren Workspace aus und fügen Sie den Inhalt von hermes-slack-manifest.yaml ein. Slack zeigt Ihnen eine Vorschau dessen, was genau erstellt wird. Bestätigen Sie.

Das Manifest aktiviert Socket Mode, deklariert jedes Event, das Hermes abonniert (app_mention, message.im, message.channels, message.groups, message.mpim), registriert die integrierten Slash-Befehle und fordert die Bot-Scopes an, die die Laufzeitumgebung tatsächlich nutzt:

app_mentions:read - hören, wenn jemand den Bot in einem Channel per @-Mention erwähnt.
chat:write - Antworten senden und Threads starten.
im:history, im:read, im:write - Direktnachrichten-Konversationen.
channels:history, groups:history, mpim:history - Kontext in öffentlichen Channels, privaten Channels und Gruppen-DMs lesen, zu denen der Bot eingeladen ist.
users:read - Benutzer-IDs in Anzeigenamen auflösen, für die Allowlist-Oberfläche und Audit-Logs.
commands - die /hermes-Slash-Befehlsfläche registrieren.

Das Manifest nach der Installation zu bearbeiten ist in Ordnung. Scopes nach der Installation hinzuzufügen ist der Vorgang, der die meisten stillen Fehler verursacht - siehe den Abschnitt zur Fehlerbehebung weiter unten.

Schritt 2 - Den Bot-Token und den App-Level-Token generieren

Slack stellt für eine Socket-Mode-App zwei verschiedene Tokens aus, und Hermes benötigt beide:

Bot-Token (xoxb-…)

Gehen Sie in den App-Einstellungen zu OAuth & Permissions → Install to Workspace. Genehmigen Sie die Scopes aus dem Manifest. Slack stellt einen xoxb-…-Token aus. Kopieren Sie ihn.

App-Level-Token (xapp-…)

Gehen Sie zu Basic Information → App-Level Tokens → Generate Token and Scopes. Benennen Sie ihn (z. B. hermes-socket), fügen Sie den Scope connections:write hinzu und klicken Sie auf Generate. Slack stellt einen xapp-…-Token aus. Kopieren Sie ihn.

Die beiden Tokens erfüllen unterschiedliche Aufgaben. Der Bot-Token authentifiziert Slack-API-Aufrufe (eine Nachricht senden, den Channel-Verlauf lesen). Der App-Token authentifiziert den Socket-Mode-WebSocket selbst - ohne ihn startet die Laufzeitumgebung, verbindet sich aber nie mit Slack, und der Bot bleibt für immer stumm.

Schritt 3 - Ihre numerische Slack-Benutzer-ID finden

Hermes Agent antwortet nur auf Benutzer-IDs, die in SLACK_ALLOWED_USERS auftauchen. Dies ist die wichtigste einzelne Sicherheitsmaßnahme in der gesamten Einrichtung, und sie erwartet numerische IDs, keine @handles oder Anzeigenamen.

Klicken Sie in Slack auf Ihren Avatar → Profile → das Kebab-Menü (⋮) → Copy member ID. Die ID sieht aus wie U01ABCD2EFG. Wiederholen Sie dies für jedes Teammitglied, das Sie autorisieren möchten.

Die Allowlist auszulassen ist dasselbe, als würden Sie Ihren Anbieter-API-Schlüssel an jeden in Ihrem Workspace veröffentlichen. Wenn eine Hermes-Instanz von einem öffentlichen Slack-Workspace aus erreichbar ist und die Allowlist leer ist, verbraucht jede Nachricht in jedem Channel, zu dem der Bot eingeladen ist, Ihre Tokens.

Schritt 4 - Die Hermes-Laufzeitumgebung konfigurieren

Öffnen Sie ~/.hermes/.env (oder welche .env auch immer Ihr Container liest) und fügen Sie hinzu:

SLACK_BOT_TOKEN=xoxb-...your-bot-token...
SLACK_APP_TOKEN=xapp-...your-app-token...
SLACK_ALLOWED_USERS=U01ABCD2EFG,U02HIJK3LMN
SLACK_HOME_CHANNEL=C04XYZ123AB

Ein Hinweis zu jedem Eintrag:

SLACK_BOT_TOKEN - der xoxb-…-Token aus Schritt 2.
SLACK_APP_TOKEN - der xapp-…-Token. Diesen zu vergessen ist die häufigste Fehlerquelle und sie erzeugt keine Fehlermeldung - das Gateway öffnet den WebSocket einfach nie.
SLACK_ALLOWED_USERS - kommagetrennte Liste numerischer IDs. Der Bot ignoriert alle anderen, einschließlich Administratoren und Bot-Konten.
SLACK_HOME_CHANNEL (optional) - die Channel-ID für proaktive Nachrichten, geplante Zusammenfassungen und durch Skills ausgelöste Benachrichtigungen. Klicken Sie in Slack mit der rechten Maustaste auf den Channel → View channel details → kopieren Sie die Channel-ID am unteren Rand. Wenn nicht gesetzt, geht die proaktive Ausgabe an die DM des Bots mit dem ersten erlaubten Benutzer.

Führen Sie nach dem Speichern chmod 600 ~/.hermes/.env aus. Beide Tokens gewähren Schreibzugriff auf Ihren Workspace; behandeln Sie sie wie SSH-Schlüssel.

Ein Terminal, das die Hermes-.env-Datei mit ausgefüllten Werten für SLACK_BOT_TOKEN, SLACK_APP_TOKEN, SLACK_ALLOWED_USERS und SLACK_HOME_CHANNEL zeigt, mit auf 600 gehärteten Dateiberechtigungen

Schritt 5 - Das Gateway starten

Starten Sie das Gateway neu, damit es die neue Umgebung übernimmt:

hermes gateway restart

Oder, mit Docker Compose:

docker compose restart gateway

Verfolgen Sie die Logs und achten Sie auf den Slack-Handshake:

hermes gateway logs --follow

Sie achten auf zwei Zeilen, in dieser Reihenfolge:

slack: connecting to Socket Mode
slack: connected as @your-bot-name (workspace: your-workspace)

Wenn Sie nur die erste Zeile sehen und danach nichts, ist der xapp-…-Token falsch, fehlt oder es fehlt ihm der Scope connections:write. Wenn Sie keine von beiden sehen, übernimmt das Gateway die neue .env nicht - bestätigen Sie den Dateipfad, den die Laufzeitumgebung liest.

Schritt 6 - Den Bot einladen und die erste Nachricht senden

In jedem Channel, in dem der Bot teilnehmen soll:

/invite @your-bot-name

Der Bot sieht nur Nachrichten in Channels, zu denen er eingeladen wurde. Dies ist eine Slack-seitige Einschränkung, keine von Hermes - selbst wenn channels:history gewährt wurde, liest der Bot keinerlei Verlauf, bis Sie ihn per /invite einladen.

Senden Sie dem Bot eine DM oder erwähnen Sie ihn per @-Mention im Channel. Hermes antwortet in derselben Konversation, mit vollständig erhaltenem Speicher- und Skill-Kontext. Von hier an funktioniert jede Hermes-Fähigkeit - persistenter Speicher, geplante Aufgaben, eigene Skills - genau so, wie sie es auf der Telegram-Auslieferungsoberfläche tut.

Ein Slack-Channel, der einen Thread zwischen einem Benutzer und dem Hermes-Bot zeigt, wobei der Bot kontextbezogen antwortet und neben dem Namen des Bots ein kleiner grüner Online-Indikator zu sehen ist

Die Fehlerquellen, die zuerst zuschlagen

Fünf Fehler machen fast jeden „Slack-Setup ist kaputt"-Support-Thread aus:

Den xapp-…-Token vergessen. Socket Mode verbindet sich ohne ihn überhaupt nicht, und Slacks App-Dashboard warnt Sie nicht. Die Lösung ist eine Zeile in der .env und ein Neustart.

Scopes nach der Installation hinzufügen, ohne neu zu installieren. Neue Scopes erscheinen auf der OAuth-Seite, werden dem Bot aber erst tatsächlich gewährt, wenn Sie auf Reinstall to Workspace klicken. Der Bot behält stillschweigend den alten Scope-Satz bei. Wenn die Laufzeitumgebung missing_scope-Fehler protokolliert, ist das der Grund.

Bot nicht zum Channel eingeladen. Ein Bot mit channels:history liest trotzdem keinen Verlauf, bis er eingeladen wird. Der Bot reagiert sofort auf DMs, bleibt in Channels aber stumm, bis /invite @your-bot-name ausgeführt wird.

Leere SLACK_ALLOWED_USERS. Die Voreinstellung ist, alle zu ignorieren. Dies ist eine bewusste sichere Voreinstellung, aber sie lässt den Bot für einen Erstanwender, der vergessen hat, seine eigene ID hinzuzufügen, kaputt aussehen.

Zwei Gateway-Prozesse gegen dasselbe Datenvolume. Wenn Sie ein Gateway im Slack-Modus und ein Gateway im Telegram-Modus gegen dasselbe /data-Verzeichnis starten, beschädigen sich Nachrichtenreihenfolge und Speicherschreibvorgänge innerhalb von Minuten gegenseitig. Betreiben Sie ein einziges Gateway mit sowohl gesetzten SLACK_*- als auch TELEGRAM_*-Blöcken in der .env, wenn Sie beide Oberflächen möchten - die Laufzeitumgebung multiplext beide nativ.

Wenn ein Problem Slack-förmig aussieht, sich die Symptome aber allgemein anfühlen, behandelt der Telegram-Leitfaden zur Fehlerbehebung die zugrunde liegenden Gateway- und Anbieter-Probleme ausführlicher - die meisten sind oberflächenunabhängig.

Slack und Telegram im direkten Vergleich

Aspekt	Slack	Telegram
Einrichtungszeit	15 Min. (Manifest + 2 Tokens)	5 Min. (ein BotFather-Token)
Erreichbarkeit	Hinter Firewall (Socket-Mode-WebSocket)	Hinter Firewall (Long-Poll)
Allowlist-Feld	`SLACK_ALLOWED_USERS` (numerische IDs)	`TELEGRAM_ALLOWED_USERS` (numerische IDs)
Am besten für	Team-Workflows, Channel-Kontext, Threads	Persönliche Nutzung, Mobile-First, Sprachmodus
Threading	Nativ	Nur Zitatantworten
Dateihandhabung	Integrierte Uploads + Vorschauen	Integrierte Uploads + Vorschauen

Die beiden Oberflächen schließen sich nicht aus. Dieselbe Hermes-Laufzeitumgebung kann an beide gleichzeitig ausliefern - nützlich, wenn derselbe Agent einen persönlichen Telegram-Chat und einen Team-Slack-Channel aus demselben Speicher bedient.

Sparen Sie sich das Slack-Klempnern

Die Slack-Schritte an sich sind unkompliziert, aber Sie sind weiterhin für den Host verantwortlich: Backups, TLS für das Dashboard, Log-Rotation und den Aktualisierungsrhythmus. Für eine Installation im persönlichen Maßstab ist das in Ordnung. Für ein Team, das den Bot innerhalb von Minuten live haben möchte und danach keinen betrieblichen Aufwand will, stellt Hermify eine verwaltete Hermes-Laufzeitumgebung bereit, verschlüsselt Ihre Slack-Tokens im Ruhezustand, stellt die Allowlist in einer Oberfläche statt einer .env bereit und hält die Socket-Mode-Verbindung auf einem dauerhaften Server gesund.

Sie bringen den Slack-Workspace und einen Modell-Anbieter-Schlüssel mit; die Plattform kümmert sich um alles darunter. Wenn Sie diesen Kompromiss abwägen, führt Sie der Vergleich selbst gehostet vs. verwaltet durch die Kosten- und Wartungszahlen.