Groupes

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

Introduction pour débutants (2 minutes)

OpenClaw « vit » sur vos propres comptes de messagerie. Il n’y a 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 réponses nécessitent une mention, sauf si vous désactivez explicitement le filtrage par mention.

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

TL;DR

L’accès DM est contrôlé par *.allowFrom.

L’accès aux groupes est contrôlé par *.groupPolicy + listes d’autorisation (*.groups, *.groupAllowFrom).

Le déclenchement des réponses est contrôlé par le filtrage par mention (requireMention, /activation).

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

groupPolicy? disabled -> drop
groupPolicy? allowlist -> group allowed? no -> drop
requireMention? yes -> mentioned? no -> store for context only
otherwise -> reply

Flux des messages de groupe

Si vous souhaitez…

Objectif	Ce qu’il faut définir
Autoriser tous les groupes mais répondre uniquement aux @mentions	`groups: { "*": { requireMention: true } }`
Désactiver toutes les réponses de groupe	`groupPolicy: "disabled"`
Seuls des groupes spécifiques	`groups: { "<group-id>": { ... } }` (pas de clé `"*"`)
Seul vous pouvez déclencher dans les groupes	`groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]`

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 du groupe afin que chaque sujet ait sa propre session.
Les discussions directes utilisent la session principale (ou par expéditeur si configuré).
Les battements de cœur (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 » est constitué de DMs et votre trafic « public » de groupes.

Pourquoi : en mode mono-agent, les DMs atterrissent 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’isolation (sandboxing) avec mode: "non-main", ces sessions de groupe s’exécutent dans Docker tandis que votre session DM principale reste sur l’hôte.

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

DMs : outils complets (hôte)
Groupes : sandbox + outils restreints (Docker)

Si vous avez besoin d’espaces de travail ou de personnalités véritablement séparés (le « personnel » et le « public » ne doivent jamais être mélangés), utilisez un second agent + liaisons. Voir Multi-Agent Routing.

Exemple (DMs sur l’hôte, groupes isolés + outils de messagerie uniquement) :

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

Vous préférez « les groupes peuvent uniquement voir le dossier X » plutôt que « pas d’accès hôte » ? Gardez workspaceAccess: "none" et montez uniquement les chemins autorisés dans le sandbox :

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

Connexes :

Clés de configuration et valeurs par défaut : configuration Gateway
Débogage du blocage d’un outil : Sandbox vs Tool Policy vs Elevated
Détails des montages de liaison (bind mounts) : Sandboxing

Libellés d’affichage

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

Stratégie de groupe

Contrôlez la façon dont les messages de groupe/salon sont gérés par channel :

{
  channels: {
    whatsapp: {
      groupPolicy: "disabled", // "open" | "disabled" | "allowlist"
      groupAllowFrom: ["+15551234567"],
    },
    telegram: {
      groupPolicy: "disabled",
      groupAllowFrom: ["123456789", "@username"],
    },
    signal: {
      groupPolicy: "disabled",
      groupAllowFrom: ["+15551234567"],
    },
    imessage: {
      groupPolicy: "disabled",
      groupAllowFrom: ["chat_id:123"],
    },
    msteams: {
      groupPolicy: "disabled",
      groupAllowFrom: ["[email protected]"],
    },
    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": { allow: true },
        "#alias:example.org": { allow: true },
      },
    },
  },
}

Stratégie	Comportement
`"open"`	Les groupes contournent les listes d’autorisation ; le filtrage par mention s’applique toujours.
`"disabled"`	Bloquer tous les messages de groupe entièrement.
`"allowlist"`	Autoriser uniquement les groupes/salons correspondant à la liste d’autorisation configurée.

Notes :

groupPolicy est distinct du filtrage par mentions (qui nécessite des @mentions).
WhatsApp/Telegram/Signal/iMessage/Microsoft Teams : utilisez groupAllowFrom (repli : allowFrom explicite).
Discord : la liste d’autorisation utilise channels.discord.guilds.<id>.channels.
Slack : la liste d’autorisation utilise channels.slack.channels.
Matrix : la liste d’autorisation utilise channels.matrix.groups (identifiants de salle, alias ou noms). Utilisez channels.matrix.groupAllowFrom pour restreindre les expéditeurs ; les listes d’autorisation users par salle sont également prises en charge.
Les messages de groupe (DMs) sont contrôlés séparément (channels.discord.dm.*, channels.slack.dm.*).
La liste d’autorisation Telegram peut correspondre aux identifiants utilisateur ("123456789", "telegram:123456789", "tg:123456789") ou aux noms d’utilisateur ("@alice" ou "alice") ; les préfixes ne sont pas sensibles à la casse.
La valeur par défaut est groupPolicy: "allowlist" ; si votre liste d’autorisation de groupe est vide, les messages de groupe sont bloqués.

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

groupPolicy (ouvert/désactivé/liste d’autorisation)
listes d’autorisation de groupe (*.groups, *.groupAllowFrom, liste d’autorisation spécifique au channel)
filtrage par mentions (requireMention, /activation)

Filtrage par mentions (par défaut)

Les messages de groupe nécessitent une mention, sauf si la règle est outrepassée pour un groupe spécifique. Les valeurs par défaut se trouvent par sous-système sous *.groups."*".

Répondre à un message du bot compte comme une mention implicite (lorsque le channel prend en charge les métadonnées de réponse). Cela s’applique à Telegram, WhatsApp, Slack, Discord et Microsoft Teams.

{
  channels: {
    whatsapp: {
      groups: {
        "*": { requireMention: true },
        "[email protected]": { 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,
        },
      },
    ],
  },
}

Notes :

Les mentionPatterns sont des expressions régulières insensibles à la casse.
Les surfaces qui fournissent des mentions explicites passent toujours ; les modèles constituent un repli.
Outrepassage par agent : agents.list[].groupChat.mentionPatterns (utile lorsque plusieurs agents partagent un groupe).
Le filtrage des mentions n’est appliqué que lorsque la détection des mentions est possible (mentions natives ou mentionPatterns configurées).
Les valeurs par défaut Discord se trouvent dans channels.discord.guilds."*" (surchargeable par guilde/channel).
Le contexte de l’historique de groupe est enveloppé de manière uniforme sur les channels et est en attente uniquement (messages ignorés en raison du filtrage des mentions) ; utilisez messages.groupChat.historyLimit pour la valeur par défaut globale et channels.<channel>.historyLimit (ou channels.<channel>.accounts.*.historyLimit) pour les surcharges. Définissez 0 pour désactiver.

Restrictions d’outils de groupe/channel (optionnel)

Certaines configurations de channel prennent en charge la restriction des outils disponibles à l’intérieur d’un groupe/salle/channel spécifique.

tools : autoriser/refuser les outils pour l’ensemble du groupe.
toolsBySender : surcharges par expéditeur au sein du groupe (les clés sont les ID d’expéditeur/noms d’utilisateur/e-mails/numéros de téléphone selon le channel). Utilisez "*" comme caractère générique.

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

correspondance du groupe/channel toolsBySender
groupe/channel tools
correspondance toolsBySender par défaut ("*")
tools par défaut ("*")

Exemple (Telegram) :

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

Notes :

Les restrictions d’outils de groupe/channel sont appliquées en plus de la stratégie d’outil global/de l’agent (le refus l’emporte toujours).
Certains channels utilisent une imbrication différente pour les salles/channels (par exemple, Discord guilds.*.channels.*, Slack channels.*, MS Teams teams.*.channels.*).

Listes blanches de groupes

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

Intentions courantes (copier/coller) :

Désactiver toutes les réponses de groupe

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

Autoriser uniquement des groupes spécifiques (WhatsApp)

{
  channels: {
    whatsapp: {
      groups: {
        "[email protected]": { requireMention: true },
        "[email protected]": { requireMention: false },
      },
    },
  },
}

Autoriser tous les groupes mais exiger une mention (explicite)

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

Seul le propriétaire peut déclencher dans les groupes (WhatsApp)

{
  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 l’E.164 du bot lui-même s’il n’est pas défini). Envoyez la commande sous forme de message autonome. Les autres surfaces ignorent actuellement /activation.

Champs de contexte

Les payloads entrants de groupe définissent :

ChatType=group
GroupSubject (si connu)
GroupMembers (si connu)
WasMentioned (résultat du filtrage des mentions)
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, d’éviter les tableaux Markdown et d’éviter de taper des séquences \n littérales.

Spécificités iMessage

Privilégiez chat_id:<id> lors du routage ou de la liste blanche.
Lister les chats : imsg chats --limit 20.
Les réponses de groupe reviennent toujours au même chat_id.

Spécificités WhatsApp

Voir Group messages pour les comportements exclusifs à WhatsApp (injection de l’historique, détails de la gestion des mentions).