Hermes Agent Plattform-Nachrichtenintegration

Das Messaging-Gateway ermöglichtSame Agent—Die gleichen Erinnerungen, Fähigkeiten und Tools—die nahtlos über 20+ Plattformen laufen.

Dieses Kapitel führt in die Gateway-Konfiguration und -Bereitstellung, den Sitzungslebenszyklus, Richtlinien zur Mehrbenutzerisolierung und die Sicherheitszugriffskontrolle ein.


Message-Gateway-Übersicht

Das Message-Gateway ist ein residenter Hintergrundprozess, der Verbindungen, Sitzungen, geplante Aufgaben und die Medienzustellung für alle Messaging-Plattformen zentral verwaltet.

Alles, was Sie dem Agenten in der CLI beibringen—Erinnerungen, Fähigkeiten, Präferenzen—ist über alle Plattformen hinweg vollständig konsistent.

Unterstützte Plattformen

Hermes unterstützt 20+ Nachrichtenplattformen:CLI、Telegram、Discord、Slack、WhatsApp、Signal、Matrix、Mattermost、Email、SMS、DingTalk、Feishu/Lark、WeChat Work、micro信、QQ、元宝、BlueBubbles(iMessage)、Home Assistant、Microsoft Teams、Google Chat usw.

Plattformfähigkeitsvergleich

PlattformSpracheImagesDateiNachrichtenstringEmoji-ReaktionTippanzeigeStreaming-Ausgabe
TelegramUnterstütztUnterstütztUnterstütztUnterstützt—UnterstütztUnterstützt
DiscordUnterstütztUnterstütztUnterstütztUnterstütztUnterstütztUnterstütztUnterstützt
SlackUnterstütztUnterstütztUnterstütztUnterstütztUnterstütztUnterstütztUnterstützt
WhatsApp—UnterstütztUnterstützt——UnterstütztUnterstützt
Signal—UnterstütztUnterstützt——UnterstütztUnterstützt
Feishu/LarkUnterstütztUnterstütztUnterstütztUnterstütztUnterstütztUnterstütztUnterstützt
WeChat WorkUnterstütztUnterstütztUnterstützt————
DingTalk—UnterstütztUnterstützt—Unterstützt—Unterstützt
Microsoft Teams—Unterstützt—Unterstützt—Unterstützt—
E-Mail—UnterstütztUnterstütztUnterstützt———
SMS———————
MatrixUnterstütztUnterstütztUnterstütztUnterstütztUnterstütztUnterstütztUnterstützt

Plattformübergreifende Sitzungskontinuität: Derselbe Agent kann den Kontext über verschiedene Plattformen hinweg beibehalten. Wenn Sie sich beispielsweise auf Telegram mitten in einer Unterhaltung mit dem Agenten befinden und zu Discord wechseln, erinnert sich der Agent weiterhin an die vorherige Unterhaltung.


Gateway-Start und -Konfiguration

Konfiguration der Desktop-Version

Öffnen Sie im linken Menü den Eintrag „Messaging Platforms“, um die unterstützten Plattformen anzuzeigen. Klicken Sie auf die entsprechende Plattform, um sie zu konfigurieren:

Konfiguration im interaktiven Modus

Verwenden Sie den interaktiven Assistenten, um die Ersteinrichtung für alle Plattformen abzuschließen:

hermes gateway setup

Der Assistent führt Sie durch die Konfiguration jeder Plattform: Auswählen der Plattform, Eingeben des Bot-Tokens, Festlegen der Liste der zulässigen Benutzer usw.

Zum Beispiel können Sie nach der Auswahl von Feishu wählen, einen Bot durch Scannen eines QR-Codes oder mithilfe der APP ID zu erstellen:

Gateway-Verwaltungsbefehle

Beispiel

# Im Vordergrund ausführen (zum Debuggen)
hermes gateway

# Als Systemdienst auf Benutzerebene installieren (Linux systemd / macOS launchd)
hermes gateway install

# Linux: Als Systemdienst installieren, der beim Booten startet
sudo hermes gateway install --system

# Dienststeuerung
hermes gateway start       # Dienst starten
hermes gateway stop        # Dienst stoppen
hermes gateway restart     # Dienst neu starten
hermes gateway status      # Dienststatus anzeigen

Praxisnahe Telegram-Bot-Integration

Am Beispiel von Telegram einen vollständigen Bot-Integrationsprozess durchführen.

Schritt 1: Einen Telegram-Bot erstellen.

Senden Sie in Telegram den Befehl /newbot und legen Sie den Bot-Namen und Benutzernamen wie aufgefordert fest.

BotFather gibt ein Bot-API-Token zurück, das ähnlich formatiert ist wie:1234567890:ABCdefGHIjklMNOpqrsTUVwxyz。

Schritt 2: Hermes Gateway konfigurieren.

Beispiel

# Dateipfad: ~/.hermes/config.yaml
# Telegram-Plattformkonfiguration
platforms
:
  telegram
:
    enabled
: true
    bot_token
: "1234567890:ABCdefGHIjklMNOpqrsTUVwxyz"
    # Optional: Liste der erlaubten Benutzer-IDs (Whitelist-Modus).
    allowed_users
:
     - "123456789"
    # Optional: ob es in der Gruppe eine @Erwähnung benötigt, um zu antworten
    require_mention
: true
    # Optional: Liste der Kanäle, die keine @Erwähnung erfordern
    free_response_channels
:
     - "-1001234567890"

Schritt 3: Starten und testen.

Beispiel

# Gateway starten
hermes gateway start

# Sende eine Testnachricht an deinen Bot in Telegram

Für die erste Integration wird empfohlen, den Whitelist-Modus (allowed_users) zu verwenden, sodass nur dein eigenes Konto mit dem Agenten interagieren kann, und ihn erst dann für andere freizugeben, nachdem du überprüft hast, dass alles ordnungsgemäß funktioniert.

Innerhalb der Plattform verfügbare Slash-Befehle

Die folgenden Befehle sind auf jeder Messaging-Plattform verfügbar:

BefehlFunktionen
/new oder /resetNeue Sitzung starten
/model [name]Modelle anzeigen oder wechseln
/retryLetzte Nachricht erneut senden
/undoLetzten Gesprächsschritt rückgängig machen
/stopAktuelle Aufgabe unterbrechen
/approve / /denyGefährliche Befehle genehmigen/ablehnen
/background <task>Aufgaben in Hintergrund-Sitzungen ausführen
/statusAktuelle Sitzungsinformationen anzeigen
/usageToken-Nutzung für diese Sitzung anzeigen.
/voice [on/off/tts]Sprachantworten steuern
/compressKonversationskontext manuell komprimieren
/resume [title]Eine zuvor benannte Sitzung fortsetzen
/<skill-name>Einen beliebigen installierten Skill aufrufen
/reload-mcpMCP-Server neu laden
/updateHermes auf die neueste Version aktualisieren
/helpAlle verfügbaren Befehle anzeigen

Sitzungslebenszyklus

Die Sitzung ist das Kernkonzept im Hermes Gateway für die Verwaltung von Konversationen.

Das Verständnis dafür, wie die Sitzung funktioniert, hilft Ihnen, geeignete Richtlinien für die Sitzungsisolierung und Regeln zum Zurücksetzen zu konfigurieren.

SessionSource: Deskriptor der Nachrichtenquelle

Jede Nachricht, die in das Gateway eintritt, trägt eine SessionSource, die festhält, "woher diese Nachricht stammt."

FieldsTypeBeschreibung
PlattformstringPlattformname (telegram, discord, slack usw.)
chat_idstringSitzungsbezeichner (private Chat-ID, Gruppen-ID, Kanal-ID)
chat_typestringSitzungstypen: dm (Direktnachricht), Gruppe, Kanal, Thread
user_idstringPlattform-ID des Nachrichtenabsenders
user_namestringAnzeigename des Nachrichtenabsenders
thread_idstringForumsthema-ID (Telegram-Forum) / Discord-Thread-ID
guild_idstringDiscord-Server-ID (verwendet zur Isolation von Servern)

Regeln zur Generierung von Sitzungsschlüsseln

Der Session-Schlüssel ist eine deterministische Zeichenkette, die aus Feldern des SessionSource zusammengesetzt ist.

Er bestimmt, welche Nachrichten zur selben Session gehören. Das Format ist wie folgt:

agent:main:{platform}:{chat_type}:{chat_id}:{thread_id}:{user_id}

Beispiele für Session-Schlüssel in verschiedenen Szenarien:

SzenarienSession-Schlüssel
Telegram-Privatchatagent:main:telegram:dm:12345
Telegram-Gruppeagent:main:telegram:group:-10012345:user_abc
Telegram-Forumthemenagent:main:telegram:group:-10012345:thread_678:user_abc
Discord-Privatchatagent:main:discord:dm:12345
Discord-Server-Kanäleagent:main:discord:channel:12345:user_abc
Discord-Threadagent:main:discord:thread:12345:thread_678

Die Regel zur Generierung des Session Keys ist eine der wichtigsten Gateway-Konfigurationen. Wenn sie falsch konfiguriert ist, kann es zu Übersprechen zwischen den Sitzungen verschiedener Benutzer kommen – zwei verschiedene Personen sehen den Gesprächsinhalt des jeweils anderen.

SessionEntry: aktiver Sitzungseintrag

Jeder Session Key entspricht einem SessionEntry, der die Metadaten und den Zustand der Sitzung aufzeichnet.

FieldsBeschreibung
session_idEindeutige Sitzungskennung, Format: YYYYMMDD_HHMMSS_8-stelliger zufälliger Hexwert
created_atSitzungserstellungszeit
updated_atLetzte Aktivitätszeit (wird zur Bestimmung des Idle-Timeouts verwendet)
total_tokensKumulativer Tokenverbrauch
estimated_cost_usdKumulative Kostenschätzung (USD)
suspendedOb es zwangsweise suspendiert wurde (/stop-Befehl oder abnormale Schleife)
resume_pendingOb es auf Wiederherstellung wartet (Neustart-Wiederherstellungsflag nach einem Absturz)

Multi-User-Isolationsrichtlinie

Die Mehrbenutzerisolierung bestimmt, ob mehrere Benutzer in derselben Gruppe oder demselben Kanal eine einzelne Sitzung gemeinsam nutzen oder ihre eigenen unabhängigen Sitzungen haben.

Diese Konfiguration wirkt sich direkt auf die Benutzererfahrung aus—eine gemeinsam genutzte Sitzung bedeutet, dass Benutzer A den Gesprächskontext von Benutzer B sehen kann.

Isolationsrichtlinienkonfiguration

KonfigurationselementStandardwertBedeutung
group_sessions_per_userwahrJeder Benutzer in einer Gruppe/einem Kanal hat eine unabhängige Sitzung
thread_sessions_per_userfalseAlle Benutzer im Thread teilen sich dieselbe Sitzung

Verhalten in verschiedenen Szenarien

SzenarienStandardverhaltenBeschreibung
Privater Chat (DM)Immer unabhängigPrivate Chats sind immer privat und nicht konfigurierbar
Gruppen/KanäleJeder Benutzer hat eine unabhängige SitzungBenutzer A und Benutzer B haben jeweils unabhängige Sitzungskontexte in derselben Gruppe
Thread (Forumsthema)Alle Benutzer teilen denselben KontextIn Telegram-Forenthemen und Discord-Threads teilen die Teilnehmer denselben Kontext

System-Prompt-Änderungen für geteilte Sitzungen

Wenn sich die Sitzung im geteilten Modus befindet (shared_multi_user = true), wird der System-Prompt

  • Anstelle eines festen Benutzernamens wird folgender Prompt verwendet: "Multi-Benutzer-Sitzung—Nachrichtenpräfix enthält Absender"
  • Jeder Benutzernachricht wird der Anzeigename des Absenders vorangestellt, damit der Agent weiß, wer spricht
  • Dieses Design erhält die Effektivität des Prompt-Cachings (der System-Prompt ändert sich nicht mit dem Absender)

Die Standard-Isolationsrichtlinie (pro Benutzer für Gruppen, geteilt für Threads) ist eine Best Practice, die durch umfangreiche reale Nutzung bestätigt wurde. Sofern keine besonderen Anforderungen bestehen, wird davon abgeraten, sie zu ändern.


Gateway-Sicherheitskonfiguration

Benutzerzugriffskontrolle

Standardmäßig weist das Gateway alle Benutzer ab, die nicht auf der Whitelist stehen—Dies ist die sichere Standardeinstellung für einen Bot mit Terminalzugriffsberechtigungen.

Erlaubte Benutzer konfigurieren (in der .env-Datei):

Beispiel

# Dateipfad: ~/.hermes/.env
# Benutzer-Whitelist für bestimmte Plattformen
TELEGRAM_ALLOWED_USERS=123456789,987654321
DISCORD_ALLOWED_USERS=123456789012345678
SLACK_ALLOWED_USERS=U012AB3CD,U012EF4GH
FEISHU_ALLOWED_USERS=ou_xxxxxxxx,ou_yyyyyyyy
WECOM_ALLOWED_USERS=user-id-1,user-id-2
TEAMS_ALLOWED_USERS=aad-object-id-1

# Whitelist, die für alle Plattformen gilt
GATEWAY_ALLOWED_USERS=123456789,987654321

# Allen Benutzern erlauben (nicht empfohlen für Bots mit Terminalzugriff)
GATEWAY_ALLOW_ALL_USERS=true

DM-Pairing (Alternative zur Whitelist)

Benutzer-IDs müssen nicht manuell konfiguriert werden. Wenn ein neuer Benutzer dem Bot eine DM sendet, erhält er einen einmaligen Pairing-Code:

Beispiel

# Nachdem der Benutzer dem Bot eine DM gesendet hat, sieht er: "Pairing-Code: XKGH5N7P"
# Sie genehmigen den Zugriff des Benutzers
hermes pairing approve telegram XKGH5N7P

# Ausstehende + genehmigte Benutzerliste anzeigen
hermes pairing list

# Zugriffsberechtigungen eines Benutzers widerrufen
hermes pairing revoke telegram 123456789

Der Pairing-Code läuft nach 1 Stunde ab, hat eine Ratenbegrenzung und wird mit kryptografischen Zufallszahlen generiert.

Stiller Token

Wird in Gruppenchats, Hooks und automatisierten Workflows verwendet, damit der Agent unter bestimmten Bedingungen keine Nachrichten sendet:

# Agent 回复中仅包含以下内容之一时,网关不会向平台发送任何消息:
[SILENT]
SILENT
NO_REPLY
NO REPLY

Schweigen istZustellentscheidung, ohne den Sitzungsdatensatz zu beeinflussen – die Antwort wird weiterhin im Sitzungsverlauf gespeichert, wodurch die Sprecherwechsel-Logik der Konversation normal funktioniert.

Richtlinie zum Zurücksetzen der Sitzung

Konfigurieren Sie, wann die Sitzung automatisch zurückgesetzt wird, um unbegrenztes Kontextwachstum zu verhindern:

Beispiel

{
  "reset_by_platform": {
    "telegram": { "mode": "idle", "idle_minutes": 240 },
    "discord": { "mode": "idle", "idle_minutes": 60 },
    "slack": { "mode": "daily", "reset_hour": 4 }
  }
}
PolicyStandardwertBeschreibung
täglich4:00 UhrSitzung jeden Tag zu einer bestimmten Uhrzeit zurücksetzen
idle1440 MinutenSitzung nach Inaktivitäts-Timeout zurücksetzen
bothKombinationWas zuerst ausgelöst wird, setzt die Sitzung zurück

Kurzreferenz für gängige Befehle

Beispiel

# ─── Gateway-Verwaltung ────────────────────────────────────────────────
hermes gateway setup                  # Interaktive Plattformkonfiguration
hermes gateway                        # Im Vordergrund ausführen (Debug)
hermes gateway install                # Als Benutzerdienst installieren
hermes gateway start / stop / restart # Dienststeuerung
hermes gateway status                 # Dienststatus anzeigen

# ─── Benutzer-Pairing ────────────────────────────────────────────────
hermes pairing list                   # Pairing-Liste anzeigen
hermes pairing approve <platform> <code>   # Pairing genehmigen
hermes pairing revoke <platform> <user_id> # Zugriff widerrufen

# ─── SessioninsideSlash-Befehle ──────────────────────────────────────────
/new                                  # Eine neue Sitzung starten
/model [Name]                         # Modell anzeigen oder wechseln
/retry                                # Letzte Nachricht wiederholen
/undo                                 # Vorherigen Zug rückgängig machen
/stop                                 # Aktuelle Aufgabe unterbrechen
/approve / /deny                      # Gefährliche Befehle genehmigen/ablehnen
/background <Task>                    # Aufgabe im Hintergrund ausführen
/status                               # Aktuelle Sitzungsinformationen
/usage                                # Token-Nutzung
/voice [on/off/tts]                   # Stimme steuern
/compress                             # Kontext komprimieren
/resume [Titel]                         # Sitzung wiederherstellen
/<skill-name>                         # Skill aufrufen
/reload-mcp                           # MCP neu laden
/update                               # Hermes aktualisieren
/help                                 # Alle Befehle
Weitere Erweiterungen