Groepsberichten (WhatsApp-webkanaal)

Doel: laat Clawd in WhatsApp-groepen zitten, alleen wakker worden wanneer gepingd, en die thread gescheiden houden van de persoonlijke DM-sessie.

Opmerking: agents.list[].groupChat.mentionPatterns wordt nu ook gebruikt door Telegram/Discord/Slack/iMessage; deze documentatie richt zich op WhatsApp-specifiek gedrag. Voor multi-agent-configuraties stel je agents.list[].groupChat.mentionPatterns per agent in (of gebruik messages.groupChat.mentionPatterns als globale terugval).

Wat is geïmplementeerd (2025-12-03)

• Activeringsmodi: mention (standaard) of always. mention vereist een ping (echte WhatsApp @-vermeldingen via mentionedJids, regex-patronen, of het E.164-nummer van de bot ergens in de tekst). always wekt de agent bij elk bericht, maar deze antwoordt alleen wanneer het echte waarde kan toevoegen; anders retourneert het het stille token NO_REPLY. Standaardwaarden kunnen in de config worden ingesteld (channels.whatsapp.groups) en per groep overschreven via /activation. Wanneer channels.whatsapp.groups is ingesteld, fungeert het ook als groeps-allowlist (voeg "*" toe om alle groepen toe te staan).
• Groepsbeleid: channels.whatsapp.groupPolicy bepaalt of groepsberichten worden geaccepteerd (open|disabled|allowlist). allowlist gebruikt channels.whatsapp.groupAllowFrom (terugval: expliciete channels.whatsapp.allowFrom). Standaard is allowlist (geblokkeerd totdat je afzenders toevoegt).
• Per-groepssessies: sessiesleutels zien eruit als agent:<agentId>:whatsapp:group:<jid>, dus commando’s zoals /verbose on of /think high (als losstaande berichten verzonden) zijn beperkt tot die groep; de persoonlijke DM-status blijft ongewijzigd. Heartbeats worden overgeslagen voor groepsthreads.
• Contextinjectie: alleen wachtende groepsberichten (standaard 50) die geen run hebben getriggerd, worden voorafgegaan door [Chat messages since your last reply - for context], met de triggerende regel onder [Current message - respond to this]. Berichten die al in de sessie staan, worden niet opnieuw geïnjecteerd.
• Afzenderweergave: elke groepsbatch eindigt nu met [from: Afzendernaam (+E164)] zodat Pi weet wie er spreekt.
• Ephemeral/view-once: we pakken deze uit voordat tekst/vermeldingen worden geëxtraheerd, zodat pings erin nog steeds triggeren.
• Groepssysteemprompt: bij de eerste beurt van een groepssessie (en wanneer /activation de modus wijzigt) injecteren we een korte tekst in de systeemprompt zoals 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. Als metadata niet beschikbaar is, vertellen we de agent nog steeds dat het een groepschat is.

Configuratievoorbeeld (WhatsApp)

Voeg een groupChat-blok toe aan ~/.openclaw/openclaw.json zodat weergavenaam-pings werken, zelfs wanneer WhatsApp de visuele @ in de berichttekst verwijdert:

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

Opmerkingen:

• De regexes zijn hoofdletterongevoelig; ze dekken een weergavenaam-ping zoals @openclaw en het kale nummer met of zonder +/spaties.
• WhatsApp stuurt nog steeds canonieke vermeldingen via mentionedJids wanneer iemand het contact aantikt, dus de nummerterugval is zelden nodig maar een handige veiligheidscontrole.

Activeringscommando (alleen eigenaar)

Gebruik het groepschat-commando:

• /activation mention
• /activation always

Alleen het eigenaarnummer (uit channels.whatsapp.allowFrom, of het eigen E.164 van de bot wanneer niet ingesteld) kan dit wijzigen. Stuur /status als losstaand bericht in de groep om de huidige activeringsmodus te zien.

Hoe te gebruiken

1. Voeg je WhatsApp-account (degene die OpenClaw draait) toe aan de groep.
2. Zeg @openclaw … (of vermeld het nummer). Alleen afzenders op de allowlist kunnen het triggeren, tenzij je groupPolicy: "open" instelt.
3. De agentprompt bevat recente groepscontext plus de afsluitende [from: …]-markering zodat het de juiste persoon kan aanspreken.
4. Sessie-niveau richtlijnen (/verbose on, /think high, /new of /reset, /compact) gelden alleen voor de sessie van die groep; stuur ze als losstaande berichten zodat ze geregistreerd worden. Je persoonlijke DM-sessie blijft onafhankelijk.

Testen / verificatie

• Handmatige rooktest:
  • Stuur een @openclaw-ping in de groep en bevestig een antwoord dat naar de afzendernaam verwijst.
  • Stuur een tweede ping en controleer of het geschiedenisblok wordt opgenomen en vervolgens gewist bij de volgende beurt.
• Controleer gateway-logs (draai met --verbose) om inbound web message-vermeldingen te zien met from: <groupJid> en het [from: …]-achtervoegsel.

Bekende aandachtspunten

• Heartbeats worden opzettelijk overgeslagen voor groepen om lawaaierige broadcasts te voorkomen.
• Echonderdrukking gebruikt de gecombineerde batchtekst; als je identieke tekst twee keer stuurt zonder vermeldingen, krijgt alleen de eerste een antwoord.
• Sessieopslagvermeldingen verschijnen als agent:<agentId>:whatsapp:group:<jid> in de sessieopslag (~/.openclaw/agents/<agentId>/sessions/sessions.json standaard); een ontbrekende vermelding betekent simpelweg dat de groep nog geen run heeft getriggerd.
• Typindicatoren in groepen volgen agents.defaults.typingMode (standaard: message wanneer niet vermeld).