Gruppen

OpenClaw behandelt Gruppenchats einheitlich auf allen Plattformen: WhatsApp, Telegram, Discord, Slack, Signal, iMessage, Microsoft Teams.

Einsteiger-Intro (2 Minuten)

OpenClaw “lebt” auf deinen eigenen Messaging-Accounts. Es gibt keinen separaten WhatsApp-Bot-User. Wenn du in einer Gruppe bist, kann OpenClaw diese Gruppe sehen und dort antworten.

Standardverhalten:

Gruppen sind eingeschränkt (groupPolicy: "allowlist").
Antworten erfordern eine Erwähnung, es sei denn, du deaktivierst das Mention-Gating explizit.

Das bedeutet: Absender auf der Allowlist können OpenClaw durch Erwähnung auslösen.

Kurz gesagt

DM-Zugriff wird durch *.allowFrom gesteuert.

Gruppenzugriff wird durch *.groupPolicy + Allowlists (*.groups, *.groupAllowFrom) gesteuert.

Antwort-Auslösung wird durch Mention-Gating (requireMention, /activation) gesteuert.

Schneller Ablauf (was mit einer Gruppennachricht passiert):

groupPolicy? disabled -> verwerfen
groupPolicy? allowlist -> Gruppe erlaubt? nein -> verwerfen
requireMention? ja -> erwähnt? nein -> nur für Kontext speichern
sonst -> antworten

Gruppennachrichten-Ablauf

Wenn du…

Ziel	Was du einstellen musst
Alle Gruppen erlauben, aber nur auf @Erwähnungen antworten	`groups: { "*": { requireMention: true } }`
Alle Gruppenantworten deaktivieren	`groupPolicy: "disabled"`
Nur bestimmte Gruppen	`groups: { "<group-id>": { ... } }` (kein `"*"` Key)
Nur du kannst in Gruppen auslösen	`groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]`

Session-Keys

Gruppen-Sessions verwenden agent:<agentId>:<channel>:group:<id> als Session-Keys (Räume/Channels verwenden agent:<agentId>:<channel>:channel:<id>).
Telegram-Forum-Topics fügen :topic:<threadId> zur Gruppen-ID hinzu, sodass jedes Topic seine eigene Session hat.
Direkte Chats verwenden die Haupt-Session (oder pro Absender, falls konfiguriert).
Heartbeats werden für Gruppen-Sessions übersprungen.

Muster: persönliche DMs + öffentliche Gruppen (einzelner Agent)

Ja — das funktioniert gut, wenn dein “persönlicher” Traffic DMs sind und dein “öffentlicher” Traffic Gruppen.

Warum: Im Single-Agent-Modus landen DMs typischerweise im main Session-Key (agent:main:main), während Gruppen immer non-main Session-Keys verwenden (agent:main:<channel>:group:<id>). Wenn du Sandboxing mit mode: "non-main" aktivierst, laufen diese Gruppen-Sessions in Docker, während deine Haupt-DM-Session auf dem Host bleibt.

Das gibt dir ein Agent-”Gehirn” (gemeinsamer Workspace + Memory), aber zwei Ausführungsmodi:

DMs: volle Tools (Host)
Gruppen: Sandbox + eingeschränkte Tools (Docker)

Wenn du wirklich separate Workspaces/Personas brauchst (“persönlich” und “öffentlich” dürfen sich nie vermischen), verwende einen zweiten Agent + Bindings. Siehe Multi-Agent Routing.

Beispiel (DMs auf Host, Gruppen sandboxed + nur Messaging-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"],
      },
    },
  },
}

Du willst “Gruppen können nur Ordner X sehen” statt “kein Host-Zugriff”? Behalte workspaceAccess: "none" und mounte nur erlaubte Pfade in die Sandbox:

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

Verwandte Themen:

Konfigurationsschlüssel und Standardwerte: Gateway-Konfiguration
Debugging warum ein Tool blockiert ist: Sandbox vs Tool Policy vs Elevated
Bind-Mounts Details: Sandboxing

Anzeige-Labels

UI-Labels verwenden displayName wenn verfügbar, formatiert als <channel>:<token>.
#room ist für Räume/Channels reserviert; Gruppenchats verwenden g-<slug> (Kleinbuchstaben, Leerzeichen -> -, behalte #@+._-).

Group Policy

Steuere, wie Gruppen-/Raumnachrichten pro Channel behandelt werden:

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

Policy	Verhalten
`"open"`	Gruppen umgehen Allowlists; Mention-Gating gilt weiterhin.
`"disabled"`	Alle Gruppennachrichten komplett blockieren.
`"allowlist"`	Nur Gruppen/Räume erlauben, die der konfigurierten Allowlist entsprechen.

Hinweise:

groupPolicy ist getrennt vom Mention-Gating (das @Erwähnungen erfordert).
WhatsApp/Telegram/Signal/iMessage/Microsoft Teams: verwende groupAllowFrom (Fallback: explizites allowFrom).
Discord: Allowlist verwendet channels.discord.guilds.<id>.channels.
Slack: Allowlist verwendet channels.slack.channels.
Matrix: Allowlist verwendet channels.matrix.groups (Raum-IDs, Aliase oder Namen). Verwende channels.matrix.groupAllowFrom um Absender einzuschränken; pro-Raum users Allowlists werden auch unterstützt.
Gruppen-DMs werden separat gesteuert (channels.discord.dm.*, channels.slack.dm.*).
Telegram-Allowlist kann User-IDs ("123456789", "telegram:123456789", "tg:123456789") oder Usernames ("@alice" oder "alice") matchen; Präfixe sind case-insensitive.
Standard ist groupPolicy: "allowlist"; wenn deine Gruppen-Allowlist leer ist, werden Gruppennachrichten blockiert.

Schnelles Denkmodell (Auswertungsreihenfolge für Gruppennachrichten):

groupPolicy (open/disabled/allowlist)
Gruppen-Allowlists (*.groups, *.groupAllowFrom, channel-spezifische Allowlist)
Mention-Gating (requireMention, /activation)

Mention-Gating (Standard)

Gruppennachrichten erfordern eine Erwähnung, es sei denn, es wird pro Gruppe überschrieben. Standardwerte leben pro Subsystem unter *.groups."*".

Eine Antwort auf eine Bot-Nachricht zählt als implizite Erwähnung (wenn der Channel Reply-Metadaten unterstützt). Das gilt für Telegram, WhatsApp, Slack, Discord und 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,
        },
      },
    ],
  },
}

Hinweise:

mentionPatterns sind case-insensitive Regexes.
Plattformen mit expliziten Erwähnungen funktionieren weiterhin; Patterns sind ein Fallback.
Pro-Agent Override: agents.list[].groupChat.mentionPatterns (nützlich wenn mehrere Agents eine Gruppe teilen).
Mention-Gating wird nur erzwungen, wenn Erwähnungserkennung möglich ist (native Erwähnungen oder mentionPatterns sind konfiguriert).
Discord-Standardwerte leben in channels.discord.guilds."*" (überschreibbar pro Guild/Channel).
Gruppen-History-Kontext wird einheitlich über Channels gewickelt und ist pending-only (Nachrichten, die wegen Mention-Gating übersprungen wurden); verwende messages.groupChat.historyLimit für den globalen Standard und channels.<channel>.historyLimit (oder channels.<channel>.accounts.*.historyLimit) für Overrides. Setze 0 zum Deaktivieren.

Gruppen-/Channel-Tool-Einschränkungen (optional)

Einige Channel-Configs unterstützen die Einschränkung, welche Tools innerhalb einer bestimmten Gruppe/Raum/Channel verfügbar sind.

tools: allow/deny Tools für die gesamte Gruppe.
toolsBySender: pro-Absender Overrides innerhalb der Gruppe (Keys sind Absender-IDs/Usernames/E-Mails/Telefonnummern je nach Channel). Verwende "*" als Wildcard.

Auflösungsreihenfolge (spezifischste gewinnt):

Gruppen-/Channel toolsBySender Match
Gruppen-/Channel tools
Standard ("*") toolsBySender Match
Standard ("*") tools

Beispiel (Telegram):

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

Hinweise:

Gruppen-/Channel-Tool-Einschränkungen werden zusätzlich zur globalen/Agent-Tool-Policy angewendet (deny gewinnt weiterhin).
Einige Channels verwenden unterschiedliche Verschachtelung für Räume/Channels (z.B. Discord guilds.*.channels.*, Slack channels.*, MS Teams teams.*.channels.*).

Gruppen-Allowlists

Wenn channels.whatsapp.groups, channels.telegram.groups oder channels.imessage.groups konfiguriert ist, fungieren die Keys als Gruppen-Allowlist. Verwende "*" um alle Gruppen zu erlauben und trotzdem Standard-Mention-Verhalten zu setzen.

Häufige Anwendungsfälle (zum Kopieren):

Alle Gruppenantworten deaktivieren

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

Nur bestimmte Gruppen erlauben (WhatsApp)

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

Alle Gruppen erlauben, aber Erwähnung erfordern (explizit)

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

Nur der Owner kann in Gruppen auslösen (WhatsApp)

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

Aktivierung (nur Owner)

Gruppen-Owner können die pro-Gruppen-Aktivierung umschalten:

/activation mention
/activation always

Der Owner wird durch channels.whatsapp.allowFrom bestimmt (oder die E.164 des Bots selbst, wenn nicht gesetzt). Sende den Befehl als eigenständige Nachricht. Andere Plattformen ignorieren /activation derzeit.

Kontext-Felder

Eingehende Gruppen-Payloads setzen:

ChatType=group
GroupSubject (falls bekannt)
GroupMembers (falls bekannt)
WasMentioned (Mention-Gating-Ergebnis)
Telegram-Forum-Topics enthalten auch MessageThreadId und IsForum.

Der Agent-System-Prompt enthält ein Gruppen-Intro beim ersten Turn einer neuen Gruppen-Session. Es erinnert das Modell daran, wie ein Mensch zu antworten, Markdown-Tabellen zu vermeiden und keine wörtlichen \n-Sequenzen zu tippen.

iMessage-Besonderheiten

Bevorzuge chat_id:<id> beim Routing oder Allowlisting.
Chats auflisten: imsg chats --limit 20.
Gruppenantworten gehen immer an dieselbe chat_id zurück.

WhatsApp-Besonderheiten

Siehe Gruppennachrichten für WhatsApp-spezifisches Verhalten (History-Injection, Mention-Handling-Details).