Grupy

OpenClaw traktuje czaty grupowe spójnie na różnych powierzchniach: Discord, iMessage, Matrix, Microsoft Teams, Signal, Slack, Telegram, WhatsApp, Zalo.

# Wprowadzenie dla początkujących (2 minuty)

OpenClaw „działa” na Twoich własnych kontach komunikacyjnych. Nie ma osobnego użytkownika bota WhatsApp. Jeśli Ty jesteś w grupie, OpenClaw może ją zobaczyć i tam odpowiadać.

Domyślne zachowanie:

• Grupy są ograniczone (groupPolicy: "allowlist").
• Odpowiedzi wymagają wzmianki, chyba że jawnie wyłączysz bramkowanie wzmiankami.
• Normalne odpowiedzi końcowe w grupach/kanałach są domyślnie prywatne. Widoczny wynik w pokoju używa narzędzia message.

Innymi słowy: nadawcy z listy dozwolonych mogą wyzwolić OpenClaw, wspominając go.

Szybki przepływ (co dzieje się z wiadomością grupową):

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

# Widoczne odpowiedzi

Dla pokojów grupowych/kanałowych OpenClaw domyślnie używa messages.groupChat.visibleReplies: "message_tool". openclaw doctor --fix zapisuje tę wartość domyślną w konfiguracjach skonfigurowanych kanałów, które jej nie zawierają. Oznacza to, że agent nadal przetwarza turę i może aktualizować stan pamięci/sesji, ale jego normalna odpowiedź końcowa nie jest automatycznie publikowana z powrotem w pokoju. Aby wypowiedzieć się widocznie, agent używa message(action=send).

Ta wartość domyślna zależy od modelu/środowiska uruchomieniowego, które niezawodnie wywołuje narzędzia. Jeśli logi pokazują tekst asystenta, ale didSendViaMessagingTool: false, model odpowiedział prywatnie zamiast wywołać narzędzie wiadomości. To nie jest awaria wysyłania Discord/Slack/Telegram. Użyj modelu niezawodnie wywołującego narzędzia dla sesji grupowych/kanałowych albo ustaw messages.groupChat.visibleReplies: "automatic", aby przywrócić starsze widoczne odpowiedzi końcowe.

Jeśli narzędzie wiadomości jest niedostępne przy aktywnej polityce narzędzi, OpenClaw wraca do automatycznych widocznych odpowiedzi zamiast po cichu tłumić odpowiedź. openclaw doctor ostrzega o tej niezgodności.

Dla czatów bezpośrednich i każdej innej tury źródłowej użyj messages.visibleReplies: "message_tool", aby zastosować globalnie to samo zachowanie widocznych odpowiedzi wyłącznie przez narzędzie. Harnessy mogą też wybrać to jako swoją nieustawioną wartość domyślną; harness Codex robi to dla czatów bezpośrednich w trybie Codex. messages.groupChat.visibleReplies pozostaje bardziej szczegółowym nadpisaniem dla pokojów grupowych/kanałowych.

Zastępuje to stary wzorzec wymuszania na modelu odpowiedzi NO_REPLY dla większości tur w trybie nasłuchiwania. W trybie wyłącznie narzędziowym brak widocznego działania oznacza po prostu niewywołanie narzędzia wiadomości.

Wskaźniki pisania są nadal wysyłane, gdy agent pracuje w trybie wyłącznie narzędziowym. Domyślny tryb pisania dla grup zostaje podniesiony z „message” do „instant” dla tych tur, ponieważ może nigdy nie pojawić się normalny tekst wiadomości asystenta, zanim agent zdecyduje, czy wywołać narzędzie wiadomości. Jawna konfiguracja trybu pisania nadal ma pierwszeństwo.

Aby przywrócić starsze automatyczne odpowiedzi końcowe dla pokojów grupowych/kanałowych:

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

Gateway przeładowuje konfigurację messages na gorąco po zapisaniu pliku. Uruchom ponownie tylko wtedy, gdy obserwowanie plików lub przeładowywanie konfiguracji jest wyłączone we wdrożeniu.

Aby wymagać, by widoczne wyjście przechodziło przez narzędzie wiadomości dla każdego czatu źródłowego:

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

Natywne polecenia ukośnikowe (Discord, Telegram i inne powierzchnie z obsługą natywnych poleceń) omijają visibleReplies: "message_tool" i zawsze odpowiadają widocznie, aby natywny interfejs poleceń kanału otrzymał oczekiwaną odpowiedź. Dotyczy to tylko zweryfikowanych tur poleceń natywnych; polecenia /... wpisane jako tekst i zwykłe tury czatu nadal stosują skonfigurowaną domyślną wartość grupową.

# Widoczność kontekstu i listy dozwolonych

W bezpieczeństwo grup są zaangażowane dwa różne mechanizmy kontroli:

• Autoryzacja wyzwalania: kto może wyzwolić agenta (groupPolicy, groups, groupAllowFrom, listy dozwolonych specyficzne dla kanału).
• Widoczność kontekstu: jaki dodatkowy kontekst jest wstrzykiwany do modelu (tekst odpowiedzi, cytaty, historia wątku, metadane przekazania).

Domyślnie OpenClaw priorytetowo traktuje normalne zachowanie czatu i zachowuje kontekst głównie tak, jak został odebrany. Oznacza to, że listy dozwolonych przede wszystkim decydują, kto może wyzwalać działania, a nie stanowią uniwersalnej granicy redakcji dla każdego cytowanego lub historycznego fragmentu.

Jeśli chcesz...

Aby uzyskać listy dozwolonych nadawców wielokrotnego użytku, zobacz Grupy dostępu.

# Klucze sesji

• Sesje grupowe używają kluczy sesji agent:<agentId>:<channel>:group:<id> (pokoje/kanały używają agent:<agentId>:<channel>:channel:<id>).
• Tematy forum Telegram dodają :topic:<threadId> do identyfikatora grupy, aby każdy temat miał własną sesję.
• Czaty bezpośrednie używają głównej sesji (lub osobnej dla nadawcy, jeśli skonfigurowano).
• Heartbeat są pomijane dla sesji grupowych.

# Wzorzec: prywatne wiadomości DM + publiczne grupy (jeden agent)

Tak — działa to dobrze, jeśli Twój ruch „prywatny” to wiadomości DM, a ruch „publiczny” to grupy.

Dlaczego: w trybie jednego agenta wiadomości DM zwykle trafiają do głównego klucza sesji (agent:main:main), natomiast grupy zawsze używają niegłównych kluczy sesji (agent:main:<channel>:group:<id>). Jeśli włączysz piaskownicę z mode: "non-main", te sesje grupowe będą działać w skonfigurowanym backendzie piaskownicy, a Twoja główna sesja DM pozostanie na hoście. Docker jest domyślnym backendem, jeśli nie wybierzesz innego.

Daje to jeden „mózg” agenta (wspólna przestrzeń robocza + pamięć), ale dwie postawy wykonawcze:

• Wiadomości DM: pełne narzędzia (host)
• Grupy: piaskownica + ograniczone narzędzia

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

Powiązane:

• Klucze konfiguracji i wartości domyślne: Konfiguracja Gateway
• Debugowanie, dlaczego narzędzie jest zablokowane: Piaskownica kontra polityka narzędzi kontra podwyższone uprawnienia
• Szczegóły montowań bind: Piaskownica

# Etykiety wyświetlania

• Etykiety UI używają displayName, gdy jest dostępne, sformatowanego jako <channel>:<token>.
• #room jest zarezerwowane dla pokojów/kanałów; czaty grupowe używają g-<slug> (małe litery, spacje -> -, zachowaj #@+._-).

# Polityka grup

Kontroluj, jak wiadomości grupowe/pokojowe są obsługiwane dla każdego kanału:

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

Szybki model mentalny (kolejność oceny wiadomości grupowych):

# Bramkowanie wzmiankami (domyślne)

Wiadomości grupowe wymagają wzmianki, chyba że nadpisano to dla danej grupy. Wartości domyślne znajdują się dla każdego podsystemu pod *.groups."*".

Odpowiedź na wiadomość bota liczy się jako niejawna wzmianka, gdy kanał obsługuje metadane odpowiedzi. Cytowanie wiadomości bota może także liczyć się jako niejawna wzmianka w kanałach udostępniających metadane cytatu. Obecne wbudowane przypadki obejmują Telegram, WhatsApp, Slack, Discord, Microsoft Teams i 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,
        },
      },
    ],
  },
}

# Ograniczenia narzędzi grupy/kanału (opcjonalne)

Niektóre konfiguracje kanałów obsługują ograniczanie narzędzi dostępnych wewnątrz konkretnej grupy/pokoju/kanału.

• tools: zezwalaj na narzędzia lub odmawiaj ich dla całej grupy.
• toolsBySender: nadpisania według nadawcy w grupie. Używaj jawnych prefiksów kluczy: id:<senderId>, e164:<phone>, username:<handle>, name:<displayName> oraz symbolu wieloznacznego "*". Starsze klucze bez prefiksu są nadal akceptowane i dopasowywane wyłącznie jako id:.

Kolejność rozstrzygania (wygrywa najbardziej szczegółowe dopasowanie):

Przykład (Telegram):

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

# Listy dozwolonych grup

Gdy skonfigurowano channels.whatsapp.groups, channels.telegram.groups lub channels.imessage.groups, klucze działają jako lista dozwolonych grup. Użyj "*", aby zezwolić na wszystkie grupy, jednocześnie nadal ustawiając domyślne zachowanie dotyczące wzmianek.

Typowe zamiary (kopiuj/wklej):

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

# Aktywacja (tylko właściciel)

Właściciele grup mogą przełączać aktywację dla poszczególnych grup:

• /activation mention
• /activation always

Właściciel jest określany przez channels.whatsapp.allowFrom (lub własny E.164 bota, gdy nie ustawiono). Wyślij polecenie jako samodzielną wiadomość. Inne powierzchnie obecnie ignorują /activation.

# Pola kontekstu

Przychodzące ładunki grupowe ustawiają:

• ChatType=group
• GroupSubject (jeśli znane)
• GroupMembers (jeśli znane)
• WasMentioned (wynik bramkowania wzmiankami)
• Tematy forum Telegram zawierają także MessageThreadId i IsForum.

Uwagi specyficzne dla kanału:

• BlueBubbles może opcjonalnie wzbogacić nienazwanych uczestników grup macOS z lokalnej bazy Kontaktów przed wypełnieniem GroupMembers. Jest to domyślnie wyłączone i uruchamia się dopiero po przejściu normalnego bramkowania grupy.

Prompt systemowy agenta zawiera wprowadzenie grupowe w pierwszej turze nowej sesji grupowej. Przypomina modelowi, aby odpowiadał jak człowiek, unikał tabel Markdown, minimalizował puste wiersze i stosował normalne odstępy czatu oraz unikał wpisywania dosłownych sekwencji \n. Nazwy grup pochodzące z kanałów i etykiety uczestników są renderowane jako ogrodzone niezaufane metadane, a nie jako wbudowane instrukcje systemowe.

# Szczegóły iMessage

• Preferuj chat_id:<id> podczas routingu lub dodawania do listy dozwolonych.
• Lista czatów: imsg chats --limit 20.
• Odpowiedzi grupowe zawsze wracają do tego samego chat_id.

# Prompty systemowe WhatsApp

Zobacz WhatsApp, aby poznać kanoniczne reguły promptów systemowych WhatsApp, w tym rozstrzyganie promptów grupowych i bezpośrednich, zachowanie symboli wieloznacznych oraz semantykę nadpisań konta.

# Szczegóły WhatsApp

Zobacz Wiadomości grupowe, aby poznać zachowanie specyficzne tylko dla WhatsApp (wstrzykiwanie historii, szczegóły obsługi wzmianek).

# Powiązane

• Grupy rozgłoszeniowe
• Routing kanałów
• Wiadomości grupowe
• Parowanie