WhatsApp-Gruppennachrichten

Für das kanalübergreifende Gruppenmodell (Discord, iMessage, Matrix, Microsoft Teams, Signal, Slack, Telegram, WhatsApp, Zalo) siehe Gruppen. Diese Seite behandelt das WhatsApp-spezifische Verhalten zusätzlich zu diesem Modell: Aktivierung, Gruppen-Zulassungslisten, sitzungsbezogene Schlüssel pro Gruppe und Kontextinjektion für ausstehende Nachrichten.

Ziel: OpenClaw soll in WhatsApp-Gruppen sitzen, nur bei einer Anpingen aktiv werden und diesen Thread von der persönlichen DM-Sitzung getrennt halten.

Verhalten

• Aktivierungsmodi: mention (Standard) oder always. mention erfordert ein Anpingen (echte WhatsApp-@-Erwähnungen über mentionedJids, sichere Regex-Muster oder die E.164 des Bots irgendwo im Text). always aktiviert den Agent bei jeder Nachricht, er sollte aber nur antworten, wenn er einen sinnvollen Mehrwert liefern kann; andernfalls gibt er exakt das stille Token NO_REPLY / no_reply zurück. Standards können in der Konfiguration (channels.whatsapp.groups) gesetzt und pro Gruppe über /activation überschrieben werden. Wenn channels.whatsapp.groups gesetzt ist, dient es auch als Gruppen-Zulassungsliste (fügen Sie "*" ein, 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 Sie Absender hinzufügen).
• Sitzungen pro Gruppe: Sitzungsschlüssel sehen aus wie agent:<agentId>:whatsapp:group:<jid>, sodass Befehle wie /verbose on, /trace on oder /think high (als eigenständige Nachrichten gesendet) auf diese Gruppe begrenzt sind; der persönliche DM-Status bleibt unberührt. Heartbeats werden für Gruppen-Threads übersprungen.
• Kontextinjektion: nur ausstehende Gruppennachrichten (standardmäßig 50), die keinen Lauf ausgelöst haben, werden unter [Chat messages since your last reply - for context] vorangestellt, mit der auslösenden Zeile unter [Current message - respond to this]. Nachrichten, die bereits in der Sitzung sind, werden nicht erneut injiziert.
• Absenderanzeige: Jeder Gruppen-Batch endet jetzt mit [from: Sender Name (+E164)], damit OpenClaw weiß, wer spricht.
• Flüchtig/einmalig anzeigbar: Wir entpacken diese Nachrichten, bevor Text/Erwähnungen extrahiert werden, sodass Anpingen darin weiterhin auslösen.
• Gruppen-Systemprompt: Beim ersten Turn einer Gruppensitzung (und immer dann, wenn /activation den Modus ändert) injizieren wir einen kurzen Hinweis in den Systemprompt wie 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. Wenn Metadaten nicht verfügbar sind, teilen wir dem Agent trotzdem mit, dass es sich um einen Gruppenchat handelt.

Konfigurationsbeispiel (WhatsApp)

Fügen Sie einen groupChat-Block zu ~/.openclaw/openclaw.json hinzu, damit Anzeigenamen-Anpingen auch dann funktionieren, wenn WhatsApp das sichtbare @ im Textkörper entfernt:

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

Hinweise:

• Die Regexes sind nicht groß-/kleinschreibungssensitiv und verwenden dieselben Safe-Regex-Leitplanken wie andere Konfigurations-Regex-Oberflächen; ungültige Muster und unsichere verschachtelte Wiederholungen werden ignoriert.
• WhatsApp sendet weiterhin kanonische Erwähnungen über mentionedJids, wenn jemand auf den Kontakt tippt. Daher wird der Nummern-Fallback selten benötigt, ist aber ein nützliches Sicherheitsnetz.

Aktivierungsbefehl (nur Owner)

Verwenden Sie den Gruppenchat-Befehl:

• /activation mention
• /activation always

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

Verwendung

1. Fügen Sie Ihr WhatsApp-Konto (das OpenClaw ausführt) zur Gruppe hinzu.
2. Schreiben Sie @openclaw … (oder geben Sie die Nummer an). Nur Absender auf der Zulassungsliste können es auslösen, sofern Sie nicht groupPolicy: "open" setzen.
3. Der Agent-Prompt enthält den aktuellen Gruppenkontext plus die abschließende Markierung [from: …], damit er die richtige Person ansprechen kann.
4. Sitzungsbezogene Direktiven (/verbose on, /trace on, /think high, /new oder /reset, /compact) gelten nur für die Sitzung dieser Gruppe; senden Sie sie als eigenständige Nachrichten, damit sie registriert werden. Ihre persönliche DM-Sitzung bleibt unabhängig.

Testen / Verifizierung

• Manueller Smoke-Test:
  • Senden Sie ein @openclaw-Anpingen in der Gruppe und bestätigen Sie eine Antwort, die den Absendernamen erwähnt.
  • Senden Sie ein zweites Anpingen und prüfen Sie, dass der Verlaufsblock enthalten ist und beim nächsten Turn geleert wird.
• Prüfen Sie die Gateway-Logs (mit --verbose ausführen), um inbound web message-Einträge mit from: <groupJid> und dem Suffix [from: …] zu sehen.

Bekannte Hinweise

• Heartbeats werden für Gruppen absichtlich übersprungen, um laute Broadcasts zu vermeiden.
• Die Echo-Unterdrückung verwendet den kombinierten Batch-String; wenn Sie identischen Text zweimal ohne Erwähnungen senden, erhält nur der erste eine Antwort.
• Sitzungsspeichereinträge erscheinen als agent:<agentId>:whatsapp:group:<jid> im Sitzungsspeicher (standardmäßig ~/.openclaw/agents/<agentId>/sessions/sessions.json); ein fehlender Eintrag bedeutet lediglich, dass die Gruppe noch keinen Lauf ausgelöst hat.
• Tippindikatoren in Gruppen folgen agents.defaults.typingMode. Wenn sichtbare Antworten im Nur-Nachrichtentool-Modus aktiviert sind, beginnt das Tippen standardmäßig sofort, damit Gruppenmitglieder sehen können, dass der Agent arbeitet, auch wenn keine automatische finale Antwort gepostet wird. Eine explizite Konfiguration des Tippmodus hat weiterhin Vorrang.

Verwandt

• Gruppen
• Kanalrouting
• Broadcast-Gruppen