Wiadomosci grupowe (kanal webowy WhatsApp)

Cel: pozwolic Clawd siedziec w grupach WhatsApp, budzic sie tylko po pingniecin i utrzymywac ten watek oddzielnie od osobistej sesji DM.

Uwaga: agents.list[].groupChat.mentionPatterns jest teraz uzywany rowniez przez Telegram/Discord/Slack/iMessage; ta dokumentacja skupia sie na zachowaniu specyficznym dla WhatsApp. W konfiguracjach wieloagentowych ustaw agents.list[].groupChat.mentionPatterns dla kazdego agenta (lub uzyj messages.groupChat.mentionPatterns jako globalnego zastepczego).

Co jest zaimplementowane (2025-12-03)

• Tryby aktywacji: mention (domyslny) lub always. mention wymaga pingniecin (prawdziwe @-wzmianki WhatsApp przez mentionedJids, wzorce regex lub E.164 bota gdziekolwiek w tekscie). always budzi agenta przy kazdej wiadomosci, ale powinien on odpowiadac tylko wtedy, gdy moze wniesc merytoryczna wartosc; w przeciwnym razie zwraca token ciszy NO_REPLY. Domyslne mozna ustawic w konfiguracji (channels.whatsapp.groups) i nadpisac per grupa przez /activation. Gdy channels.whatsapp.groups jest ustawione, dziala tez jako lista dozwolonych grup (dodaj "*" aby zezwolic na wszystkie).
• Polityka grupowa: channels.whatsapp.groupPolicy kontroluje, czy wiadomosci grupowe sa akceptowane (open|disabled|allowlist). allowlist uzywa channels.whatsapp.groupAllowFrom (zastepczym: jawne channels.whatsapp.allowFrom). Domyslna to allowlist (blokowane do momentu dodania nadawcow).
• Sesje per grupa: klucze sesji wygladaja jak agent:<agentId>:whatsapp:group:<jid>, wiec polecenia takie jak /verbose on czy /think high (wyslane jako samodzielne wiadomosci) sa ograniczone do tej grupy; stan osobistych DM pozostaje nietkniety. Heartbeaty sa pomijane dla watkow grupowych.
• Wstrzykiwanie kontekstu: oczekujace wiadomosci grupowe (domyslnie 50), ktore nie wyzwolily uruchomienia, sa dodawane z prefiksem [Chat messages since your last reply - for context], a wiadomosc wyzwalajaca pod [Current message - respond to this]. Wiadomosci juz w sesji nie sa ponownie wstrzykiwane.
• Wyswietlanie nadawcy: kazda partia grupowa konczy sie teraz [from: Sender Name (+E164)], wiec Pi wie, kto mowi.
• Efemeryczne/view-once: rozpakowujemy je przed wyodrebnieniem tekstu/wzmianek, wiec pingi wewnatrz nich nadal wyzwalaja.
• Prompt systemowy grupy: na pierwszym kroku sesji grupowej (i za kazdym razem, gdy /activation zmienia tryb) wstrzykujemy krotki blurb do promptu systemowego, np. You are replying inside the WhatsApp group "<subject>". Group members: Alice (+44...), Bob (+43...), … Activation: trigger-only … Address the specific sender noted in the message context. Jesli metadane nie sa dostepne, nadal informujemy agenta, ze to czat grupowy.

Przyklad konfiguracji (WhatsApp)

Dodaj blok groupChat do ~/.openclaw/openclaw.json, aby pingi po nazwie wyswietlanej dzialaly nawet gdy WhatsApp usuwa wizualne @ z tresci wiadomosci:

{
  channels: {
    whatsapp: {
      groups: {
        "*": { requireMention: true },
      },
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          historyLimit: 50,
          mentionPatterns: ["@?openclaw", "\\+?15555550123"],
        },
      },
    ],
  },
}

Uwagi:

• Wyrazenia regularne sa niewrazliwe na wielkosc liter; obejmuja ping po nazwie wyswietlanej jak @openclaw i surowy numer z lub bez +/spacji.
• WhatsApp nadal wysyla kanoniczne wzmianki przez mentionedJids gdy ktos tapnie kontakt, wiec zastepczym numer jest rzadko potrzebny, ale jest przydatna siatka bezpieczenstwa.

Polecenie aktywacji (tylko wlasciciel)

Uzyj polecenia czatu grupowego:

• /activation mention
• /activation always

Tylko numer wlasciciela (z channels.whatsapp.allowFrom lub wlasny E.164 bota gdy nie ustawiony) moze to zmieniac. Wyslij /status jako samodzielna wiadomosc w grupie, aby zobaczyc aktualny tryb aktywacji.

Jak uzywac

1. Dodaj swoje konto WhatsApp (to z OpenClaw) do grupy.
2. Napisz @openclaw … (lub umiesc numer). Tylko nadawcy z listy dozwolonych moga wyzwalac, chyba ze ustawisz groupPolicy: "open".
3. Prompt agenta bedzie zawieral ostatni kontekst grupowy plus koncowy znacznik [from: …], dzieki czemu moze odpowiedziec wlasciwej osobie.
4. Dyrektywy sesji (/verbose on, /think high, /new lub /reset, /compact) dotycza tylko sesji tej grupy; wyslij je jako samodzielne wiadomosci, aby zostaly zarejestrowane. Twoja osobista sesja DM pozostaje niezalezna.

Testowanie / weryfikacja

• Reczny test:
  • Wyslij ping @openclaw w grupie i potwierdz odpowiedz, ktora odwoluje sie do nazwy nadawcy.
  • Wyslij drugi ping i zweryfikuj, ze blok historii jest dolaczony, a potem wyczyszczony w nastepnym kroku.
• Sprawdz logi gateway (uruchom z --verbose), aby zobaczyc wpisy inbound web message pokazujace from: <groupJid> i sufiks [from: …].

Znane uwagi

• Heartbeaty sa celowo pomijane dla grup, aby unikac halasliwych rozgloszen.
• Tlumienie echa uzywa polaczonego ciagu partii; jesli wyslasz identyczny tekst dwukrotnie bez wzmianek, tylko pierwszy uzyska odpowiedz.
• Wpisy magazynu sesji pojawia sie jako agent:<agentId>:whatsapp:group:<jid> w magazynie sesji (~/.openclaw/agents/<agentId>/sessions/sessions.json domyslnie); brak wpisu oznacza po prostu, ze grupa nie wyzwolila jeszcze uruchomienia.
• Wskazniki pisania w grupach kieruja sie agents.defaults.typingMode (domyslnie: message gdy nie wspomniony).