Groupes

OpenClaw applique les mêmes règles de groupe à tous les canaux prenant en charge les groupes, notamment Discord, iMessage, Matrix, Microsoft Teams, QQBot, Signal, Slack, Telegram, WhatsApp et 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 ambiants.

Présentation pour débutants (2 minutes)

OpenClaw « vit » sur vos propres comptes de messagerie. Il n’existe pas d’utilisateur bot WhatsApp distinct : 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 expéditeurs des groupes sont bloqués jusqu’à leur ajout à la liste d’autorisation.
• Les réponses nécessitent une mention, sauf si vous désactivez cette exigence pour un groupe.
• Le texte de la réponse finale est automatiquement publié dans le salon (visibleReplies: "automatic").

En clair : les expéditeurs figurant dans la liste d’autorisation peuvent déclencher OpenClaw en le mentionnant.

Flux rapide (traitement d’un message de groupe) :

groupPolicy ? désactivée -> ignorergroupPolicy ? liste d’autorisation -> groupe autorisé ? non -> ignorerrequireMention ? oui -> mentionné ? non -> stocker uniquement comme contextemention/réponse/commande/message privé -> requête utilisateurconversation d’un groupe toujours actif -> requête utilisateur, ou événement de salon si configuré

Réponses visibles

Pour les requêtes ordinaires de groupe ou de canal, OpenClaw utilise par défaut messages.groupChat.visibleReplies: "automatic" : le texte final de l’assistant est publié dans le salon comme réponse visible.

Utilisez messages.groupChat.visibleReplies: "message_tool" lorsqu’un salon partagé doit laisser l’agent décider quand intervenir en appelant message(action=send). Ce mode fonctionne mieux avec des modèles qui utilisent les outils de manière fiable (par exemple GPT-5.6 Sol). Si le modèle omet l’outil et renvoie un texte final substantiel, OpenClaw conserve ce texte en privé au lieu de le publier dans le salon.

Utilisez "automatic" pour les modèles ou environnements d’exécution qui ne respectent pas de manière fiable l’envoi exclusivement par outil : les textes finaux ordinaires sont publiés directement dans le salon, et l’agent peut toujours appeler message(action=send) pour les fichiers, images ou autres pièces jointes qui ne peuvent pas accompagner le texte final.

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

Pour les conversations directes et tout autre événement source, messages.visibleReplies: "message_tool" applique globalement le même comportement exclusivement par outil ; messages.groupChat.visibleReplies reste la dérogation plus spécifique pour les salons de groupe ou de canal. Les échanges directs du WebChat interne utilisent par défaut l’envoi automatique de la réponse finale afin que Pi et Codex bénéficient du même contrat de réponse visible.

Le mode exclusivement par outil remplace l’ancien modèle qui imposait au modèle de répondre NO_REPLY pour la plupart des échanges en mode observation. Dans ce mode, le prompt ne définit aucun contrat NO_REPLY ; ne rien rendre visible signifie simplement ne pas appeler l’outil de messagerie.

Les liaisons de conversation détenues par un plugin constituent l’exception. Dès qu’un plugin lie un fil de discussion et prend en charge l’échange entrant, la réponse renvoyée par le plugin devient la réponse visible de la liaison ; elle n’a pas besoin de message(action=send). Cette réponse est une sortie de l’environnement d’exécution du plugin, et non le texte final privé du modèle.

Les indicateurs de saisie sont toujours envoyés pour les requêtes directes de groupe. Lorsqu’ils sont activés, les événements ambiants des salons toujours actifs restent stricts et silencieux, sauf si l’agent appelle l’outil de messagerie.

Par défaut, les sessions masquent les résumés détaillés des outils et de la progression. Utilisez /verbose on (ou /verbose full) pour les afficher dans la session actuelle pendant le débogage, et /verbose off pour revenir au comportement limité à la réponse finale. L’état détaillé est propre à chaque session et fonctionne de la même manière dans les conversations directes, les groupes, les canaux et les sujets de forum.

Pour soumettre les conversations non mentionnées des groupes toujours actifs comme contexte discret du salon plutôt que comme requêtes utilisateur, utilisez Événements de salon ambiants :

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

La valeur par défaut est unmentionedInbound: "user_request". Les messages avec mention, les commandes, les demandes d’annulation et les messages privés restent des requêtes utilisateur.

Pour imposer que la sortie visible passe par l’outil de messagerie pour les requêtes de groupe ou de canal :

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

Pour l’imposer à toutes les conversations sources :

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

Le Gateway prend en compte les modifications de configuration de messages sans redémarrage après l’enregistrement du fichier. Redémarrez uniquement si le rechargement de la configuration est désactivé (gateway.reload.mode: "off").

Les échanges de commande contournent visibleReplies: "message_tool" et répondent toujours de manière visible : les commandes slash natives (Discord, Telegram et autres interfaces prenant en charge les commandes natives) ainsi que les commandes textuelles /... autorisées publient leur réponse dans la conversation source. Dans les groupes, les échanges textuels /... non autorisés restent exclusivement traités par l’outil de messagerie ; les échanges de conversation ordinaires suivent la valeur par défaut configurée.

Visibilité du contexte et listes d’autorisation

La sécurité des groupes repose sur deux contrôles distincts :

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

Par défaut, OpenClaw conserve le contexte tel qu’il est reçu : les listes d’autorisation déterminent qui peut déclencher des actions, et non les extraits cités ou historiques visibles par le modèle. Pour filtrer également le contexte supplémentaire, définissez contextVisibility :

Définissez cette valeur par canal (channels.<channel>.contextVisibility), par compte (channels.<channel>.accounts.<accountId>.contextVisibility) ou globalement (channels.defaults.contextVisibility). Les canaux qui récupèrent du contexte supplémentaire (Discord, Feishu, iMessage, Matrix, Microsoft Teams, Signal, Slack, Telegram, WhatsApp) appliquent la politique lors de la création du contexte entrant ; les combinaisons de politiques inconnues échouent de manière sécurisée et omettent le contexte.

Si vous souhaitez...

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 et canaux utilisent agent:<agentId>:<channel>:channel:<id>).
• Les sujets de forum Telegram ajoutent :topic:<threadId> à l’identifiant du groupe afin que chaque sujet dispose de sa propre session.
• Les conversations directes utilisent la session principale (ou des sessions propres à chaque expéditeur si session.dmScope est configuré).
• Les Heartbeats s’exécutent dans la session de heartbeat configurée (par défaut : la session principale de l’agent) ; les sessions de groupe n’exécutent pas leurs propres heartbeats.

Modèle : messages privés personnels et groupes publics (agent unique)

Oui, cela fonctionne bien si votre trafic « personnel » correspond aux messages privés et votre trafic « public » aux groupes.

Explication : en mode agent unique, les messages privés 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 l’environnement isolé avec mode: "non-main", ces sessions de groupe s’exécutent dans le moteur d’environnement isolé configuré, tandis que votre session principale de messages privés reste sur l’hôte. Docker est le moteur par défaut si vous n’en choisissez aucun.

Vous disposez ainsi d’un seul « cerveau » d’agent (espace de travail et mémoire partagés), mais de deux modes d’exécution :

• Messages privés : outils complets (hôte)
• Groupes : environnement isolé et outils restreints

{  agents: {    defaults: {      sandbox: {        mode: "non-main", // les groupes/canaux ne sont pas principaux -> isolés        scope: "session", // isolation la plus forte (un conteneur par groupe/canal)        workspaceAccess: "none",      },    },  },  tools: {    sandbox: {      tools: {        // Si allow n’est pas vide, tout le reste est bloqué (deny reste prioritaire).        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: [            // cheminHôte:cheminConteneur:mode            "/home/user/FriendsShared:/data:ro",          ],        },      },    },  },}

Voir aussi :

• Clés de configuration et valeurs par défaut : Configuration du Gateway
• Déterminer pourquoi un outil est bloqué : Environnement isolé ou politique d’outils ou mode élevé
• Détails des montages liés : Environnement isolé

Libellés d’affichage

• Les libellés de l’interface utilisateur utilisent displayName lorsque cette valeur est disponible, avec le format <channel>:<token>.
• #room est réservé aux salons et canaux ; les conversations de groupe utilisent g-<slug> (minuscules, espaces remplacés par -, conserver #@+._-). Les identifiants opaques très longs sont raccourcis en un jeton stable afin d’éviter d’exposer les identifiants de routage complets dans l’interface utilisateur.

Politique de groupe

Contrôlez le traitement des messages de groupe ou de salon pour chaque canal :

{  channels: {    whatsapp: {      groupPolicy: "disabled", // "open" | "disabled" | "allowlist"      groupAllowFrom: ["+15551234567"],    },    telegram: {      groupPolicy: "disabled",      groupAllowFrom: ["123456789"], // identifiant utilisateur Telegram numérique (la configuration résout @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: { enabled: true } } },      },    },    slack: {      groupPolicy: "allowlist",      channels: { "#general": { enabled: 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 nécessitent une mention, sauf remplacement pour un groupe particulier. Les valeurs par défaut sont définies par sous-système sous *.groups."*".

Répondre à un message du bot compte comme une mention implicite lorsque le canal expose les métadonnées de réponse ; citer un message du bot peut également compter sur les canaux qui exposent les métadonnées de citation. Cas intégrés actuels : Discord, Microsoft Teams, QQBot, Slack, Telegram, WhatsApp et Zalo personnel.

{  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,        },      },    ],  },}

Définir la portée des motifs de mention configurés

Les mentionPatterns configurés sont des déclencheurs de repli sous forme d’expressions régulières. Utilisez-les lorsque la plateforme n’expose pas de mention native du bot, ou lorsque vous souhaitez qu’un texte brut tel que openclaw: compte comme une mention. Les mentions natives de la plateforme sont distinctes : lorsque Discord, Slack, Telegram, Matrix, Signal ou un autre canal peut établir que le message mentionne explicitement le bot, cette mention native déclenche toujours l’agent même si les motifs d’expression régulière configurés sont refusés.

Par défaut, les motifs de mention configurés s’appliquent partout où le canal transmet les informations sur le fournisseur et la conversation à la détection des mentions. Pour éviter que des motifs généraux réveillent l’agent dans chaque groupe, définissez leur portée par canal avec channels.<channel>.mentionPatterns.

Utilisez mode: "deny" lorsque les motifs de mention sous forme d’expressions régulières 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 la valeur par défaut mode: "allow" (ou omettez mode) lorsque les motifs de mention sous forme d’expressions régulières 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 politique :

Politique actuelle de portée des expressions régulières prise en charge :

Les configurations de canal au niveau du compte peuvent définir la même politique sous channels.<channel>.accounts.<accountId>.mentionPatterns lorsque ce canal prend en charge plusieurs comptes. Pour ce compte, la politique du compte prévaut sur la politique globale du canal.

Restrictions des outils par groupe/canal (facultatif)

Certaines configurations de canal permettent de restreindre les outils disponibles dans un groupe/salon/canal précis.

• tools : autorise/refuse des outils pour l’ensemble du groupe (allow, alsoAllow, deny ; le refus prévaut).
• toolsBySender : remplacements par expéditeur au sein du groupe. Utilisez des préfixes de clé explicites : channel:<channelId>:<senderId>, id:<senderId>, e164:<phone>, username:<handle>, name:<displayName> et le caractère générique "*". Les identifiants de canal utilisent les identifiants 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, correspondent uniquement comme id: et génèrent un avertissement d’obsolescence dans le journal.

Ordre de résolution (le plus précis prévaut) :

Exemple (Telegram) :

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

Listes d’autorisation de groupes

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

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 groupes peuvent activer ou désactiver l’activation pour chaque groupe à l’aide d’un message autonome :

• /activation mention
• /activation always

/activation est une commande principale réservée au propriétaire et s’applique uniquement aux discussions de groupe. Le propriétaire est l’expéditeur qui correspond à commands.ownerAllowFrom ; les listes allowFrom du canal contrôlent uniquement l’accès ordinaire au canal et aux commandes. Le mode enregistré remplace le paramètre requireMention de ce groupe sur les canaux qui le consultent (Google Chat, QQBot, Telegram, WhatsApp), et l’introduction de l’invite système du groupe reflète partout le mode actif.

Champs de contexte

Les charges utiles entrantes des groupes 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.

L’invite système de l’agent inclut une introduction de groupe lors du premier tour d’une nouvelle session de groupe (et après une modification de /activation). Elle rappelle au modèle de répondre comme un humain, de réduire au minimum les lignes vides, de respecter l’espacement habituel des discussions et d’éviter de saisir des séquences \n littérales. Les canaux dont le mode de tableau déclaré ne préserve pas les tableaux natifs ou bruts déconseillent également les tableaux Markdown. Les noms de groupes et les libellés de participants provenant des canaux sont rendus sous forme de métadonnées non fiables dans un bloc délimité, et non comme des instructions système intégrées.

Particularités d’iMessage

• Privilégiez chat_id:<id> pour le routage ou l’ajout à une liste d’autorisation.
• Répertorier les discussions : imsg chats --limit 20.
• Les réponses de groupe sont toujours renvoyées vers le même chat_id.

Invites système de WhatsApp

Consultez WhatsApp pour connaître les règles canoniques des invites système de WhatsApp, notamment la résolution des invites de groupe et directes, le comportement des caractères génériques et la sémantique de remplacement au niveau du compte.

Particularités de WhatsApp

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

Pages associées

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