Gruppen

OpenClaw behandelt Gruppenchats plattformübergreifend konsistent: WhatsApp, Telegram, Discord, Slack, Signal, iMessage, Microsoft Teams, Zalo.

Einführung für Einsteiger (2 Minuten)

OpenClaw „lebt” auf deinen eigenen Messaging-Konten. Es gibt keinen separaten WhatsApp-Bot-Benutzer. 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.

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

Kurzfassung

DM-Zugang wird durch *.allowFrom gesteuert.

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

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

Schnellablauf (was mit einer Gruppennachricht passiert):

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

Group message flow

Wenn du…

Ziel	Was zu setzen ist
Alle Gruppen erlauben, aber nur bei @Mentions antworten	`groups: { "*": { requireMention: true } }`
Alle Gruppenantworten deaktivieren	`groupPolicy: "disabled"`
Nur bestimmte Gruppen	`groups: { "<group-id>": { ... } }` (kein `"*"`-Schlüssel)
Nur du kannst in Gruppen auslösen	`groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]`

Session-Schlüssel

Gruppen-Sessions verwenden agent:<agentId>:<channel>:group:<id> Session-Schlüssel (Räume/Kanäle 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 und dein „öffentlicher” Traffic Gruppen sind.

Warum: Im Einzelagenten-Modus landen DMs typischerweise im Haupt-Session-Schlüssel (agent:main:main), während Gruppen immer Nicht-Haupt-Session-Schlüssel 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 + Speicher), aber zwei Ausführungshaltungen:

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

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

Beispiel (DMs auf Host, Gruppen sandboxed + nur Messaging-Tools):

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // Gruppen/Kanäle sind nicht-main -> sandboxed
        scope: "session", // Stärkste Isolation (ein Container pro Gruppe/Kanal)
        workspaceAccess: "none",
      },
    },
  },
  tools: {
    sandbox: {
      tools: {
        // Wenn allow nicht leer ist, wird alles andere blockiert (deny gewinnt trotzdem).
        allow: ["group:messaging", "group:sessions"],
        deny: ["group:runtime", "group:fs", "group:ui", "nodes", "cron", "gateway"],
      },
    },
  },
}

Du möchtest „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
            "/home/user/FriendsShared:/data:ro",
          ],
        },
      },
    },
  },
}

Verwandt:

Konfigurationsschlüssel und Standards: Gateway configuration
Debugging, warum ein Tool blockiert ist: Sandbox vs Tool Policy vs Elevated
Bind-Mount-Details: Sandboxing

Anzeige-Labels

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

Gruppenrichtlinie

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

{
  channels: {
    whatsapp: {
      groupPolicy: "disabled", // "open" | "disabled" | "allowlist"
      groupAllowFrom: ["+15551234567"],
    },
    telegram: {
      groupPolicy: "disabled",
      groupAllowFrom: ["123456789"], // numerische Telegram-Benutzer-ID (Assistent kann @username auflösen)
    },
    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 },
      },
    },
  },
}

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

Hinweise:

groupPolicy ist getrennt vom Mention-Gating (das @Mentions erfordert).
WhatsApp/Telegram/Signal/iMessage/Microsoft Teams/Zalo: Verwende groupAllowFrom (Fallback: explizites allowFrom).
DM-Pairing-Genehmigungen (*-allowFrom-Store-Einträge) gelten nur für DM-Zugang; Gruppen-Absender-Autorisierung bleibt explizit an Gruppen-Allowlists gebunden.
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 ebenfalls unterstützt.
Gruppen-DMs werden separat gesteuert (channels.discord.dm.*, channels.slack.dm.*).
Telegram-Allowlist kann Benutzer-IDs ("123456789", "telegram:123456789", "tg:123456789") oder Benutzernamen ("@alice" oder "alice") matchen; Präfixe sind case-insensitive.
Standard ist groupPolicy: "allowlist"; wenn deine Gruppen-Allowlist leer ist, werden Gruppennachrichten blockiert.
Laufzeitsicherheit: Wenn ein Provider-Block vollständig fehlt (channels.<provider> fehlt), fällt die Gruppenrichtlinie auf einen Fail-Closed-Modus zurück (typischerweise allowlist), anstatt channels.defaults.groupPolicy zu erben.

Schnelles Denkmodell (Auswertungsreihenfolge für Gruppennachrichten):

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

Mention-Gating (Standard)

Gruppennachrichten erfordern eine Erwähnung, sofern nicht pro Gruppe überschrieben. Standards leben pro Subsystem unter *.groups."*".

Das Antworten auf eine Bot-Nachricht zählt als implizite Erwähnung (wenn der Kanal Antwort-Metadaten unterstützt). Dies 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 Regexe.
Oberflächen, die explizite Mentions liefern, werden weiterhin erkannt; Muster sind ein Fallback.
Pro-Agent-Überschreibung: agents.list[].groupChat.mentionPatterns (nützlich, wenn mehrere Agenten eine Gruppe teilen).
Mention-Gating wird nur durchgesetzt, wenn Mention-Erkennung möglich ist (native Mentions oder mentionPatterns sind konfiguriert).
Discord-Standards leben in channels.discord.guilds."*" (pro Guild/Kanal überschreibbar).
Gruppenverlaufskontext wird kanalübergreifend einheitlich bereitgestellt und ist nur ausstehend (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 Überschreibungen. Setze 0 zum Deaktivieren.

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

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

tools: Tools für die gesamte Gruppe erlauben/verbieten.
toolsBySender: Pro-Absender-Überschreibungen innerhalb der Gruppe. Verwende explizite Schlüsselpräfixe: id:<senderId>, e164:<phone>, username:<handle>, name:<displayName> und "*" als Wildcard. Legacy-Schlüssel ohne Präfix werden weiterhin akzeptiert und nur als id: gematcht.

Auflösungsreihenfolge (spezifischstes gewinnt):

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

Beispiel (Telegram):

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

Hinweise:

Gruppen-/Kanal-Tool-Einschränkungen werden zusätzlich zur globalen/Agent-Tool-Richtlinie angewendet (deny gewinnt weiterhin).
Einige Kanäle verwenden unterschiedliche Verschachtelung für Räume/Kanäle (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 Schlüssel als Gruppen-Allowlist. Verwende "*", um alle Gruppen zu erlauben und dennoch Standard-Mention-Verhalten festzulegen.

Gängige Absichten (kopieren/einfügen):

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 Mention erfordern (explizit)

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

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

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

Aktivierung (nur Besitzer)

Gruppenbesitzer können die Pro-Gruppen-Aktivierung umschalten:

/activation mention
/activation always

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

Kontextfelder

Eingehende Gruppen-Payloads setzen:

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

Der Agent-Systemprompt enthält beim ersten Turn einer neuen Gruppen-Session eine Gruppeneinführung. Sie erinnert das Modell daran, wie ein Mensch zu antworten, keine Markdown-Tabellen zu verwenden und keine literalen \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 Group messages für WhatsApp-spezifisches Verhalten (Verlaufsinjektion, Mention-Handling-Details).