Gruppen

OpenClaw behandelt Gruppenchats über alle Oberflächen hinweg konsistent: 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 abschließende Antworten in Gruppen/Kanälen sind standardmäßig privat. Sichtbare Raumausgabe verwendet das message-Tool.

Übersetzung: Absender in der Allowlist können OpenClaw durch Erwähnen auslösen.

Schneller Ablauf (was mit einer Gruppennachricht passiert):

groupPolicy? disabled -> drop
groupPolicy? allowlist -> group allowed? no -> drop
requireMention? yes -> mentioned? no -> store for context only
otherwise -> 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 abschließende Antwort aber nicht automatisch zurück in den Raum gepostet wird. Um sichtbar zu sprechen, verwendet der Agent message(action=send).

Dieser Standardwert hängt von einem Modell/einer Laufzeitumgebung ab, die zuverlässig Tools aufruft. Wenn Protokolle Assistententext zeigen, aber didSendViaMessagingTool: false, hat das Modell privat geantwortet, statt das message-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 bisherigen sichtbaren abschließenden Antworten wiederherzustellen.

Wenn das message-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 Inkonsistenz.

Für Direktchats und jeden anderen Quell-Turn verwenden Sie messages.visibleReplies: "message_tool", um dasselbe rein Tool-basierte Verhalten für sichtbare Antworten global anzuwenden. Harnesses können dies ebenfalls als ihren nicht gesetzten Standard wählen; der Codex-Harness tut dies für Direktchats 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 Lauschmodus zu einer Antwort mit NO_REPLY zu zwingen. Im reinen Tool-Modus bedeutet nichts Sichtbares zu tun schlicht, das message-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 Assistentennachrichtentext entsteht, bevor der Agent entscheidet, ob er das message-Tool aufruft. Eine explizite Tippmodus-Konfiguration hat weiterhin Vorrang.

Um bisherige automatische abschließende Antworten für Gruppen-/Kanalräume wiederherzustellen:

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

Der Gateway lädt die messages-Konfiguration per Hot Reload neu, nachdem die Datei gespeichert wurde. Starten Sie nur neu, wenn Dateiüberwachung oder Konfigurations-Neuladen in der Bereitstellung deaktiviert ist.

Um sichtbare Ausgabe für jeden Quellchat über das message-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 Befehlsoberfläche die erwartete Antwort erhält. Dies gilt nur für validierte native Befehls-Turns; als Text eingegebene /...-Befehle und normale Chat-Turns folgen weiterhin dem konfigurierten Gruppenstandard.

# Kontextsichtbarkeit und Allowlists

Bei der Gruppensicherheit sind zwei verschiedene Steuerungen beteiligt:

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

Standardmäßig priorisiert OpenClaw normales Chatverhalten und belässt Kontext weitgehend so, wie er empfangen wurde. Das bedeutet, dass Allowlists primär entscheiden, wer Aktionen auslösen kann, und keine universelle Schwärzungsgrenze für jedes zitierte oder historische Snippet darstellen.

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, damit jedes Thema eine eigene Sitzung hat.
• Direktchats verwenden die Hauptsitzung (oder pro Absender, wenn konfiguriert).
• Heartbeats werden für Gruppensitzungen übersprungen.

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

Ja – das funktioniert gut, wenn Ihr „persönlicher“ Datenverkehr aus DMs und Ihr „öffentlicher“ Datenverkehr aus Gruppen besteht.

Warum: Im Einzelagentenmodus landen DMs typischerweise im Haupt-Sitzungsschlüssel (agent:main:main), während Gruppen immer Nicht-Haupt-Sitzungsschlüssel verwenden (agent:main:<channel>:group:<id>). 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.

Das gibt Ihnen ein Agenten-„Gehirn“ (gemeinsamer Arbeitsbereich + Speicher), aber zwei Ausführungshaltungen:

• 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 Standardwerte: Gateway-Konfiguration
• Debugging, warum ein Tool blockiert wird: Sandbox vs Tool Policy vs Elevated
• Details zu Bind-Mounts: Sandboxing

# Anzeigebezeichnungen

• UI-Bezeichnungen 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 pro Kanal, wie Gruppen-/Raumnachrichten 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 Denkmodell (Auswertungsreihenfolge für Gruppennachrichten):

# Mention-Gating (Standard)

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

Das Antworten auf eine Bot-Nachricht zählt als implizite Erwähnung, wenn der Kanal Antwortmetadaten unterstützt. Das Zitieren einer Bot-Nachricht kann auf Kanälen, die Zitatmetadaten bereitstellen, ebenfalls als implizite Erwähnung zählen. Zu den aktuellen integrierten Fällen gehören 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 das Einschränken, welche Tools innerhalb einer bestimmten Gruppe/eines bestimmten Raums/Kanals verfügbar sind.

• tools: Tools für die gesamte Gruppe erlauben/verweigern.
• toolsBySender: Absenderbezogene Überschreibungen innerhalb der Gruppe. Verwenden Sie explizite Schlüsselpräfixe: id:<senderId>, e164:<phone>, username:<handle>, name:<displayName> und den Platzhalter "*". Alte 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, fungieren die Schlüssel als Gruppen-Allowlist. Verwenden Sie "*", um alle Gruppen zu erlauben und trotzdem ein 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.

Kanalspezifische Hinweise:

• BlueBubbles kann unbenannte macOS-Gruppenteilnehmer optional aus der lokalen Kontakte-Datenbank anreichern, bevor GroupMembers befüllt wird. Dies ist standardmäßig deaktiviert und wird erst ausgeführt, nachdem das normale Gruppen-Gating bestanden wurde.

Der Agent-Systemprompt 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 literalen \n-Sequenzen zu schreiben. Aus Kanälen stammende Gruppennamen und Teilnehmerbezeichnungen werden als eingezäunte, nicht vertrauenswürdige Metadaten gerendert, nicht als Inline-Systemanweisungen.

# iMessage-spezifische Details

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

# WhatsApp-Systemprompts

Siehe WhatsApp für die kanonischen WhatsApp-Systemprompt-Regeln, einschließlich Auflösung von Gruppen- und Direktprompts, Platzhalterverhalten und Semantik von Kontoüberschreibungen.

# WhatsApp-spezifische Details

Siehe Gruppennachrichten für reines WhatsApp-Verhalten (Verlaufsinjektion, Details zur Erwähnungsbehandlung).

# Verwandte Themen

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