Groepen

OpenClaw behandelt groepschats consistent over alle platforms: WhatsApp, Telegram, Discord, Slack, Signal, iMessage, Microsoft Teams, Zalo.

Beginners-introductie (2 minuten)

OpenClaw “leeft” op je eigen berichtenaccounts. Er is geen apart WhatsApp-botgebruiker. Als jij in een groep zit, kan OpenClaw die groep zien en er reageren.

Standaardgedrag:

Groepen zijn beperkt (groupPolicy: "allowlist").
Antwoorden vereisen een vermelding tenzij je mention-gating expliciet uitschakelt.

Vertaald: afzenders op de allowlist kunnen OpenClaw triggeren door het te vermelden.

Samenvatting

DM-toegang wordt beheerd door *.allowFrom.

Groepstoegang wordt beheerd door *.groupPolicy + allowlists (*.groups, *.groupAllowFrom).

Antwoord-triggering wordt beheerd door mention-gating (requireMention, /activation).

Snel schema (wat er met een groepsbericht gebeurt):

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

Group message flow

Als je wilt…

Doel	Wat in te stellen
Alle groepen toestaan maar alleen antwoorden op @mentions	`groups: { "*": { requireMention: true } }`
Alle groepsantwoorden uitschakelen	`groupPolicy: "disabled"`
Alleen specifieke groepen	`groups: { "<group-id>": { ... } }` (geen `"*"`-sleutel)
Alleen jij kunt triggeren in groepen	`groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]`

Sessiesleutels

Groepssessies gebruiken sessiesleutels agent:<agentId>:<channel>:group:<id> (kamers/kanalen gebruiken agent:<agentId>:<channel>:channel:<id>).
Telegram-forumonderwerpen voegen :topic:<threadId> toe aan het groeps-ID zodat elk onderwerp een eigen sessie heeft.
Directe chats gebruiken de hoofdsessie (of per-afzender indien geconfigureerd).
Heartbeats worden overgeslagen voor groepssessies.

Patroon: persoonlijke DM’s + openbare groepen (enkele agent)

Ja — dit werkt goed als je “persoonlijke” verkeer DM’s zijn en je “openbare” verkeer groepen.

Waarom: in single-agent-modus landen DM’s doorgaans in de hoofd-sessiesleutel (agent:main:main), terwijl groepen altijd niet-hoofd-sessiesleutels gebruiken (agent:main:<channel>:group:<id>). Als je sandboxing inschakelt met mode: "non-main", draaien die groepssessies in Docker terwijl je hoofd-DM-sessie op de host blijft.

Dit geeft je een agent-”brein” (gedeelde werkruimte + geheugen), maar twee uitvoeringsposities:

DM’s: volledige tools (host)
Groepen: sandbox + beperkte tools (Docker)

Als je echt gescheiden werkruimtes/persona’s nodig hebt (“persoonlijk” en “openbaar” mogen nooit mengen), gebruik dan een tweede agent + bindings. Zie Multi-Agent Routing.

Voorbeeld (DM’s op host, groepen gesandboxed + alleen berichtentools):

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

Wil je “groepen kunnen alleen map X zien” in plaats van “geen hosttoegang”? Houd workspaceAccess: "none" en mount alleen toegestane paden in de sandbox:

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

Gerelateerd:

Configuratiesleutels en standaarden: Gateway-configuratie
Debuggen waarom een tool geblokkeerd is: Sandbox vs Tool Policy vs Elevated
Bind mounts-details: Sandboxing

Weergavelabels

UI-labels gebruiken displayName indien beschikbaar, opgemaakt als <channel>:<token>.
#room is gereserveerd voor kamers/kanalen; groepschats gebruiken g-<slug> (kleine letters, spaties -> -, behoud #@+._-).

Groepsbeleid

Bepaal hoe groeps-/kamerberichten per kanaal worden afgehandeld:

{
  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": { allow: true },
        "#alias:example.org": { allow: true },
      },
    },
  },
}

Beleid	Gedrag
`"open"`	Groepen omzeilen allowlists; mention-gating is nog steeds van toepassing.
`"disabled"`	Alle groepsberichten volledig blokkeren.
`"allowlist"`	Alleen groepen/kamers toestaan die overeenkomen met de geconfigureerde allowlist.

Opmerkingen:

groupPolicy staat los van mention-gating (wat @-vermeldingen vereist).
WhatsApp/Telegram/Signal/iMessage/Microsoft Teams/Zalo: gebruik groupAllowFrom (terugval: expliciete allowFrom).
DM-koppelings-goedkeuringen (*-allowFrom opslagvermeldingen) gelden alleen voor DM-toegang; groepsafzenderautorisatie blijft expliciet aan groeps-allowlists.
Discord: allowlist gebruikt channels.discord.guilds.<id>.channels.
Slack: allowlist gebruikt channels.slack.channels.
Matrix: allowlist gebruikt channels.matrix.groups (kamer-ID’s, aliassen of namen). Gebruik channels.matrix.groupAllowFrom om afzenders te beperken; per-kamer users-allowlists worden ook ondersteund.
Groeps-DM’s worden apart beheerd (channels.discord.dm.*, channels.slack.dm.*).
Telegram-allowlist kan gebruikers-ID’s matchen ("123456789", "telegram:123456789", "tg:123456789") of gebruikersnamen ("@alice" of "alice"); prefixes zijn hoofdletterongevoelig.
Standaard is groupPolicy: "allowlist"; als je groeps-allowlist leeg is, worden groepsberichten geblokkeerd.
Runtime-veiligheid: wanneer een providerblok volledig ontbreekt (channels.<provider> afwezig), valt het groepsbeleid terug op een fail-closed modus (doorgaans allowlist) in plaats van channels.defaults.groupPolicy over te nemen.

Snel denkmodel (evaluatievolgorde voor groepsberichten):

groupPolicy (open/disabled/allowlist)
groeps-allowlists (*.groups, *.groupAllowFrom, kanaalspecifieke allowlist)
mention-gating (requireMention, /activation)

Mention-gating (standaard)

Groepsberichten vereisen een vermelding tenzij overschreven per groep. Standaarden leven per subsysteem onder *.groups."*".

Antwoorden op een botbericht telt als een impliciete vermelding (wanneer het kanaal antwoord-metadata ondersteunt). Dit geldt voor Telegram, WhatsApp, Slack, Discord en 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,
        },
      },
    ],
  },
}

Opmerkingen:

mentionPatterns zijn hoofdletterongevoelige regexes.
Platforms die expliciete vermeldingen bieden laten berichten nog steeds door; patronen zijn een terugval.
Per-agent-overschrijving: agents.list[].groupChat.mentionPatterns (handig wanneer meerdere agents een groep delen).
Mention-gating wordt alleen afgedwongen wanneer mention-detectie mogelijk is (native vermeldingen of mentionPatterns zijn geconfigureerd).
Discord-standaarden leven in channels.discord.guilds."*" (overschrijfbaar per guild/kanaal).
Groepsgeschiedeniscontext wordt uniform over kanalen gewrapped en is alleen wachtend (berichten overgeslagen door mention-gating); gebruik messages.groupChat.historyLimit voor de globale standaard en channels.<channel>.historyLimit (of channels.<channel>.accounts.*.historyLimit) voor overschrijvingen. Stel 0 in om uit te schakelen.

Groeps-/kanaal-toolbeperkingen (optioneel)

Sommige kanaalconfiguraties ondersteunen het beperken van welke tools beschikbaar zijn binnen een specifieke groep/kamer/kanaal.

tools: tools toestaan/weigeren voor de hele groep.
toolsBySender: per-afzender-overschrijvingen binnen de groep. Gebruik expliciete sleutelprefixen: id:<senderId>, e164:<phone>, username:<handle>, name:<displayName>, en "*" wildcard. Legacy-sleutels zonder prefix worden nog steeds geaccepteerd en alleen als id: gematcht.

Resolutievolgorde (meest specifiek wint):

groep/kanaal toolsBySender-match
groep/kanaal tools
standaard ("*") toolsBySender-match
standaard ("*") tools

Voorbeeld (Telegram):

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

Opmerkingen:

Groeps-/kanaal-toolbeperkingen worden toegepast bovenop het globale/agent-toolbeleid (deny wint nog steeds).
Sommige kanalen gebruiken een andere nesting voor kamers/kanalen (bijv. Discord guilds.*.channels.*, Slack channels.*, MS Teams teams.*.channels.*).

Groeps-allowlists

Wanneer channels.whatsapp.groups, channels.telegram.groups of channels.imessage.groups is geconfigureerd, fungeren de sleutels als groeps-allowlist. Gebruik "*" om alle groepen toe te staan terwijl je toch standaard mention-gedrag instelt.

Veelvoorkomende scenario’s (kopieer/plak):

Alle groepsantwoorden uitschakelen

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

Alleen specifieke groepen toestaan (WhatsApp)

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

Alle groepen toestaan maar vermelding vereisen (expliciet)

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

Alleen de eigenaar kan triggeren in groepen (WhatsApp)

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

Activering (alleen eigenaar)

Groepseigenaren kunnen per-groepsactivering wisselen:

/activation mention
/activation always

De eigenaar wordt bepaald door channels.whatsapp.allowFrom (of het eigen E.164-nummer van de bot wanneer niet ingesteld). Stuur het commando als losstaand bericht. Andere platforms negeren /activation momenteel.

Contextvelden

Inkomende groeps-payloads stellen in:

ChatType=group
GroupSubject (indien bekend)
GroupMembers (indien bekend)
WasMentioned (mention-gating-resultaat)
Telegram-forumonderwerpen bevatten ook MessageThreadId en IsForum.

De agent-systeemprompt bevat een groepsintroductie bij de eerste beurt van een nieuwe groepssessie. Het herinnert het model eraan te antwoorden als een mens, Markdown-tabellen te vermijden en geen letterlijke \n-sequenties te typen.

iMessage-specifiek

Gebruik bij voorkeur chat_id:<id> bij routering of allowlisting.
Chats weergeven: imsg chats --limit 20.
Groepsantwoorden gaan altijd terug naar dezelfde chat_id.

WhatsApp-specifiek

Zie Groepsberichten voor WhatsApp-specifiek gedrag (geschiedenisinjectie, mention-afhandelingsdetails).