Gruppen

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

Einführung für Einsteiger (2 Minuten)

OpenClaw „lebt“ in Ihren eigenen Messaging-Konten. Es gibt keinen separaten WhatsApp-Bot-Benutzer. Wenn Sie in einer Gruppe sind, kann OpenClaw diese Gruppe sehen und dort antworten.

Standardverhalten:

• Gruppen sind eingeschränkt (groupPolicy: "allowlist").
• Antworten erfordern eine Erwähnung, sofern Sie das Erwähnungs-Gating nicht ausdrücklich deaktivieren.
• Normale finale Antworten in Gruppen/Kanälen sind standardmäßig privat. Sichtbare Raumausgabe verwendet das message-Tool.

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

Schneller Ablauf (was mit einer Gruppennachricht passiert):

groupPolicy? disabled -> dropgroupPolicy? allowlist -> group allowed? no -> droprequireMention? yes -> mentioned? no -> store for context onlyotherwise -> reply

Sichtbare Antworten

Für Gruppen-/Kanalräume verwendet OpenClaw standardmäßig messages.groupChat.visibleReplies: "message_tool". openclaw doctor --fix schreibt diesen Standardwert in Konfigurationen konfigurierter Kanäle, in denen er fehlt. Das bedeutet, dass der Agent den Turn weiterhin verarbeitet und den Speicher-/Sitzungszustand aktualisieren kann, seine normale finale Antwort aber nicht automatisch zurück in den Raum gepostet wird. Um sichtbar zu sprechen, verwendet der Agent message(action=send).

Dieser Standard hängt von einem Modell/einer Runtime ab, das bzw. die zuverlässig Tools aufruft. Wenn die Logs Assistant-Text zeigen, aber didSendViaMessagingTool: false, hat das Modell privat geantwortet, statt das Nachrichten-Tool aufzurufen. Das ist kein Discord-/Slack-/Telegram-Sendefehler. Verwenden Sie für Gruppen-/Kanalsitzungen ein Modell mit zuverlässigen Tool-Aufrufen, oder setzen Sie messages.groupChat.visibleReplies: "automatic", um die früheren sichtbaren finalen Antworten wiederherzustellen.

Wenn das Nachrichten-Tool unter der aktiven Tool-Richtlinie nicht verfügbar ist, fällt OpenClaw auf automatische sichtbare Antworten zurück, statt die Antwort stillschweigend zu unterdrücken. openclaw doctor warnt vor dieser Nichtübereinstimmung.

Für direkte Chats und jeden anderen Quell-Turn verwenden Sie messages.visibleReplies: "message_tool", um dasselbe sichtbare Antwortverhalten nur per Tool global anzuwenden. Harnesses können dies auch als ihren nicht gesetzten Standard wählen; das Codex-Harness tut dies für direkte Chats im Codex-Modus. messages.groupChat.visibleReplies bleibt die spezifischere Überschreibung für Gruppen-/Kanalräume.

Dies ersetzt das alte Muster, das Modell für die meisten Turns im Lurk-Modus zu einer Antwort mit NO_REPLY zu zwingen. Im reinen Tool-Modus bedeutet nichts Sichtbares zu tun einfach, das Nachrichten-Tool nicht aufzurufen.

Tippindikatoren werden weiterhin gesendet, während der Agent im reinen Tool-Modus arbeitet. Der standardmäßige Gruppentippmodus wird für diese Turns von „message“ auf „instant“ hochgestuft, weil möglicherweise nie normaler Assistant-Nachrichtentext erscheint, bevor der Agent entscheidet, ob er das Nachrichten-Tool aufruft. Eine explizite Tippmodus-Konfiguration hat weiterhin Vorrang.

Um frühere automatische finale Antworten für Gruppen-/Kanalräume wiederherzustellen:

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

Das Gateway lädt die messages-Konfiguration nach dem Speichern der Datei per Hot-Reload neu. Starten Sie nur neu, wenn Dateibeobachtung oder Konfigurations-Neuladen in der Bereitstellung deaktiviert ist.

Um sichtbare Ausgaben für jeden Quell-Chat durch das Nachrichten-Tool zu erzwingen:

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

Native Slash-Befehle (Discord, Telegram und andere Oberflächen mit nativer Befehlsunterstützung) umgehen visibleReplies: "message_tool" und antworten immer sichtbar, damit die kanalnative Befehls-UI die erwartete Antwort erhält. Dies gilt nur für validierte native Befehls-Turns; als Text eingegebene /...-Befehle und gewöhnliche Chat-Turns folgen weiterhin dem konfigurierten Gruppenstandard.

Kontextsichtbarkeit und Allowlists

Bei der Gruppensicherheit sind zwei verschiedene Steuerelemente beteiligt:

• Auslöseautorisierung: wer den Agenten auslösen kann (groupPolicy, groups, groupAllowFrom, kanalspezifische Allowlists).
• Kontextsichtbarkeit: welcher zusätzliche Kontext in das Modell injiziert wird (Antworttext, Zitate, Thread-Verlauf, weitergeleitete Metadaten).

Standardmäßig priorisiert OpenClaw normales Chatverhalten und behält Kontext weitgehend so bei, wie er empfangen wurde. Das bedeutet, dass Allowlists hauptsächlich entscheiden, wer Aktionen auslösen kann, nicht eine universelle Schwärzungsgrenze für jedes zitierte oder historische Fragment.

Wenn Sie möchten ...

Für wiederverwendbare Absender-Allowlists siehe Zugriffsgruppen.

Sitzungsschlüssel

• Gruppensitzungen verwenden Sitzungsschlüssel im Format agent:<agentId>:<channel>:group:<id> (Räume/Kanäle verwenden agent:<agentId>:<channel>:channel:<id>).
• Telegram-Forumsthemen fügen :topic:<threadId> zur Gruppen-ID hinzu, sodass jedes Thema seine eigene Sitzung hat.
• Direkte Chats verwenden die Hauptsitzung (oder pro Absender, falls konfiguriert).
• Heartbeats werden für Gruppensitzungen übersprungen.

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

Ja, das funktioniert gut, wenn Ihr „persönlicher“ Traffic DMs und Ihr „öffentlicher“ Traffic Gruppen sind.

Warum: Im Einzel-Agent-Modus landen DMs typischerweise im Haupt-Sitzungsschlüssel (agent:main:main), während Gruppen immer Nicht-Haupt-Sitzungsschlüssel (agent:main:<channel>:group:<id>) verwenden. Wenn Sie Sandboxing mit mode: "non-main" aktivieren, laufen diese Gruppensitzungen im konfigurierten Sandbox-Backend, während Ihre Haupt-DM-Sitzung auf dem Host bleibt. Docker ist das Standard-Backend, wenn Sie keines auswählen.

Dadurch erhalten Sie ein Agenten-„Gehirn“ (gemeinsamer Workspace + Speicher), aber zwei Ausführungsprofile:

• DMs: vollständige Tools (Host)
• Gruppen: Sandbox + eingeschränkte 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",          ],        },      },    },  },}

Verwandt:

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

Anzeigelabels

• 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 -> -, #@+._- beibehalten).

Gruppenrichtlinie

Steuern Sie, wie Gruppen-/Raumnachrichten pro Kanal behandelt 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: ["[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 },      },    },  },}

Schnelles mentales Modell (Auswertungsreihenfolge für Gruppennachrichten):

Mention-Gating (Standard)

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

Das Antworten auf eine Bot-Nachricht zählt als implizite Erwähnung, wenn der Kanal Antwort-Metadaten unterstützt. Das Zitieren einer Bot-Nachricht kann auf Kanälen, die Zitat-Metadaten bereitstellen, ebenfalls als implizite Erwähnung zählen. Aktuelle integrierte Fälle umfassen Telegram, WhatsApp, Slack, Discord, Microsoft Teams und 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,        },      },    ],  },}

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

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

• tools: Tools für die gesamte Gruppe erlauben/verbieten.
• toolsBySender: Absenderspezifische Overrides innerhalb der Gruppe. Verwenden Sie explizite Schlüsselpräfixe: channel:<channelId>:<senderId>, id:<senderId>, e164:<phone>, username:<handle>, name:<displayName> und "*"-Wildcard. Kanal-IDs verwenden kanonische OpenClaw-Kanal-IDs; Aliasse wie teams werden zu msteams normalisiert. Veraltete Schlüssel ohne Präfix werden weiterhin akzeptiert und nur als id: abgeglichen.

Auflösungsreihenfolge (spezifischste gewinnt):

Beispiel (Telegram):

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

Gruppen-Allowlists

Wenn channels.whatsapp.groups, channels.telegram.groups oder channels.imessage.groups konfiguriert ist, wirken die Schlüssel als Gruppen-Allowlist. Verwenden Sie "*", um alle Gruppen zu erlauben und dennoch das Standardverhalten für Erwähnungen festzulegen.

Häufige Absichten (kopieren/einfügen):

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

Aktivierung (nur Owner)

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

• /activation mention
• /activation always

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

Kontextfelder

Eingehende Gruppen-Payloads setzen:

• ChatType=group
• GroupSubject (falls bekannt)
• GroupMembers (falls bekannt)
• WasMentioned (Mention-Gating-Ergebnis)
• Telegram-Forumsthemen enthalten außerdem MessageThreadId und IsForum.

Der System-Prompt des Agenten enthält beim ersten Turn einer neuen Gruppensitzung eine Gruppeneinführung. Sie erinnert das Modell daran, wie ein Mensch zu antworten, Markdown-Tabellen zu vermeiden, Leerzeilen zu minimieren, normale Chat-Abstände einzuhalten und keine literal \n-Sequenzen zu tippen. Aus dem Kanal stammende Gruppennamen und Teilnehmerlabels werden als eingezäunte, nicht vertrauenswürdige Metadaten gerendert, nicht als Inline-Systemanweisungen.

iMessage-Spezifika

• Bevorzugen Sie chat_id:<id> beim Routing oder bei Allowlists.
• Chats auflisten: imsg chats --limit 20.
• Gruppenantworten gehen immer zurück an dieselbe chat_id.

WhatsApp-System-Prompts

Siehe WhatsApp für die kanonischen WhatsApp-System-Prompt-Regeln, einschließlich Auflösung von Gruppen- und Direkt-Prompts, Wildcard-Verhalten und Semantik von Konto-Overrides.

WhatsApp-Spezifika

Siehe Gruppennachrichten für WhatsApp-spezifisches Verhalten (Verlaufseinfügung, Details zur Erwähnungsbehandlung).

Verwandt

• Broadcast-Gruppen
• Kanal-Routing
• Gruppennachrichten
• Kopplung