Groepen

OpenClaw behandelt groepschats consistent op alle oppervlakken: Discord, iMessage, Matrix, Microsoft Teams, Signal, Slack, Telegram, WhatsApp, Zalo.

# Introductie voor beginners (2 minuten)

OpenClaw "leeft" op je eigen messaging-accounts. Er is geen aparte WhatsApp-botgebruiker. Als jij in een groep zit, kan OpenClaw die groep zien en daar reageren.

Standaardgedrag:

• Groepen zijn beperkt (groupPolicy: "allowlist").
• Antwoorden vereisen een vermelding, tenzij je vermeldingscontrole expliciet uitschakelt.
• Normale eindantwoorden in groepen/kanalen zijn standaard privé. Zichtbare kameruitvoer gebruikt de message-tool.

Vertaling: afzenders op de allowlist kunnen OpenClaw activeren door het te vermelden.

Snelle stroom (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

# Zichtbare antwoorden

Voor groeps-/kanaalkamers gebruikt OpenClaw standaard messages.groupChat.visibleReplies: "message_tool". openclaw doctor --fix schrijft deze standaardwaarde naar configuraties van geconfigureerde kanalen die deze weglaten. Dat betekent dat de agent de beurt nog steeds verwerkt en geheugen-/sessiestatus kan bijwerken, maar dat het normale eindantwoord niet automatisch terug in de kamer wordt geplaatst. Om zichtbaar te spreken gebruikt de agent message(action=send).

Deze standaard is afhankelijk van een model/runtimeomgeving die tools betrouwbaar aanroept. Als logs assistant-tekst tonen maar didSendViaMessagingTool: false, antwoordde het model privé in plaats van de berichtentool aan te roepen. Dat is geen Discord/Slack/Telegram-verzendfout. Gebruik een model dat betrouwbaar toolaanroepen doet voor groeps-/kanaalsessies, of stel messages.groupChat.visibleReplies: "automatic" in om legacy zichtbare eindantwoorden te herstellen.

Als de berichtentool niet beschikbaar is onder het actieve toolbeleid, valt OpenClaw terug op automatische zichtbare antwoorden in plaats van het antwoord stilzwijgend te onderdrukken. openclaw doctor waarschuwt voor deze mismatch.

Voor directe chats en elke andere bronbeurt gebruik je messages.visibleReplies: "message_tool" om hetzelfde tool-only zichtbare-antwoordgedrag globaal toe te passen. Harnesses kunnen dit ook als hun niet-ingestelde standaard kiezen; de Codex-harness doet dit voor directe chats in Codex-modus. messages.groupChat.visibleReplies blijft de specifiekere override voor groeps-/kanaalkamers.

Dit vervangt het oude patroon waarbij het model voor de meeste lurk-mode-beurten gedwongen werd NO_REPLY te antwoorden. In tool-only-modus betekent niets zichtbaar doen simpelweg dat de berichtentool niet wordt aangeroepen.

Typindicatoren worden nog steeds verzonden terwijl de agent in tool-only-modus werkt. De standaard typmodus voor groepen wordt voor deze beurten opgewaardeerd van "message" naar "instant", omdat er mogelijk nooit normale assistant-berichttekst is voordat de agent beslist of de berichtentool wordt aangeroepen. Expliciete typmodusconfiguratie blijft leidend.

Om legacy automatische eindantwoorden voor groeps-/kanaalkamers te herstellen:

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

De Gateway herlaadt de messages-configuratie hot nadat het bestand is opgeslagen. Herstart alleen wanneer bestandbewaking of configuratieherlaad in de deployment is uitgeschakeld.

Om zichtbare uitvoer voor elke bronchat via de berichtentool te verplichten:

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

Native slash-commando's (Discord, Telegram en andere oppervlakken met native commandondersteuning) omzeilen visibleReplies: "message_tool" en antwoorden altijd zichtbaar, zodat de kanaal-native command-UI het antwoord krijgt dat die verwacht. Dit geldt alleen voor gevalideerde native command-beurten; als tekst getypte /...-commando's en gewone chatbeurten volgen nog steeds de geconfigureerde groepsstandaard.

# Contextzichtbaarheid en allowlists

Bij groepsveiligheid zijn twee verschillende controles betrokken:

• Triggerautorisatie: wie de agent kan activeren (groupPolicy, groups, groupAllowFrom, kanaalspecifieke allowlists).
• Contextzichtbaarheid: welke aanvullende context in het model wordt geïnjecteerd (antwoordtekst, citaten, threadgeschiedenis, doorgestuurde metadata).

Standaard geeft OpenClaw prioriteit aan normaal chatgedrag en houdt het context grotendeels zoals ontvangen. Dit betekent dat allowlists vooral bepalen wie acties kan activeren, niet een universele redactiegrens voor elk geciteerd of historisch fragment.

Als je wilt...

Voor herbruikbare allowlists voor afzenders, zie Toegangsgroepen.

# Sessiesleutels

• Groepssessies gebruiken sessiesleutels agent:<agentId>:<channel>:group:<id> (kamers/kanalen gebruiken agent:<agentId>:<channel>:channel:<id>).
• Telegram-forumonderwerpen voegen :topic:<threadId> toe aan de 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 privéberichten + openbare groepen (één agent)

Ja — dit werkt goed als je "persoonlijke" verkeer privéberichten zijn en je "openbare" verkeer groepen zijn.

Waarom: in één-agentmodus komen privéberichten meestal terecht in de hoofdsessiesleutel (agent:main:main), terwijl groepen altijd niet-hoofdsessiesleutels gebruiken (agent:main:<channel>:group:<id>). Als je sandboxing inschakelt met mode: "non-main", draaien die groepssessies in de geconfigureerde sandbox-backend, terwijl je hoofd-DM-sessie op de host blijft. Docker is de standaardbackend als je er geen kiest.

Dit geeft je één agent-"brein" (gedeelde werkruimte + geheugen), maar twee uitvoeringshoudingen:

• Privéberichten: volledige tools (host)
• Groepen: sandbox + beperkte tools

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

Gerelateerd:

• Configuratiesleutels en standaardwaarden: Gateway-configuratie
• Debuggen waarom een tool is geblokkeerd: Sandbox versus toolbeleid versus verhoogd
• Details van bind mounts: Sandboxing

# Weergavelabels

• UI-labels gebruiken displayName wanneer beschikbaar, geformatteerd 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": { enabled: true },
        "#alias:example.org": { enabled: true },
      },
    },
  },
}

Snel mentaal model (evaluatievolgorde voor groepsberichten):

# Vermelding-gating (standaard)

Groepsberichten vereisen een vermelding, tenzij dit per groep wordt overschreven. Standaarden staan per subsysteem onder *.groups."*".

Antwoorden op een botbericht telt als een impliciete vermelding wanneer het kanaal antwoordmetadata ondersteunt. Een botbericht citeren kan ook tellen als een impliciete vermelding op kanalen die citatiemetadata beschikbaar maken. Huidige ingebouwde gevallen omvatten Telegram, WhatsApp, Slack, Discord, Microsoft Teams en 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,
        },
      },
    ],
  },
}

# Toolbeperkingen voor groep/kanaal (optioneel)

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

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

Oplossingsvolgorde (meest specifiek wint):

Voorbeeld (Telegram):

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

# Groeps-allowlists

Wanneer channels.whatsapp.groups, channels.telegram.groups of channels.imessage.groups is geconfigureerd, werken de keys als een groeps-allowlist. Gebruik "*" om alle groepen toe te staan terwijl je nog steeds standaard vermeldingsgedrag instelt.

Veelvoorkomende intenties (kopiëren/plakken):

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

# Activatie (alleen eigenaar)

Groepseigenaren kunnen activatie per groep schakelen:

• /activation mention
• /activation always

Eigenaar wordt bepaald door channels.whatsapp.allowFrom (of de eigen E.164 van de bot wanneer niet ingesteld). Verstuur de opdracht als een op zichzelf staand bericht. Andere oppervlakken negeren /activation momenteel.

# Contextvelden

Binnenkomende groepspayloads stellen in:

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

Kanaalspecifieke opmerkingen:

• BlueBubbles kan optioneel naamloze macOS-groepsdeelnemers verrijken vanuit de lokale Contacts-database voordat GroupMembers wordt ingevuld. Dit staat standaard uit en draait alleen nadat normale groeps-gating is geslaagd.

De systeemprompt van de agent bevat een groepsintro bij de eerste beurt van een nieuwe groepssessie. Die herinnert het model eraan te antwoorden als een mens, Markdown-tabellen te vermijden, lege regels te minimaliseren en normale chatafstand te volgen, en te vermijden letterlijke \n-reeksen te typen. Groepsnamen en deelnemerslabels afkomstig van kanalen worden weergegeven als afgeschermde niet-vertrouwde metadata, niet als inline systeeminstructies.

# iMessage-specifiek

• Geef de voorkeur aan chat_id:<id> bij routeren of allowlisten.
• Chats weergeven: imsg chats --limit 20.
• Groepsantwoorden gaan altijd terug naar dezelfde chat_id.

# WhatsApp-systeemprompts

Zie WhatsApp voor de canonieke WhatsApp-systeempromptregels, inclusief resolutie van groeps- en directe prompts, jokertekengedrag en semantiek voor accountoverschrijvingen.

# WhatsApp-specifiek

Zie Groepsberichten voor WhatsApp-only gedrag (geschiedenisinjectie, details over vermeldingsafhandeling).

# Gerelateerd

• Uitzendgroepen
• Kanaalroutering
• Groepsberichten
• Koppeling