Groupes

OpenClaw traite les discussions de groupe de manière cohérente sur toutes les surfaces : Discord, iMessage, Matrix, Microsoft Teams, QQBot, Signal, Slack, Telegram, WhatsApp, Zalo.

Pour les salons toujours actifs qui doivent fournir un contexte discret sauf si l’agent envoie explicitement un message visible, consultez Événements de salon ambiant.

Introduction débutant (2 minutes)

OpenClaw « vit » sur vos propres comptes de messagerie. Il n’y a pas d’utilisateur bot WhatsApp séparé. Si vous êtes dans un groupe, OpenClaw peut voir ce groupe et y répondre.

Comportement par défaut :

• Les groupes sont restreints (groupPolicy: "allowlist").
• Les réponses nécessitent une mention, sauf si vous désactivez explicitement le filtrage par mention.
• Les réponses visibles dans les groupes/canaux utilisent l’outil message par défaut.

Traduction : les expéditeurs autorisés peuvent déclencher OpenClaw en le mentionnant.

Flux rapide (ce qui arrive à un message de groupe) :

groupPolicy? disabled -> dropgroupPolicy? allowlist -> group allowed? no -> droprequireMention? yes -> mentioned? no -> store for context onlymention/reply/command/DM -> user requestalways-on group chatter -> user request, or room event when configured

Réponses visibles

Pour les demandes normales de groupe/canal, OpenClaw utilise par défaut messages.groupChat.visibleReplies: "automatic". Le texte final de l’assistant est publié via l’ancien chemin de réponse visible, sauf si vous configurez le salon pour une sortie uniquement via l’outil de message.

Utilisez messages.groupChat.visibleReplies: "message_tool" lorsqu’un salon partagé doit laisser l’agent décider quand parler en appelant message(action=send). Cela fonctionne le mieux pour les salons de groupe adossés à des modèles de dernière génération fiables avec les outils, comme GPT 5.5. Si le modèle n’utilise pas cet outil et renvoie un texte final substantiel, OpenClaw garde ce texte final privé au lieu de le publier dans le salon.

Utilisez "automatic" pour les modèles ou runtimes plus faibles qui ne comprennent pas de manière fiable la livraison uniquement par outil. En mode automatique, le texte final de l’assistant est le chemin de réponse visible source, donc un modèle qui ne peut pas appeler systématiquement message(action=send) peut quand même répondre normalement.

En mode automatique, les réponses finales en texte normal sont publiées directement dans le salon. Si la réponse visible nécessite des fichiers, des images ou d’autres pièces jointes, l’agent peut tout de même utiliser message(action=send) pour cette pièce jointe au lieu d’essayer de la faire passer par la réponse textuelle finale.

Si l’outil de message n’est pas disponible sous la politique d’outils active, OpenClaw revient aux réponses visibles automatiques au lieu de supprimer silencieusement la réponse. openclaw doctor avertit de cette incohérence.

Pour les discussions directes et tout autre événement source, utilisez messages.visibleReplies: "message_tool" afin d’appliquer globalement le même comportement de réponse visible uniquement par outil. Les tours directs WebChat internes utilisent par défaut la livraison automatique de réponse finale afin que Pi et Codex reçoivent le même contrat de réponse visible. Définissez messages.visibleReplies: "message_tool" pour exiger intentionnellement message(action=send) pour la sortie visible. messages.groupChat.visibleReplies reste le remplacement plus spécifique pour les salons de groupe/canal.

Cela remplace l’ancien modèle qui forçait le modèle à répondre NO_REPLY pour la plupart des tours en mode observation. En mode uniquement par outil, le prompt ne définit pas de contrat NO_REPLY. Ne rien faire de visible signifie simplement ne pas appeler l’outil de message.

Les liaisons de conversation détenues par un Plugin sont l’exception. Une fois qu’un Plugin lie un fil et revendique le tour entrant, la réponse renvoyée par le Plugin est la réponse de liaison visible ; elle n’a pas besoin de message(action=send). Cette réponse est une sortie du runtime du Plugin, et non le texte final privé du modèle.

Les indicateurs de saisie sont toujours envoyés pour les demandes directes de groupe. Les événements de salon ambiant toujours actifs, lorsqu’ils sont activés, restent stricts et discrets sauf si l’agent appelle l’outil de message.

Les sessions suppriment par défaut les résumés détaillés d’outils/progression. Utilisez /verbose on pour afficher ces résumés pour la session actuelle pendant le débogage, et /verbose off pour revenir au comportement limité à la réponse finale. Le même état détaillé s’applique aux discussions directes, groupes, canaux et sujets de forum.

Pour soumettre les échanges de groupe toujours actifs non mentionnés comme contexte de salon discret au lieu de demandes utilisateur, utilisez Événements de salon ambiant :

{  messages: {    groupChat: {      unmentionedInbound: "room_event",    },  },}

La valeur par défaut est unmentionedInbound: "user_request".

Les messages mentionnés, commandes, demandes d’arrêt et DM restent des demandes utilisateur.

Pour exiger que la sortie visible passe par l’outil de message pour les demandes de groupe/canal :

{  messages: {    groupChat: {      visibleReplies: "message_tool",    },  },}

Le Gateway recharge à chaud la configuration messages après l’enregistrement du fichier. Redémarrez uniquement lorsque la surveillance des fichiers ou le rechargement de la configuration est désactivé dans le déploiement.

Pour exiger que la sortie visible passe par l’outil de message pour chaque discussion source :

{  messages: {    visibleReplies: "message_tool",  },}

Les commandes slash natives (Discord, Telegram et autres surfaces avec prise en charge des commandes natives) contournent visibleReplies: "message_tool" et répondent toujours visiblement afin que l’interface de commande native du canal reçoive la réponse attendue. Cela s’applique uniquement aux tours de commandes natives validées ; les commandes /... saisies en texte et les tours de discussion ordinaires suivent toujours la valeur par défaut de groupe configurée.

Visibilité du contexte et listes d’autorisation

Deux contrôles différents interviennent dans la sécurité des groupes :

• Autorisation de déclenchement : qui peut déclencher l’agent (groupPolicy, groups, groupAllowFrom, listes d’autorisation propres au canal).
• Visibilité du contexte : quel contexte supplémentaire est injecté dans le modèle (texte de réponse, citations, historique du fil, métadonnées transférées).

Par défaut, OpenClaw privilégie le comportement normal des discussions et conserve le contexte majoritairement tel qu’il est reçu. Cela signifie que les listes d’autorisation décident principalement qui peut déclencher des actions, et ne constituent pas une limite universelle de rédaction pour chaque extrait cité ou historique.

Si vous voulez...

Pour les listes d’autorisation d’expéditeurs réutilisables, consultez Groupes d’accès.

Clés de session

• Les sessions de groupe utilisent des clés de session agent:<agentId>:<channel>:group:<id> (les salons/canaux utilisent agent:<agentId>:<channel>:channel:<id>).
• Les sujets de forum Telegram ajoutent :topic:<threadId> à l’identifiant de groupe afin que chaque sujet ait sa propre session.
• Les discussions directes utilisent la session principale (ou une session par expéditeur si configuré).
• Les Heartbeats sont ignorés pour les sessions de groupe.

Modèle : DM personnels + groupes publics (agent unique)

Oui — cela fonctionne bien si votre trafic « personnel » correspond aux DM et votre trafic « public » aux groupes.

Pourquoi : en mode agent unique, les DM arrivent généralement dans la clé de session principale (agent:main:main), tandis que les groupes utilisent toujours des clés de session non principales (agent:main:<channel>:group:<id>). Si vous activez le sandboxing avec mode: "non-main", ces sessions de groupe s’exécutent dans le backend de sandbox configuré, tandis que votre session DM principale reste sur l’hôte. Docker est le backend par défaut si vous n’en choisissez pas.

Cela vous donne un « cerveau » d’agent unique (espace de travail + mémoire partagés), mais deux postures d’exécution :

• DM : outils complets (hôte)
• Groupes : sandbox + outils restreints

{  agents: {    defaults: {      sandbox: {        mode: "non-main", // groups/channels are non-main -> sandboxed        scope: "session", // strongest isolation (one container per group/channel)        workspaceAccess: "none",      },    },  },  tools: {    sandbox: {      tools: {        // If allow is non-empty, everything else is blocked (deny still wins).        allow: ["group:messaging", "group:sessions"],        deny: ["group:runtime", "group:fs", "group:ui", "nodes", "cron", "gateway"],      },    },  },}

{  agents: {    defaults: {      sandbox: {        mode: "non-main",        scope: "session",        workspaceAccess: "none",        docker: {          binds: [            // hostPath:containerPath:mode            "/home/user/FriendsShared:/data:ro",          ],        },      },    },  },}

Connexe :

• Clés de configuration et valeurs par défaut : Configuration du Gateway
• Déboguer pourquoi un outil est bloqué : Sandbox vs politique d’outils vs élevé
• Détails des montages bind : Sandboxing

Libellés d’affichage

• Les libellés d’interface utilisent displayName lorsqu’il est disponible, formaté comme <channel>:<token>.
• #room est réservé aux salons/canaux ; les discussions de groupe utilisent g-<slug> (minuscules, espaces -> -, conserver #@+._-).

Politique de groupe

Contrôlez la manière dont les messages de groupe/salon sont traités par canal :

{  channels: {    whatsapp: {      groupPolicy: "disabled", // "open" | "disabled" | "allowlist"      groupAllowFrom: ["+15551234567"],    },    telegram: {      groupPolicy: "disabled",      groupAllowFrom: ["123456789"], // identifiant utilisateur Telegram numérique (l’assistant de configuration peut résoudre @username)    },    signal: {      groupPolicy: "disabled",      groupAllowFrom: ["+15551234567"],    },    imessage: {      groupPolicy: "disabled",      groupAllowFrom: ["chat_id:123"],    },    msteams: {      groupPolicy: "disabled",      groupAllowFrom: ["user@org.com"],    },    discord: {      groupPolicy: "allowlist",      guilds: {        GUILD_ID: { channels: { help: { allow: true } } },      },    },    slack: {      groupPolicy: "allowlist",      channels: { "#general": { allow: true } },    },    matrix: {      groupPolicy: "allowlist",      groupAllowFrom: ["@owner:example.org"],      groups: {        "!roomId:example.org": { enabled: true },        "#alias:example.org": { enabled: true },      },    },  },}

Modèle mental rapide (ordre d’évaluation des messages de groupe) :

Filtrage par mention (par défaut)

Les messages de groupe exigent une mention, sauf remplacement par groupe. Les valeurs par défaut résident par sous-système sous *.groups."*".

Répondre à un message du bot compte comme une mention implicite lorsque le canal prend en charge les métadonnées de réponse. Citer un message du bot peut également compter comme une mention implicite sur les canaux qui exposent les métadonnées de citation. Les cas intégrés actuels incluent Telegram, WhatsApp, Slack, Discord, Microsoft Teams et ZaloUser.

{  channels: {    whatsapp: {      groups: {        "*": { requireMention: true },        "123@g.us": { requireMention: false },      },    },    telegram: {      groups: {        "*": { requireMention: true },        "123456789": { requireMention: false },      },    },    imessage: {      groups: {        "*": { requireMention: true },        "123": { requireMention: false },      },    },  },  agents: {    list: [      {        id: "main",        groupChat: {          mentionPatterns: ["@openclaw", "openclaw", "\\+15555550123"],          historyLimit: 50,        },      },    ],  },}

Portée des motifs de mention configurés

Les mentionPatterns configurés sont des déclencheurs de repli regex. Utilisez-les lorsque la plateforme n’expose pas de mention native du bot, ou lorsque vous voulez qu’un texte brut tel que openclaw: compte comme une mention. Les mentions natives de plateforme sont distinctes : lorsque Discord, Slack, Telegram, Matrix ou un autre canal peut prouver que le message a explicitement mentionné le bot, cette mention native déclenche toujours même si les motifs regex configurés sont refusés.

Par défaut, les motifs de mention configurés s’appliquent partout où ce canal transmet les faits de fournisseur et de conversation à la détection de mention. Pour éviter que des motifs larges ne réveillent l’agent dans chaque groupe, limitez-les par canal avec channels.<channel>.mentionPatterns.

Utilisez mode: "deny" lorsque les motifs de mention regex doivent être désactivés par défaut pour un canal, puis activez-les dans des salons précis avec allowIn :

{  messages: {    groupChat: {      mentionPatterns: ["\\bopenclaw\\b", "\\bops bot\\b"],    },  },  channels: {    slack: {      mentionPatterns: {        mode: "deny",        allowIn: ["C0123OPS"],      },    },  },}

Utilisez le mode: "allow" par défaut (ou omettez mode) lorsque les motifs de mention regex doivent s’appliquer largement, puis désactivez-les dans les salons bruyants avec denyIn :

{  messages: {    groupChat: {      mentionPatterns: ["\\bopenclaw\\b"],    },  },  channels: {    telegram: {      mentionPatterns: {        denyIn: ["-1001234567890", "-1001234567890:topic:42"],      },    },  },}

Résolution de la stratégie :

Stratégie regex à portée limitée prise en charge aujourd’hui :

Les configurations de canal au niveau du compte peuvent définir la même stratégie sous channels.<channel>.accounts.<accountId>.mentionPatterns lorsque ce canal prend en charge plusieurs comptes. La stratégie de compte est prioritaire sur la stratégie de canal de niveau supérieur pour ce compte.

Restrictions d’outils par groupe/canal (facultatif)

Certaines configurations de canal prennent en charge la restriction des outils disponibles dans un groupe/salon/canal spécifique.

• tools : autoriser/refuser des outils pour tout le groupe.
• toolsBySender : remplacements par expéditeur dans le groupe. Utilisez des préfixes de clé explicites : channel:<channelId>:<senderId>, id:<senderId>, e164:<phone>, username:<handle>, name:<displayName> et le joker "*". Les ID de canal utilisent les ID de canal OpenClaw canoniques ; les alias tels que teams sont normalisés en msteams. Les anciennes clés sans préfixe sont toujours acceptées et correspondent uniquement à id:.

Ordre de résolution (le plus spécifique l’emporte) :

Exemple (Telegram) :

{  channels: {    telegram: {      groups: {        "*": { tools: { deny: ["exec"] } },        "-1001234567890": {          tools: { deny: ["exec", "read", "write"] },          toolsBySender: {            "id:123456789": { alsoAllow: ["exec"] },          },        },      },    },  },}

Listes d’autorisation de groupe

Lorsque channels.whatsapp.groups, channels.telegram.groups ou channels.imessage.groups est configuré, les clés agissent comme liste d’autorisation de groupe. Utilisez "*" pour autoriser tous les groupes tout en définissant le comportement de mention par défaut.

Intentions courantes (copier/coller) :

{  channels: { whatsapp: { groupPolicy: "disabled" } },}

{  channels: {    whatsapp: {      groups: {        "123@g.us": { requireMention: true },        "456@g.us": { requireMention: false },      },    },  },}

{  channels: {    whatsapp: {      groups: { "*": { requireMention: true } },    },  },}

{  channels: {    whatsapp: {      groupPolicy: "allowlist",      groupAllowFrom: ["+15551234567"],      groups: { "*": { requireMention: true } },    },  },}

Activation (propriétaire uniquement)

Les propriétaires de groupe peuvent activer ou désactiver l’activation par groupe :

• /activation mention
• /activation always

Le propriétaire est déterminé par channels.whatsapp.allowFrom (ou par le numéro E.164 du bot lui-même si ce champ n’est pas défini). Envoyez la commande sous forme de message autonome. Les autres surfaces ignorent actuellement /activation.

Champs de contexte

Les charges utiles entrantes de groupe définissent :

• ChatType=group
• GroupSubject (si connu)
• GroupMembers (si connu)
• WasMentioned (résultat du filtrage par mention)
• Les sujets de forum Telegram incluent également MessageThreadId et IsForum.

Le prompt système de l’agent inclut une introduction de groupe au premier tour d’une nouvelle session de groupe. Il rappelle au modèle de répondre comme un humain, de réduire les lignes vides, de respecter l’espacement normal d’une conversation et d’éviter de saisir des séquences littérales \n. Les groupes non Telegram déconseillent également les tableaux Markdown ; les consignes de texte enrichi Telegram proviennent du prompt du canal Telegram. Les noms de groupe et libellés de participants provenant du canal sont rendus comme des métadonnées non fiables dans un bloc délimité, et non comme des instructions système en ligne.

Spécificités iMessage

• Préférez chat_id:<id> pour le routage ou les listes d’autorisation.
• Lister les conversations : imsg chats --limit 20.
• Les réponses de groupe retournent toujours au même chat_id.

Prompts système WhatsApp

Consultez WhatsApp pour les règles canoniques des prompts système WhatsApp, y compris la résolution des prompts de groupe et directs, le comportement des jokers et la sémantique de remplacement au niveau du compte.

Spécificités WhatsApp

Consultez Messages de groupe pour le comportement propre à WhatsApp (injection d’historique, détails de gestion des mentions).

Connexe

• Groupes de diffusion
• Routage des canaux
• Messages de groupe
• Appairage