Groupes

OpenClaw traite les discussions de groupe de maniere coherente sur toutes les surfaces : WhatsApp, Telegram, Discord, Slack, Signal, iMessage, Microsoft Teams, Zalo.

Introduction pour debutants (2 minutes)

OpenClaw « vit » sur vos propres comptes de messagerie. Il n’y a pas d’utilisateur bot WhatsApp separe. Si vous etes dans un groupe, OpenClaw peut voir ce groupe et y repondre.

Comportement par defaut :

  • Les groupes sont restreints (groupPolicy: "allowlist").
  • Les reponses necessitent une mention sauf si vous desactivez explicitement le filtrage par mention.

Autrement dit : les expediteurs autorises peuvent declencher OpenClaw en le mentionnant.

En resume

  • L’acces DM est controle par *.allowFrom.
  • L’acces groupe est controle par *.groupPolicy + listes d’autorisation (*.groups, *.groupAllowFrom).
  • Le declenchement des reponses est controle par le filtrage par mention (requireMention, /activation).

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

groupPolicy? disabled -> ignorer
groupPolicy? allowlist -> groupe autorise? non -> ignorer
requireMention? yes -> mentionne? non -> stocker pour contexte uniquement
sinon -> repondre

Flux des messages de groupe

Si vous souhaitez


ObjectifConfiguration
Autoriser tous les groupes mais repondre seulement aux @mentionsgroups: { "*": { requireMention: true } }
Desactiver toutes les reponses de groupegroupPolicy: "disabled"
Seulement des groupes specifiquesgroups: { "<group-id>": { ... } } (pas de cle "*")
Seul vous pouvez declencher dans les groupesgroupPolicy: "allowlist", groupAllowFrom: ["+1555..."]

Cles de session

  • Les sessions de groupe utilisent des cles agent:<agentId>:<channel>:group:<id> (les salons/canaux utilisent agent:<agentId>:<channel>:channel:<id>).
  • Les sujets de forum Telegram ajoutent :topic:<threadId> a l’ID du groupe pour que chaque sujet ait sa propre session.
  • Les discussions directes utilisent la session principale (ou par expediteur si configure).
  • Les heartbeats sont ignores pour les sessions de groupe.

Patron : DMs personnels + groupes publics (agent unique)

Oui — cela fonctionne bien si votre trafic « personnel » est en DMs et votre trafic « public » en groupes.

Raison : en mode agent unique, les DMs atterrissent generalement dans la cle de session principale (agent:main:main), tandis que les groupes utilisent toujours des cles de session non-principales (agent:main:<channel>:group:<id>). Si vous activez le sandboxing avec mode: "non-main", ces sessions de groupe s’executent dans Docker tandis que votre session DM principale reste sur l’hote.

Cela vous donne un seul « cerveau » d’agent (workspace + memoire partages), mais deux postures d’execution :

  • DMs : outils complets (hote)
  • Groupes : sandbox + outils restreints (Docker)

Si vous avez besoin d’espaces de travail/personas vraiment separes (« personnel » et « public » ne doivent jamais se melanger), utilisez un second agent + des bindings. Voir Routage multi-agents.

Exemple (DMs sur l’hote, groupes en sandbox + outils de messagerie uniquement) :

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // les groupes/canaux sont non-main -> sandboxes
        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 bloque (deny a toujours la priorite).
        allow: ["group:messaging", "group:sessions"],
        deny: ["group:runtime", "group:fs", "group:ui", "nodes", "cron", "gateway"],
      },
    },
  },
}

Vous voulez « les groupes ne peuvent voir que le dossier X » au lieu de « pas d’acces hote » ? Gardez workspaceAccess: "none" et montez uniquement les chemins autorises dans le sandbox :

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

Liens connexes :

Labels d’affichage

  • Les labels de l’interface utilisent displayName quand disponible, formates comme <channel>:<token>.
  • #room est reserve pour les salons/canaux ; les discussions de groupe utilisent g-<slug> (minuscules, espaces -> -, conserve #@+._-).

Politique de groupe

Controlez comment les messages de groupe/salon sont geres par canal :

{
  channels: {
    whatsapp: {
      groupPolicy: "disabled", // "open" | "disabled" | "allowlist"
      groupAllowFrom: ["+15551234567"],
    },
    telegram: {
      groupPolicy: "disabled",
      groupAllowFrom: ["123456789"], // ID utilisateur Telegram numerique (l'assistant peut resoudre @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 },
      },
    },
  },
}
PolitiqueComportement
"open"Les groupes contournent les listes d’autorisation ; le filtrage par mention s’applique toujours.
"disabled"Bloque entierement tous les messages de groupe.
"allowlist"N’autorise que les groupes/salons correspondant a la liste d’autorisation configuree.

Remarques :

  • groupPolicy est separe du filtrage par mention (qui exige des @mentions).
  • WhatsApp/Telegram/Signal/iMessage/Microsoft Teams/Zalo : utilisez groupAllowFrom (repli : allowFrom explicite).
  • Les approbations d’appairage DM (entrees *-allowFrom du store) s’appliquent uniquement a l’acces DM ; l’autorisation d’expediteur de groupe reste explicite aux listes d’autorisation de groupe.
  • 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 (IDs de salon, alias ou noms). Utilisez channels.matrix.groupAllowFrom pour restreindre les expediteurs ; des listes users par salon sont aussi prises en charge.
  • Les DMs de groupe sont controles separement (channels.discord.dm.*, channels.slack.dm.*).
  • La liste d’autorisation Telegram peut correspondre aux IDs utilisateur ("123456789", "telegram:123456789", "tg:123456789") ou aux noms d’utilisateur ("@alice" ou "alice") ; les prefixes sont insensibles a la casse.
  • Par defaut c’est groupPolicy: "allowlist" ; si votre liste d’autorisation de groupe est vide, les messages de groupe sont bloques.
  • Securite a l’execution : quand un bloc fournisseur est completement absent (channels.<provider> absent), la politique de groupe se replie sur un mode ferme par defaut (generalement allowlist) au lieu d’heriter de channels.defaults.groupPolicy.

Modele mental rapide (ordre d’evaluation pour les messages de groupe) :

  1. groupPolicy (open/disabled/allowlist)
  2. listes d’autorisation de groupe (*.groups, *.groupAllowFrom, liste d’autorisation specifique au canal)
  3. filtrage par mention (requireMention, /activation)

Filtrage par mention (par defaut)

Les messages de groupe necessitent une mention sauf surcharge par groupe. Les valeurs par defaut vivent par sous-systeme sous *.groups."*".

Repondre a un message du bot compte comme une mention implicite (quand le canal supporte les metadonnees de reponse). Cela s’applique a 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,
        },
      },
    ],
  },
}

Remarques :

  • mentionPatterns sont des regex insensibles a la casse.
  • Les surfaces qui fournissent des mentions explicites passent toujours ; les patterns sont un repli.
  • Surcharge par agent : agents.list[].groupChat.mentionPatterns (utile quand plusieurs agents partagent un groupe).
  • Le filtrage par mention n’est applique que quand la detection de mention est possible (mentions natives ou mentionPatterns sont configures).
  • Les valeurs par defaut Discord vivent dans channels.discord.guilds."*" (surchargeable par guild/canal).
  • Le contexte d’historique de groupe est encapsule uniformement entre les canaux et est en attente uniquement (messages ignores a cause du filtrage par mention) ; utilisez messages.groupChat.historyLimit pour le defaut global et channels.<channel>.historyLimit (ou channels.<channel>.accounts.*.historyLimit) pour les surcharges. Mettez 0 pour desactiver.

Restrictions d’outils par groupe/canal (optionnel)

Certaines configurations de canal supportent la restriction des outils disponibles a l’interieur d’un groupe/salon/canal specifique.

  • tools : autoriser/interdire des outils pour tout le groupe.
  • toolsBySender : surcharges par expediteur dans le groupe. Utilisez des prefixes de cle explicites : id:<senderId>, e164:<phone>, username:<handle>, name:<displayName>, et le joker "*". Les cles legacy non prefixees sont toujours acceptees et correspondent uniquement a id:.

Ordre de resolution (le plus specifique l’emporte) :

  1. correspondance toolsBySender du groupe/canal
  2. tools du groupe/canal
  3. correspondance toolsBySender par defaut ("*")
  4. tools par defaut ("*")

Exemple (Telegram) :

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

Remarques :

  • Les restrictions d’outils de groupe/canal sont appliquees en plus de la politique d’outils globale/agent (deny l’emporte toujours).
  • Certains canaux utilisent une imbrication differente pour les salons/canaux (ex : Discord guilds.*.channels.*, Slack channels.*, MS Teams teams.*.channels.*).

Listes d’autorisation de groupe

Quand channels.whatsapp.groups, channels.telegram.groups, ou channels.imessage.groups est configure, les cles agissent comme liste d’autorisation de groupe. Utilisez "*" pour autoriser tous les groupes tout en definissant le comportement de mention par defaut.

Intentions courantes (copier/coller) :

  1. Desactiver toutes les reponses de groupe
{
  channels: { whatsapp: { groupPolicy: "disabled" } },
}
  1. N’autoriser que des groupes specifiques (WhatsApp)
{
  channels: {
    whatsapp: {
      groups: {
        "[email protected]": { requireMention: true },
        "[email protected]": { requireMention: false },
      },
    },
  },
}
  1. Autoriser tous les groupes mais exiger une mention (explicite)
{
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } },
    },
  },
}
  1. Seul le proprietaire peut declencher dans les groupes (WhatsApp)
{
  channels: {
    whatsapp: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
      groups: { "*": { requireMention: true } },
    },
  },
}

Activation (proprietaire uniquement)

Les proprietaires de groupe peuvent basculer l’activation par groupe :

  • /activation mention
  • /activation always

Le proprietaire est determine par channels.whatsapp.allowFrom (ou le E.164 propre du bot quand non defini). Envoyez la commande comme message autonome. Les autres surfaces ignorent actuellement /activation.

Champs de contexte

Les charges utiles entrantes de groupe definissent :

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

Le prompt systeme de l’agent inclut une introduction de groupe au premier tour d’une nouvelle session de groupe. Il rappelle au modele de repondre comme un humain, d’eviter les tableaux Markdown et d’eviter de taper des sequences \n litterales.

Specificites iMessage

  • Preferez chat_id:<id> pour le routage ou les listes d’autorisation.
  • Listez les chats : imsg chats --limit 20.
  • Les reponses de groupe retournent toujours au meme chat_id.

Specificites WhatsApp

Voir Messages de groupe pour le comportement specifique a WhatsApp (injection d’historique, details du traitement des mentions).

arrow_back
Précédent
Group Messages
Suivant
Broadcast Groups
arrow_forward