OpenClaw Gruppen-Bots konfigurieren: In 2 Minuten starten

OpenClaw behandelt Gruppen-Chats über alle Oberflächen hinweg konsistent: Discord, iMessage, Matrix, Microsoft Teams, Signal, Slack, Telegram, WhatsApp, Zalo.

Einführung für Anfänger (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 (@mention), außer du deaktivierst das Mention-Gating explizit.

Das bedeutet: Absender auf der Allowlist können OpenClaw triggern, indem sie den Agenten erwähnen.

TL;DR

DM-Zugriff wird über *.allowFrom gesteuert.

Gruppen-Zugriff wird über *.groupPolicy + Allowlists (*.groups, *.groupAllowFrom) gesteuert.

Antwort-Trigger werden über Mention-Gating (requireMention, /activation) gesteuert.

Quick Flow (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 Folgendes erreichen willst…

Ziel	Einstellung
Alle Gruppen erlauben, aber nur auf @mentions antworten	`groups: { "*": { requireMention: true } }`
Alle Gruppen-Antworten deaktivieren	`groupPolicy: "disabled"`
Nur spezifische Gruppen erlauben	`groups: { "<group-id>": { ... } }` (kein `"*"` Key)
Nur du kannst in Gruppen triggern	`groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]`

Session-Keys

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

Pattern: Persönliche DMs + öffentliche Gruppen (Single-Agent)

Das funktioniert hervorragend, wenn dein „persönlicher“ Traffic aus DMs besteht und dein „öffentlicher“ Traffic in Gruppen stattfindet.

Der Grund: Im Single-Agent-Modus landen DMs normalerweise im Haupt-Session-Key (agent:main:main), während Gruppen immer Nicht-Haupt-Session-Keys (agent:main:<channel>:group:<id>) verwenden. 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 Agenten-„Gehirn“ (gemeinsamer Workspace + Memory), aber zwei verschiedene Ausführungsebenen:

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

Falls du wirklich getrennte Workspaces oder Personas brauchst (Privates und Öffentliches dürfen sich niemals vermischen), verwende einen zweiten Agenten + Bindings. Siehe Multi-Agent Routing.

Beispiel (DMs auf dem Host, Gruppen in der Sandbox + 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 möchtest, dass „Gruppen nur Ordner X sehen können“, anstatt „gar kein Host-Zugriff“? Behalte workspaceAccess: "none" bei und mounte nur freigegebene Pfade in die Sandbox:

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

Passend dazu:

Konfigurations-Keys und Defaults: Gateway configuration
Debugging, warum ein Tool blockiert wird: Sandbox vs Tool Policy vs Elevated
Details zu Bind-Mounts: Sandboxing

Display-Labels

UI-Labels verwenden displayName, falls verfügbar, formatiert als <channel>:<token>.
#room ist für Rooms/Channels reserviert; Gruppen-Chats verwenden g-<slug> (kleingeschrieben, Leerzeichen werden zu -, Sonderzeichen wie #@+._- bleiben erhalten).

AI Setup Assistant

Gruppenrichtlinien

Bestimme, wie Gruppen- oder Raumnachrichten pro Channel verarbeitet werden:

{
  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: ["user@org.com"],
    },
    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"`	Blockiert alle Gruppennachrichten vollständig.
`"allowlist"`	Erlaubt nur Gruppen/Räume, die der konfigurierten Allowlist entsprechen.

Hinweise:

groupPolicy ist getrennt vom Mention-Gating (das @mentions erfordert).
WhatsApp/Telegram/Signal/iMessage/Microsoft Teams/Zalo: Nutze groupAllowFrom (Fallback: explizites allowFrom).
DM-Pairing-Freigaben (*-allowFrom Einträge) gelten nur für den DM-Zugriff; die Autorisierung von Gruppensendern bleibt explizit an Gruppen-Allowlists gebunden.
Discord: Die Allowlist nutzt channels.discord.guilds.<id>.channels.
Slack: Die Allowlist nutzt channels.slack.channels.
Matrix: Die Allowlist nutzt channels.matrix.groups. Bevorzuge Room-IDs oder Aliase; die Suche nach Namen beigetretener Räume erfolgt nach dem Best-Effort-Prinzip, und nicht aufgelöste Namen werden zur Laufzeit ignoriert. Nutze channels.matrix.groupAllowFrom, um Sender einzuschränken; pro Raum unterstützte users Allowlists sind ebenfalls verfügbar.
Gruppen-DMs werden separat gesteuert (channels.discord.dm.*, channels.slack.dm.*).
Die Telegram-Allowlist kann User-IDs ("123456789", "telegram:123456789", "tg:123456789") oder Usernames ("@alice" oder "alice") abgleichen; Präfixe ignorieren Groß-/Kleinschreibung.
Standard ist groupPolicy: "allowlist"; wenn deine Gruppen-Allowlist leer ist, werden Gruppennachrichten blockiert.
Sicherheit zur Laufzeit: Wenn ein Provider-Block komplett fehlt (channels.<provider> nicht vorhanden), fällt die Gruppenrichtlinie in einen Fail-Closed-Modus zurück (normalerweise allowlist), anstatt channels.defaults.groupPolicy zu erben.

Kurzes mentales Modell (Reihenfolge der Auswertung 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 (Mention), sofern dies nicht pro Gruppe überschrieben wird. Standardwerte liegen pro Subsystem unter *.groups."*".

Das Antworten auf eine Bot-Nachricht zählt als implizite Mention (wenn der Channel Reply-Metadaten unterstützt). Dies gilt für Telegram, WhatsApp, Slack, Discord und Microsoft Teams.

{
  channels: {
    whatsapp: {
      groups: {
        "*": { requireMention: true },
        "123@g.us": { 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 Regex-Muster; ungültige Muster und unsichere “Nested-Repetition”-Formen werden ignoriert.
Oberflächen, die explizite Mentions liefern, werden weiterhin durchgelassen; Muster dienen als Fallback.
Override pro Agent: agents.list[].groupChat.mentionPatterns (nützlich, wenn sich mehrere Agents eine Gruppe teilen).
Mention-Gating wird nur erzwungen, wenn eine Mention-Erkennung möglich ist (native Mentions oder konfigurierte mentionPatterns).
Discord-Standardwerte liegen in channels.discord.guilds."*" (überschreibbar pro Guild/Channel).
Der Kontext der Gruppen-Historie wird über alle Channels hinweg einheitlich verpackt und ist pending-only (Nachrichten, die aufgrund von Mention-Gating übersprungen wurden); nutze messages.groupChat.historyLimit für den globalen Standard und channels.<channel>.historyLimit (oder channels.<channel>.accounts.*.historyLimit) für Overrides. Setze 0 zum Deaktivieren.

Tool-Einschränkungen für Gruppen/Channels (optional)

Einige Channel-Konfigurationen erlauben es dir einzuschränken, welche Tools innerhalb einer bestimmten Gruppe, eines Raums oder eines Channels verfügbar sind.

tools: Erlaubt oder verbietet Tools für die gesamte Gruppe.
toolsBySender: Überschreibt Einstellungen pro Absender innerhalb der Gruppe. Verwende explizite Key-Präfixe: id:<senderId>, e164:<phone>, username:<handle>, name:<displayName> und den Wildcard "*" . Veraltete Keys ohne Präfix werden weiterhin akzeptiert und nur als id: gematcht.

Reihenfolge der Auflösung (der spezifischste Treffer gewinnt):

Treffer in toolsBySender der Gruppe/des Channels
tools der Gruppe/des Channels
Standard-Treffer ("*") in toolsBySender
Standard-Einstellung ("*") für tools

Beispiel (Telegram):

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

Hinweise:

Tool-Einschränkungen für Gruppen/Channels werden zusätzlich zur globalen oder Agent-spezifischen Tool-Policy angewendet (ein “deny” gewinnt immer).
Manche Channels nutzen eine andere Verschachtelung für Räume/Channels (z. B. Discord guilds.*.channels.*, Slack channels.*, Microsoft Teams teams.*.channels.*).

Allowlists für Gruppen

Wenn channels.whatsapp.groups, channels.telegram.groups oder channels.imessage.groups konfiguriert ist, fungieren die Keys als Allowlist für Gruppen. Nutze "*", um alle Gruppen zuzulassen und gleichzeitig das Standard-Verhalten für Erwähnungen festzulegen.

Häufige Anwendungsfälle (zum Kopieren):

Alle Antworten in Gruppen deaktivieren

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

Nur bestimmte Gruppen zulassen (WhatsApp)

{
  channels: {
    whatsapp: {
      groups: {
        "123@g.us": { requireMention: true },
        "456@g.us": { requireMention: false },
      },
    },
  },
}

Alle Gruppen zulassen, aber Erwähnung erzwingen (explizit)

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

Nur der Besitzer kann in Gruppen triggern (WhatsApp)

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

AI Setup Assistant

Aktivierung (nur für Owner)

Als Group Owner kannst du die Aktivierung pro Gruppe umschalten. Ich empfehle dir, diese Befehle zu nutzen, um die Kontrolle zu behalten:

/activation mention
/activation always

Wer als Owner gilt, wird über channels.whatsapp.allowFrom definiert. Falls du dort nichts eingetragen hast, wird die eigene E.164-Nummer des Bots verwendet. Sende den Befehl als eigenständige Nachricht ab. Andere Oberflächen ignorieren /activation aktuell noch.

Kontext-Felder

Bei eingehenden Payloads aus Gruppen werden diese Felder gesetzt:

ChatType=group
GroupSubject (falls bekannt)
GroupMembers (falls bekannt)
WasMentioned (Ergebnis der Erwähnungs-Prüfung)
Telegram Forum-Topics enthalten zusätzlich MessageThreadId und IsForum.

Besonderheiten der Channels:

BlueBubbles kann optional Namen für unbekannte macOS-Gruppenteilnehmer aus der lokalen Kontakte-Datenbank ergänzen, bevor GroupMembers befüllt wird. Diese Funktion ist standardmäßig deaktiviert und wird erst ausgeführt, nachdem die normalen Prüfungen für Gruppen abgeschlossen sind.

Der System Prompt des Agents enthält beim ersten Turn einer neuen Gruppen-Session eine Einführung für Gruppen. Das erinnert das Model daran, wie ein Mensch zu antworten, Markdown-Tabellen zu vermeiden und keine wörtlichen \n Sequenzen zu schreiben.

iMessage-Besonderheiten

Nutze am besten chat_id:<id>, wenn du Nachrichten routest oder auf eine Allowlist setzt. Das ist die zuverlässigste Methode für dein Setup.

Um deine Chats aufzulisten, nutzt du diesen Befehl:

imsg chats --limit 20

Antworten in Gruppen gehen immer an dieselbe chat_id zurück, was die Zuordnung extrem einfach macht.

WhatsApp-Besonderheiten

Schau dir Group messages an, wenn du Details zu WhatsApp-spezifischem Verhalten suchst. Dort erfährst du alles Wichtige zur History Injection und wie Mentions genau gehandhabt werden.

OpenClaw Expert

Noch festgefahren?

Wenn diese Seite nicht hilft, frage OpenClaw Expert nach Schritt-fuer-Schritt-Loesungen.