Messages de groupe (canal web WhatsApp)

Objectif : permettre a Clawd de rester dans les groupes WhatsApp, de ne se reveiller que quand on le sollicite, et de garder ce fil separe de la session DM personnelle.

Remarque : agents.list[].groupChat.mentionPatterns est maintenant aussi utilise par Telegram/Discord/Slack/iMessage ; cette documentation se concentre sur le comportement specifique a WhatsApp. Pour les configurations multi-agents, definissez agents.list[].groupChat.mentionPatterns par agent (ou utilisez messages.groupChat.mentionPatterns comme repli global).

Ce qui est implemente (2025-12-03)

Modes d’activation : mention (par defaut) ou always. mention necessite un ping (vraies @-mentions WhatsApp via mentionedJids, patterns regex, ou le E.164 du bot n’importe ou dans le texte). always reveille l’agent a chaque message mais il ne devrait repondre que quand il peut apporter une valeur significative ; sinon il retourne le jeton silencieux NO_REPLY. Les valeurs par defaut peuvent etre definies dans la config (channels.whatsapp.groups) et surchargees par groupe via /activation. Quand channels.whatsapp.groups est defini, il agit aussi comme liste d’autorisation de groupe (incluez "*" pour autoriser tous).
Politique de groupe : channels.whatsapp.groupPolicy controle si les messages de groupe sont acceptes (open|disabled|allowlist). allowlist utilise channels.whatsapp.groupAllowFrom (repli : channels.whatsapp.allowFrom explicite). Par defaut c’est allowlist (bloque jusqu’a ce que vous ajoutiez des expediteurs).
Sessions par groupe : les cles de session ressemblent a agent:<agentId>:whatsapp:group:<jid> donc les commandes comme /verbose on ou /think high (envoyees comme messages autonomes) sont limitees a ce groupe ; l’etat du DM personnel n’est pas touche. Les heartbeats sont ignores pour les fils de groupe.
Injection de contexte : les messages de groupe en attente uniquement (50 par defaut) qui n’ont pas declenche une execution sont prefixes sous [Chat messages since your last reply - for context], avec la ligne declencheuse sous [Current message - respond to this]. Les messages deja dans la session ne sont pas reinjectes.
Affichage de l’expediteur : chaque lot de groupe se termine maintenant par [from: Sender Name (+E164)] pour que l’agent sache qui parle.
Ephemere/vue unique : nous les deroulons avant d’extraire le texte/mentions, donc les pings a l’interieur declenchent quand meme.
Prompt systeme de groupe : au premier tour d’une session de groupe (et chaque fois que /activation change le mode) nous injectons un court texte dans le prompt systeme comme 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. Si les metadonnees ne sont pas disponibles, nous informons quand meme l’agent qu’il est dans une discussion de groupe.

Exemple de configuration (WhatsApp)

Ajoutez un bloc groupChat a ~/.openclaw/openclaw.json pour que les pings par nom d’affichage fonctionnent meme quand WhatsApp supprime le @ visuel dans le corps du texte :

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

Remarques :

Les regex sont insensibles a la casse ; elles couvrent un ping par nom d’affichage comme @openclaw et le numero brut avec ou sans +/espaces.
WhatsApp envoie toujours les mentions canoniques via mentionedJids quand quelqu’un tapote le contact, donc le repli par numero est rarement necessaire mais est un filet de securite utile.

Commande d’activation (proprietaire uniquement)

Utilisez la commande de discussion de groupe :

/activation mention
/activation always

Seul le numero proprietaire (depuis channels.whatsapp.allowFrom, ou le E.164 du bot quand non defini) peut changer cela. Envoyez /status comme message autonome dans le groupe pour voir le mode d’activation actuel.

Comment utiliser

Ajoutez votre compte WhatsApp (celui qui execute OpenClaw) au groupe.
Dites @openclaw ... (ou incluez le numero). Seuls les expediteurs autorises peuvent le declencher sauf si vous definissez groupPolicy: "open".
Le prompt de l’agent incluera le contexte recent du groupe plus le marqueur [from: ...] final pour qu’il puisse s’adresser a la bonne personne.
Les directives au niveau de la session (/verbose on, /think high, /new ou /reset, /compact) s’appliquent uniquement a la session de ce groupe ; envoyez-les comme messages autonomes pour qu’elles soient enregistrees. Votre session DM personnelle reste independante.

Tests / verification

Test manuel :
- Envoyez un ping @openclaw dans le groupe et confirmez une reponse qui reference le nom de l’expediteur.
- Envoyez un second ping et verifiez que le bloc d’historique est inclus puis efface au tour suivant.
Verifiez les logs de la gateway (lancez avec --verbose) pour voir les entrees inbound web message montrant from: <groupJid> et le suffixe [from: ...].

Considerations connues

Les heartbeats sont intentionnellement ignores pour les groupes pour eviter les diffusions bruyantes.
La suppression d’echo utilise la chaine de lot combinee ; si vous envoyez un texte identique deux fois sans mentions, seul le premier obtiendra une reponse.
Les entrees du magasin de sessions apparaitront comme agent:<agentId>:whatsapp:group:<jid> dans le magasin de sessions (~/.openclaw/agents/<agentId>/sessions/sessions.json par defaut) ; une entree manquante signifie simplement que le groupe n’a pas encore declenche d’execution.
Les indicateurs de saisie dans les groupes suivent agents.defaults.typingMode (par defaut : message quand non mentionne).