Gruppennachrichten (WhatsApp-Webkanal)

Ziel: Lass Clawd in WhatsApp-Gruppen sitzen, nur bei Erwähnung aufwachen und diesen Thread getrennt von der persönlichen DM-Session halten.

Hinweis: agents.list[].groupChat.mentionPatterns wird inzwischen auch von Telegram/Discord/Slack/iMessage verwendet; diese Dokumentation konzentriert sich auf WhatsApp-spezifisches Verhalten. Für Multi-Agent-Setups setze agents.list[].groupChat.mentionPatterns pro Agent (oder verwende messages.groupChat.mentionPatterns als globalen Fallback).

Was implementiert ist (2025-12-03)

• Aktivierungsmodi: mention (Standard) oder always. mention erfordert eine Erwähnung (echte WhatsApp-@-Mentions via mentionedJids, Regex-Muster oder die E.164-Nummer des Bots im Text). always weckt den Agent bei jeder Nachricht, aber er soll nur antworten, wenn er sinnvoll beitragen kann; andernfalls gibt er das stille Token NO_REPLY zurück. Standards können in der Konfiguration festgelegt werden (channels.whatsapp.groups) und pro Gruppe via /activation überschrieben werden. Wenn channels.whatsapp.groups gesetzt ist, dient es auch als Gruppen-Allowlist (füge "*" hinzu, um alle zu erlauben).
• Gruppenrichtlinie: channels.whatsapp.groupPolicy steuert, ob Gruppennachrichten akzeptiert werden (open|disabled|allowlist). allowlist verwendet channels.whatsapp.groupAllowFrom (Fallback: explizites channels.whatsapp.allowFrom). Standard ist allowlist (blockiert, bis du Absender hinzufügst).
• Pro-Gruppen-Sessions: Session-Schlüssel sehen so aus: agent:<agentId>:whatsapp:group:<jid>, sodass Befehle wie /verbose on oder /think high (als eigenständige Nachrichten gesendet) auf diese Gruppe beschränkt sind; der persönliche DM-Zustand bleibt unberührt. Heartbeats werden für Gruppen-Threads übersprungen.
• Kontextinjektion: Nur ausstehende Gruppennachrichten (Standard 50), die keinen Lauf ausgelöst haben, werden unter [Chat messages since your last reply - for context] vorangestellt, wobei die auslösende Zeile unter [Current message - respond to this] steht. Nachrichten, die bereits in der Session sind, werden nicht erneut injiziert.
• Absenderanzeige: Jeder Gruppenbatch endet mit [from: Absendername (+E164)], damit der Bot weiß, wer spricht.
• Ephemeral/Einmalansicht: Diese werden vor der Text-/Mention-Extraktion entpackt, sodass Pings darin weiterhin auslösen.
• Gruppen-Systemprompt: Beim ersten Turn einer Gruppen-Session (und wenn sich der Modus via /activation ändert) wird ein kurzer Hinweis in den Systemprompt injiziert, z. B. You are replying inside the WhatsApp group "<subject>". Group members: Alice (+44...), Bob (+43...), … Activation: trigger-only … Address the specific sender noted in the message context. Falls Metadaten nicht verfügbar sind, wird dem Agent trotzdem mitgeteilt, dass es sich um einen Gruppenchat handelt.

Konfigurationsbeispiel (WhatsApp)

Füge einen groupChat-Block zu ~/.openclaw/openclaw.json hinzu, damit Anzeigenamen-Pings auch funktionieren, wenn WhatsApp das visuelle @ im Textkörper entfernt:

{
  channels: {
    whatsapp: {
      groups: {
        "*": { requireMention: true },
      },
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          historyLimit: 50,
          mentionPatterns: ["@?openclaw", "\\+?15555550123"],
        },
      },
    ],
  },
}

Hinweise:

• Die Regexe sind case-insensitive; sie decken einen Anzeigenamen-Ping wie @openclaw und die Rohzahl mit oder ohne +/Leerzeichen ab.
• WhatsApp sendet weiterhin kanonische Mentions via mentionedJids, wenn jemand auf den Kontakt tippt, sodass der Nummern-Fallback selten benötigt wird, aber ein nützliches Sicherheitsnetz darstellt.

Aktivierungsbefehl (nur Besitzer)

Verwende den Gruppenchat-Befehl:

• /activation mention
• /activation always

Nur die Besitzernummer (aus channels.whatsapp.allowFrom, oder die eigene E.164 des Bots wenn nicht gesetzt) kann dies ändern. Sende /status als eigenständige Nachricht in der Gruppe, um den aktuellen Aktivierungsmodus zu sehen.

Verwendung

1. Füge dein WhatsApp-Konto (das, auf dem OpenClaw läuft) der Gruppe hinzu.
2. Schreibe @openclaw … (oder füge die Nummer ein). Nur Absender auf der Allowlist können den Bot auslösen, es sei denn, du setzt groupPolicy: "open".
3. Der Agent-Prompt enthält den aktuellen Gruppenkontext plus den abschließenden [from: …]-Marker, damit er die richtige Person ansprechen kann.
4. Session-spezifische Anweisungen (/verbose on, /think high, /new oder /reset, /compact) gelten nur für die Session dieser Gruppe; sende sie als eigenständige Nachrichten, damit sie registriert werden. Deine persönliche DM-Session bleibt unabhängig.

Testen / Verifizierung

• Manueller Schnelltest:
  • Sende einen @openclaw-Ping in der Gruppe und bestätige, dass eine Antwort kommt, die den Absendernamen referenziert.
  • Sende einen zweiten Ping und überprüfe, dass der Verlaufsblock eingebunden und beim nächsten Turn gelöscht wird.
• Prüfe die Gateway-Logs (mit --verbose starten), um inbound web message-Einträge zu sehen, die from: <groupJid> und das [from: …]-Suffix zeigen.

Bekannte Besonderheiten

• Heartbeats werden für Gruppen absichtlich übersprungen, um störende Broadcasts zu vermeiden.
• Echo-Unterdrückung verwendet den kombinierten Batch-String; wenn du identischen Text zweimal ohne Mentions sendest, erhält nur der erste eine Antwort.
• Session-Store-Einträge erscheinen als agent:<agentId>:whatsapp:group:<jid> im Session-Store (standardmäßig ~/.openclaw/agents/<agentId>/sessions/sessions.json); ein fehlender Eintrag bedeutet nur, dass die Gruppe noch keinen Lauf ausgelöst hat.
• Tippindikatoren in Gruppen folgen agents.defaults.typingMode (Standard: message bei fehlender Erwähnung).