Mattermost Hermes Agent — selbst gehostet | Easy Understand Hermes Agent

Mattermost Hermes Agent — selbst gehostet

Wenn dein Team Mattermost betreibt, kennst du den Reiz: Es sieht aus und fühlt sich an wie Slack, aber der Server — und die Daten — bleiben auf deiner eigenen Infrastruktur. Hermes Agent dockt als Bot daran an und verbindet sich über die REST-API (v4) von Mattermost plus einen WebSocket für Echtzeit-Events, sodass dein Assistent in DMs und Team-Channels antworten kann, ohne dass etwas dein Netzwerk verlässt.

Es gibt keine zusätzliche Bibliothek zu installieren: Der Adapter nutzt aiohttp, das bereits mit Hermes ausgeliefert wird. Er funktioniert sowohl mit der Mattermost Team Edition (kostenlos) als auch mit der Enterprise Edition.

Wie Hermes sich in Mattermost verhält

Wo du mit ihm sprichst	Was passiert
DMs	Hermes antwortet auf jede Nachricht — kein `@mention` nötig. Jede DM bekommt ihre eigene Session.
Channels	Hermes antwortet, wenn du es `@mention`st. Ohne Mention ignoriert es die Nachricht.
Threads	Mit `MATTERMOST_REPLY_MODE=thread` werden Antworten unter deiner Nachricht verschachtelt und bleiben vom übergeordneten Channel isoliert.
Geteilte Channels	Der Session-Verlauf ist standardmäßig pro Benutzer isoliert, sodass zwei Personen in einem Channel kein gemeinsames Transkript teilen.

Das letzte Verhalten wird durch group_sessions_per_user in config.yaml gesteuert:

group_sessions_per_user: true   # each person keeps their own context

Setze es nur dann auf false, wenn du bewusst eine gemeinsame Konversation für den gesamten Channel möchtest. Eine geteilte Session bedeutet, dass alle den Kontextzuwachs und die Token-Kosten teilen, und die lange, tool-lastige Aufgabe einer Person kann den Lauf einer anderen aufblähen oder unterbrechen.

Schritt 1: Bot-Konten aktivieren (Admin-Seite)

Bot-Konten müssen für den Server aktiviert sein, bevor du eines erstellen kannst:

Melde dich bei Mattermost als System Admin an.
Gehe zu System Console → Integrations → Bot Accounts.
Setze Enable Bot Account Creation auf true und klicke dann auf Save.

Kein Admin-Zugang? Bitte deinen Mattermost-Administrator, Bot-Konten zu aktivieren und eines für dich zu erstellen.

Schritt 2: Das Bot-Konto erstellen

Klicke auf das ☰-Menü (oben links) → Integrations → Bot Accounts → Add Bot Account.
Fülle die Details aus: Username wie hermes, Display Name wie Hermes Agent und eine Role — Member reicht aus.
Klicke auf Create Bot Account und kopiere das Token sofort — es wird nur einmal angezeigt. Wenn du es verlierst, musst du es in den Bot-Konto-Einstellungen neu generieren.

⚠️ Teile das Token niemals und committe es nicht in Git. Wer es hat, hat die volle Kontrolle über den Bot.

Möchtest du lieber, dass der Agent als dein eigener Benutzer statt als separater Bot postet? Erstelle ein persönliches Zugriffstoken unter Profile → Security → Personal Access Tokens → Create Token.

Schritt 3: Den Bot in Channels einladen

Der Bot antwortet nur in Channels, in denen er Mitglied ist:

Öffne den Channel → klicke auf den Channel-Namen → Add Members.
Suche nach dem Bot-Benutzernamen (zum Beispiel hermes) und füge ihn hinzu.

Für DMs öffnest du einfach eine Direktnachricht mit dem Bot — keine Einladung nötig.

Schritt 4: Deine Mattermost User ID finden

Hermes verwendet deine User ID — nicht deinen Benutzernamen — um zu entscheiden, wer mit dem Bot sprechen darf:

Klicke auf deinen Avatar (oben links) → Profile.
Der Dialog zeigt deine User ID: eine 26-stellige alphanumerische Zeichenkette wie 3uo8dkh1p7g1mfk49ear5fzs5c. Klicke darauf, um sie zu kopieren.

Du kannst sie auch über die API auslesen:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-mattermost-server/api/v4/users/me | jq .id

Deine User ID ist nicht der @username, den du in Nachrichten siehst. Den Benutzernamen einzufügen ist der häufigste Grund, warum ein Bot stumm bleibt.

Schritt 5: Hermes konfigurieren

Führe das geführte Setup aus und wähle Mattermost, wenn du dazu aufgefordert wirst — es fragt nach der Server-URL, dem Bot-Token und deiner User ID:

hermes gateway setup

Oder verdrahte es manuell in ~/.hermes/.env:

# Required
MATTERMOST_URL=https://mm.example.com
MATTERMOST_TOKEN=your-bot-token
MATTERMOST_ALLOWED_USERS=3uo8dkh1p7g1mfk49ear5fzs5c

# Multiple allowed users (comma-separated)
# MATTERMOST_ALLOWED_USERS=3uo8dkh1p7g1mfk49ear5fzs5c,8fk2jd9s0a7bncm1xqw4tp6r3e

# Optional: reply in a thread instead of flat messages (default: off)
# MATTERMOST_REPLY_MODE=thread

# Optional: respond without an @mention (default: true = mention required)
# MATTERMOST_REQUIRE_MENTION=false

# Optional: channels where no @mention is needed (comma-separated channel IDs)
# MATTERMOST_FREE_RESPONSE_CHANNELS=channel_id_1,channel_id_2

Starte dann das Gateway:

hermes gateway

Der Bot verbindet sich innerhalb weniger Sekunden mit deinem Mattermost-Server. Sende ihm eine DM oder @mention ihn in einem Channel, in dem er hinzugefügt wurde, um es zu testen.

Schritt 6: Optionale Verhaltensschalter

Einstellung	Was sie bewirkt
`MATTERMOST_REPLY_MODE`	`off` (Standard) postet flache Nachrichten; `thread` verschachtelt Antworten unter deiner Nachricht und hält belebte Channels aufgeräumt.
`MATTERMOST_REQUIRE_MENTION`	Standardmäßig `true`. Auf `false` setzen, um auf alle Channel-Nachrichten zu antworten (DMs funktionieren immer).
`MATTERMOST_FREE_RESPONSE_CHANNELS`	Channel-IDs, die die Mention-Anforderung überspringen, auch wenn Mentions erforderlich sind.
`MATTERMOST_HOME_CHANNEL`	Wohin proaktive Nachrichten gehen — Cron-Ausgaben, Erinnerungen, Benachrichtigungen. Oder tippe `/sethome` in einem Channel.
`mattermost.allowed_channels`	Beschränke den Bot auf eine Liste von Channel-IDs; Nachrichten von überall sonst werden verworfen. DMs sind ausgenommen.
`mattermost.channel_prompts`	Injiziere einen ephemeren System-Prompt pro Channel — wird bei jedem Turn angewendet, nie im Transkript-Verlauf gespeichert.

Wenn der Bot @mentioned wird, wird die Mention aus der Nachricht entfernt, bevor sie verarbeitet wird, sodass @hermes summarize this thread als saubere Anweisung ankommt.

Fehlerbehebung

Symptom	Wahrscheinliche Ursache	Lösung
Bot ignoriert dich in Channels	Er ist nicht im Channel, oder deine User ID steht nicht in `MATTERMOST_ALLOWED_USERS`	Füge den Bot zum Channel hinzu, überprüfe die 26-stellige User ID, starte das Gateway neu
Bot kann nicht posten	Ungültiges Token, oder dem Bot fehlt die Berechtigung in diesem Channel	Prüfe `MATTERMOST_TOKEN`, bestätige, dass das Konto aktiv und Channel-Mitglied ist
Ständige Verbindungsabbrüche	WebSocket-Abbrüche, Server-Neustarts oder Proxy-/Firewall-Probleme	Der Adapter verbindet sich mit exponentiellem Backoff neu (2s → 60s); stelle bei nginx sicher, dass WebSocket-Upgrade-Header konfiguriert sind
Gar nichts passiert	Gateway läuft nicht, oder die URL/das Token ist falsch	Prüfe die Ausgabe von `hermes gateway` und dass `MATTERMOST_URL` `https://` enthält und keinen abschließenden Slash hat

Teste ein Token direkt mit:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-server/api/v4/users/me

Den Bot absichern

Setze immer MATTERMOST_ALLOWED_USERS. Ohne diese Einstellung verweigert das Gateway standardmäßig allen Benutzern den Zugriff als Sicherheitsmaßnahme — und autorisierte Benutzer erhalten vollen Zugriff auf die Fähigkeiten des Agenten, einschließlich Tool-Nutzung und Systemzugriff, also halte die Liste kurz. Für einen breiteren Blick auf die Absicherung eines Deployments siehe die offizielle Sicherheitsrichtlinie.

Wie geht es weiter?

Sobald das Gateway läuft, verhält sich Mattermost wie jeder andere Hermes-Channel: Slash-Befehle, Datei-Uploads, Sprachnotizen, Cron-Ausgaben, die an deinen Home-Channel geliefert werden — alles auf Infrastruktur, die du kontrollierst. Wenn du lieber die gehostete Option nutzen möchtest, behandelt die Slack-Integration den Socket-Mode-Weg; wenn du Gateways auf mehreren Maschinen betreibst, verbindet sie Hermes Relay.