Groupes

OpenClaw traite les discussions de groupe de façon cohérente sur toutes les surfaces : Discord, iMessage, Matrix, Microsoft Teams, Signal, Slack, Telegram, WhatsApp, Zalo.

# Introduction pour débutants (2 minutes)

OpenClaw « vit » sur vos propres comptes de messagerie. Il n’existe 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 finales normales dans les groupes/canaux sont privées par défaut. La sortie visible dans la salle utilise l’outil message.

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

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

# Réponses visibles

Pour les salles de groupe/canal, OpenClaw utilise par défaut messages.groupChat.visibleReplies: "message_tool". openclaw doctor --fix écrit cette valeur par défaut dans les configurations de canaux configurés qui ne l’indiquent pas. Cela signifie que l’agent traite toujours le tour et peut mettre à jour l’état de la mémoire/session, mais sa réponse finale normale n’est pas automatiquement publiée dans la salle. Pour parler de façon visible, l’agent utilise message(action=send).

Cette valeur par défaut dépend d’un modèle/environnement d’exécution qui appelle les outils de manière fiable. Si les journaux affichent du texte assistant mais didSendViaMessagingTool: false, le modèle a répondu en privé au lieu d’appeler l’outil de messagerie. Ce n’est pas un échec d’envoi Discord/Slack/Telegram. Utilisez un modèle fiable pour les appels d’outils dans les sessions de groupe/canal, ou définissez messages.groupChat.visibleReplies: "automatic" pour rétablir les anciennes réponses finales visibles.

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 avertit de cette incohérence.

Pour les discussions directes et tout autre tour source, utilisez messages.visibleReplies: "message_tool" afin d’appliquer globalement le même comportement de réponse visible uniquement via outil. Les harnais peuvent aussi choisir cette valeur comme valeur par défaut non définie ; le harnais Codex le fait pour les discussions directes en mode Codex. messages.groupChat.visibleReplies reste la surcharge plus spécifique pour les salles 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 via outil, ne rien rendre visible signifie simplement ne pas appeler l’outil de messagerie.

Les indicateurs de saisie sont toujours envoyés pendant que l’agent travaille en mode uniquement via outil. Le mode de saisie de groupe par défaut passe de "message" à "instant" pour ces tours, car il se peut qu’il n’y ait jamais de texte de message assistant normal avant que l’agent décide d’appeler ou non l’outil de messagerie. La configuration explicite du mode de saisie reste prioritaire.

Pour rétablir les anciennes réponses finales automatiques pour les salles de groupe/canal :

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

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 configuration est désactivé dans le déploiement.

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

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

Les commandes slash natives (Discord, Telegram et autres surfaces avec prise en charge native des commandes) contournent visibleReplies: "message_tool" et répondent toujours de façon visible afin que l’interface de commande native du canal reçoive la réponse attendue. Cela s’applique uniquement aux tours de commande native validés ; 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 distincts 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 de fil, métadonnées transférées).

Par défaut, OpenClaw privilégie le comportement normal de discussion et conserve le contexte principalement tel qu’il est reçu. Cela signifie que les listes d’autorisation déterminent surtout qui peut déclencher des actions, et ne constituent pas une frontière universelle de caviardage 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 salles/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 seul « cerveau » d’agent (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",
          ],
        },
      },
    },
  },
}

Liens associés :

• 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 élévation
• Détails des montages bind : Sandboxing

# Libellés d’affichage

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

# Politique de groupe

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

{
  channels: {
    whatsapp: {
      groupPolicy: "disabled", // "open" | "disabled" | "allowlist"
      groupAllowFrom: ["+15551234567"],
    },
    telegram: {
      groupPolicy: "disabled",
      groupAllowFrom: ["123456789"], // numeric Telegram user id (wizard can resolve @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": { 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 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 aussi 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 },
        "[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,
        },
      },
    ],
  },
}

# Restrictions d’outils par groupe/canal (facultatif)

Certaines configurations de canaux permettent de restreindre les outils disponibles dans un groupe, une salle ou un canal spécifique.

• tools : autorise/refuse des outils pour tout le groupe.
• toolsBySender : remplacements par expéditeur au sein du groupe. Utilisez des préfixes de clés explicites : id:<senderId>, e164:<phone>, username:<handle>, name:<displayName>, et le caractère générique "*". Les anciennes clés sans préfixe sont toujours acceptées et ne correspondent qu’à 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 groupes

Lorsque channels.whatsapp.groups, channels.telegram.groups ou channels.imessage.groups est configuré, les clés agissent comme une liste d’autorisation de groupes. 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: {
        "[email protected]": { requireMention: true },
        "[email protected]": { 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 basculer 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 propre au bot lorsqu’il n’est pas défini). Envoyez la commande comme 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 connus)
• WasMentioned (résultat du filtrage par mention)
• Les sujets de forum Telegram incluent également MessageThreadId et IsForum.

Notes propres aux canaux :

• BlueBubbles peut, facultativement, enrichir les participants de groupes macOS sans nom à partir de la base de données locale Contacts avant de remplir GroupMembers. Cette option est désactivée par défaut et ne s’exécute qu’après la réussite du filtrage normal de groupe.

L’invite système de l’agent inclut une introduction de groupe au premier tour d’une nouvelle session de groupe. Elle rappelle au modèle de répondre comme un humain, d’éviter les tableaux Markdown, de minimiser les lignes vides, de respecter l’espacement normal d’une discussion et d’éviter de saisir des séquences littérales \n. Les noms de groupes et libellés de participants issus du canal sont rendus comme métadonnées non fiables dans des blocs de code, et non comme instructions système en ligne.

# Spécificités d’iMessage

• Préférez chat_id:<id> lors du routage ou de l’ajout à une liste d’autorisation.
• Lister les discussions : imsg chats --limit 20.
• Les réponses de groupe reviennent toujours au même chat_id.

# Invites système WhatsApp

Consultez WhatsApp pour les règles canoniques des invites système WhatsApp, y compris la résolution des invites de groupe et directes, le comportement des caractères génériques et la sémantique de remplacement par compte.

# Spécificités de 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