WeCom-Rückrufmodus — Benutzerdefinierte Apps

Stell es dir vor wie ein eigenes Büropostfach für deinen KI-Assistenten – statt in Gruppenchats mitzuhängen, bekommt er einen eigenen Schreibtisch, an dem Leute vorbeikommen und direkt Nachrichten hinterlassen können.

Was ist der große Unterschied?

Hermes Agent bietet dir zwei Möglichkeiten, WeCom (Enterprise WeChat) anzubinden. Der Bot-Modus ist wie ein freundlicher Assistent, der Gruppenchats beitritt – schnell eingerichtet, aber begrenzt. Der Rückrufmodus ist anders: Du baust eine benutzerdefinierte App, die in der WeCom-Seitenleiste deiner Mitarbeiter erscheint, genau wie jede offizielle App. Sie fühlt sich nativ an, unterstützt mehrere Unternehmen und verarbeitet verschlüsselte Nachrichten sicher.

Der Haken? Du brauchst einen öffentlichen Server, um Nachrichten zu empfangen. Aber keine Sorge – ein einfacher Tunnel wie ngrok reicht zum Testen völlig aus.

---

Wie es tatsächlich funktioniert

Hier ist der Ablauf in einfachen Worten:

1. Jemand sendet eine Nachricht an deine benutzerdefinierte App in WeCom.
2. WeCom verschlüsselt diese Nachricht und sendet sie an den HTTP-Endpunkt deines Servers.
3. Hermes entschlüsselt sie, stellt sie für den KI-Agenten in die Warteschlange und meldet WeCom sofort „erhalten“ (still – der Benutzer sieht noch nichts).
4. Der Agent denkt 3–30 Minuten nach (je nach Aufgabe).
5. Hermes sendet die Antwort proaktiv über die WeCom-Nachrichten-API zurück.

Kein Polling. Keine Verzögerungen. Nur eine saubere, asynchrone Konversation.

---

Schritt-für-Schritt-Einrichtung

1. App in der WeCom-Verwaltung erstellen

Melde dich in der WeCom-Verwaltungskonsole an und gehe zu Anwendungen → App erstellen.
Notiere deine Corp ID (oben in der Konsole) und erstelle ein Corp Secret.
Auf der Übersichtsseite der App findest du die Agent ID.

Unter Nachrichten empfangen konfiguriere:

• URL: http://DEINE_ÖFFENTLICHE_IP:8645/wecom/callback
• Token: generiere einen zufälligen
• EncodingAESKey: generiere einen 43-stelligen Schlüssel

2. Umgebungsvariablen setzen

Füge diese zu deiner .env-Datei hinzu:

WECOM_CALLBACK_CORP_ID = your-corp-id
WECOM_CALLBACK_CORP_SECRET = your-corp-secret
WECOM_CALLBACK_AGENT_ID = 1000002
WECOM_CALLBACK_TOKEN = your-callback-token
WECOM_CALLBACK_ENCODING_AES_KEY = your-43-char-aes-key

# Optional
WECOM_CALLBACK_PORT = 8645
WECOM_CALLBACK_ALLOWED_USERS = user1,user2

3. Gateway starten

hermes gateway

Hinweis: Verwende hermes gateway start erst, nachdem du hermes gateway install ausgeführt hast, um den Dienst zu registrieren.

Der Rückruf-Adapter startet einen HTTP-Server auf Port 8645. WeCom verifiziert die URL über eine GET-Anfrage und beginnt dann, Nachrichten per POST zu senden.

---

Konfigurationsreferenz

Du kannst diese Einstellungen auch in config.yaml unter platforms.wecom_callback.extra festlegen:

Einstellung	Standard	Beschreibung
corp_id	—	Erforderlich. Deine WeCom-Corp-ID
corp_secret	—	Erforderlich. App-Geheimnis
agent_id	—	Erforderlich. Die Agent-ID deiner App
token	—	Erforderlich. Rückruf-Verifizierungstoken
encoding_aes_key	—	Erforderlich. 43-stelliger AES-Schlüssel
host	nicht gesetzt (Dual-Stack)	Bind-Adresse für den HTTP-Server
port	8645	Port für den Rückruf-Server

---

Zusammenfassung

Der WeCom-Rückrufmodus ist der „offizielle“ Weg, Hermes in deinen Unternehmensworkflow zu integrieren. Die Einrichtung ist aufwendiger als beim Bot, aber der Lohn ist eine ausgefeilte App-Erfahrung erster Klasse für deine Benutzer.

Praktischer Tipp: Starte mit ngrok, bevor du einen echten Server freigibst. Führe ngrok http 8645 aus, verwende diese URL in der WeCom-Konsole und teste mit einem einzelnen Benutzer. Sobald es funktioniert, wechsle zu einem Produktionsserver und beschränke WECOM_CALLBACK_ALLOWED_USERS auf dein Team. Viel Erfolg beim Bauen!