WhatsApp (kanal webowy)

Status: gotowy produkcyjnie przez WhatsApp Web (Baileys). Gateway jest wlascicielem polaczonych sesji.

• Parowanie — Domyslna polityka DM to parowanie dla nieznanych nadawcow.
• Rozwiazywanie problemow z kanalami — Miedzykanalowa diagnostyka i poradniki naprawy.
• Konfiguracja Gateway — Pelne wzorce i przyklady konfiguracji kanalow.

Szybka konfiguracja

Krok 1: Skonfiguruj polityke dostepu WhatsApp

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing",
      allowFrom: ["+15551234567"],
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
    },
  },
}

Krok 2: Polacz WhatsApp (QR)

openclaw channels login --channel whatsapp

Dla konkretnego konta:

openclaw channels login --channel whatsapp --account work

Krok 3: Uruchom gateway

openclaw gateway

Krok 4: Zatwierdz pierwsze zadanie parowania (jesli uzywasz trybu parowania)

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>

Zadania parowania wygasaja po 1 godzinie. Oczekujace zadania sa ograniczone do 3 na kanal.

Uwaga: OpenClaw zaleca uruchamianie WhatsApp na oddzielnym numerze gdy to mozliwe. (Metadane kanalu i przeplyw onboardingu sa zoptymalizowane pod ta konfiguracje, ale konfiguracje z osobistym numerem sa rowniez obslugiwane.)

Wzorce wdrozenia

To jest najczystszy tryb operacyjny:

- oddzielna tozsamosc WhatsApp dla OpenClaw
- wyrazniejsze listy dozwolonych DM i granice routingu
- mniejsze ryzyko pomylki z self-chatem

Minimalny wzorzec polityki:

```json5
{
  channels: {
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15551234567"],
    },
  },
}
```

Onboarding obsluguje tryb osobistego numeru i zapisuje bazowe ustawienia przyjazne dla self-chatu:

- `dmPolicy: "allowlist"`
- `allowFrom` zawiera twoj osobisty numer
- `selfChatMode: true`

W runtime zabezpieczenia self-chatu opieraja sie na polaczonym wlasnym numerze i `allowFrom`.

Kanal platformy komunikacyjnej jest oparty na WhatsApp Web (`Baileys`) w obecnej architekturze kanalow OpenClaw.

Nie ma oddzielnego kanalu wiadomosci Twilio WhatsApp w wbudowanym rejestrze kanalow czatu.

Model runtime

• Gateway jest wlascicielem gniazda WhatsApp i petli ponownego laczenia.
• Wysylki wychodzace wymagaja aktywnego listenera WhatsApp dla docelowego konta.
• Czaty statusu i rozgloszeniowe sa ignorowane (@status, @broadcast).
• Czaty bezposrednie uzywaja regul sesji DM (session.dmScope; domyslny main zwija DM do glownej sesji agenta).
• Sesje grupowe sa izolowane (agent:<agentId>:whatsapp:group:<jid>).

Kontrola dostepu i aktywacja

Polityka DM

`channels.whatsapp.dmPolicy` kontroluje dostep do czatu bezposredniego:

- `pairing` (domyslnie)
- `allowlist`
- `open` (wymaga `allowFrom` zawierajacego `"*"`)
- `disabled`

`allowFrom` akceptuje numery w stylu E.164 (normalizowane wewnetrznie).

Nadpisanie wielokontowe: `channels.whatsapp.accounts.<id>.dmPolicy` (i `allowFrom`) maja pierwszenstwo nad domyslnymi na poziomie kanalu dla tego konta.

Szczegoly zachowania runtime:

- parowania sa utrwalane w magazynie dozwolonych kanalu i lączone ze skonfigurowanym `allowFrom`
- jesli nie skonfigurowano listy dozwolonych, polaczony wlasny numer jest domyslnie dozwolony
- wychodzace DM `fromMe` nigdy nie sa automatycznie parowane

Polityka grupowa + listy dozwolonych

Dostep grupowy ma dwie warstwy:

1. **Lista dozwolonych czlonkostwa w grupie** (`channels.whatsapp.groups`)
   - jesli `groups` jest pominiete, wszystkie grupy sa kwalifikowalne
   - jesli `groups` jest obecne, dziala jako lista dozwolonych grup (dozwolone `"*"`)

2. **Polityka nadawcow grupowych** (`channels.whatsapp.groupPolicy` + `groupAllowFrom`)
   - `open`: lista dozwolonych nadawcow jest pomijana
   - `allowlist`: nadawca musi pasowac do `groupAllowFrom` (lub `*`)
   - `disabled`: blokuj wszystkie przychodzace grupowe

Zastepczym listy dozwolonych nadawcow:

- jesli `groupAllowFrom` nie jest ustawione, runtime stosuje zastepczym `allowFrom` gdy dostepne
- listy dozwolonych nadawcow sa oceniane przed aktywacja wzmianki/odpowiedzi

Uwaga: jesli nie istnieje blok `channels.whatsapp`, zastepczym polityki grupowej runtime to `allowlist` (z ostrzezeniem w logach), nawet jesli `channels.defaults.groupPolicy` jest ustawione.

Wzmianki + /activation

Odpowiedzi grupowe domyslnie wymagaja wzmianki.

Wykrywanie wzmianek obejmuje:

- jawne wzmianki WhatsApp tozsamosci bota
- skonfigurowane wzorce regex wzmianek (`agents.list[].groupChat.mentionPatterns`, zastepczym `messages.groupChat.mentionPatterns`)
- niejawne wykrywanie odpowiedzi-do-bota (nadawca odpowiedzi pasuje do tozsamosci bota)

Uwaga bezpieczenstwa:

- cytat/odpowiedz spelnia jedynie bramkowanie wzmiankami; **nie** nadaje autoryzacji nadawcy
- z `groupPolicy: "allowlist"`, nadawcy spoza listy dozwolonych sa nadal blokowani nawet jesli odpowiadaja na wiadomosc uzytkownika z listy dozwolonych

Polecenie aktywacji na poziomie sesji:

- `/activation mention`
- `/activation always`

`activation` aktualizuje stan sesji (nie globalna konfiguracje). Jest bramkowane dla wlasciciela.

Zachowanie osobistego numeru i self-chatu

Gdy polaczony wlasny numer jest rowniez obecny w allowFrom, aktywuja sie zabezpieczenia self-chatu WhatsApp:

• pomijanie potwierdzen odczytu dla tur self-chatu
• ignorowanie zachowania automatycznego wyzwalania wzmianek-JID, ktore w przeciwnym razie pingowaloby ciebie samego
• jesli messages.responsePrefix nie jest ustawiony, odpowiedzi self-chatu domyslnie uzywaja [{identity.name}] lub [openclaw]

Normalizacja wiadomosci i kontekst

Przychodzace wiadomosci WhatsApp sa opakowywane we wspolna koperte przychodzaca.

Jesli istnieje cytowana odpowiedz, kontekst jest dolaczany w tej formie:

```text
[Replying to <sender> id:<stanzaId>]
<cytowane cialo lub zastepczym mediow>
[/Replying]
```

Pola metadanych odpowiedzi sa rowniez wypelniane gdy dostepne (`ReplyToId`, `ReplyToBody`, `ReplyToSender`, JID/E.164 nadawcy).

Wiadomosci przychodzace zawierajace tylko media sa normalizowane zastepczymi takimi jak:

- `<media:image>`
- `<media:video>`
- `<media:audio>`
- `<media:document>`
- `<media:sticker>`

Payloady lokalizacji i kontaktow sa normalizowane do kontekstu tekstowego przed routingiem.

Dla grup nieprzywrotzone wiadomosci moga byc buforowane i wstrzykiwane jako kontekst, gdy bot jest wreszcie wyzwolony.

- domyslny limit: `50`
- konfiguracja: `channels.whatsapp.historyLimit`
- zastepczym: `messages.groupChat.historyLimit`
- `0` wylacza

Znaczniki wstrzykiwania:

- `[Chat messages since your last reply - for context]`
- `[Current message - respond to this]`

Potwierdzenia odczytu sa domyslnie wlaczone dla zaakceptowanych przychodzacych wiadomosci WhatsApp.

Wylacz globalnie:

```json5
{
  channels: {
    whatsapp: {
      sendReadReceipts: false,
    },
  },
}
```

Nadpisanie per konto:

```json5
{
  channels: {
    whatsapp: {
      accounts: {
        work: {
          sendReadReceipts: false,
        },
      },
    },
  },
}
```

Tury self-chatu pomijaja potwierdzenia odczytu nawet gdy globalnie wlaczone.

Dostarczanie, dzielenie na kawalki i media

- domyslny limit kawalka: `channels.whatsapp.textChunkLimit = 4000`
- `channels.whatsapp.chunkMode = "length" | "newline"`
- tryb `newline` preferuje granice akapitow (puste linie), nastepnie stosuje zastepczym dzielenie bezpieczne wedlug dlugosci

- obsluguje payloady obrazow, wideo, dzwieku (notatka glosowa PTT) i dokumentow
- `audio/ogg` jest przepisywany na `audio/ogg; codecs=opus` dla kompatybilnosci z notatkami glosowymi
- odtwarzanie animowanych GIF-ow jest obslugiwane przez `gifPlayback: true` przy wysylce wideo
- podpisy sa stosowane do pierwszego elementu mediow przy wysylaniu wielomediowych payloadow odpowiedzi
- zrodlo mediow moze byc HTTP(S), `file://` lub sciezki lokalne

- limit zapisu mediow przychodzacych: `channels.whatsapp.mediaMaxMb` (domyslnie `50`)
- limit wysylki mediow wychodzacych: `channels.whatsapp.mediaMaxMb` (domyslnie `50`)
- nadpisania per konto uzywaja `channels.whatsapp.accounts.<accountId>.mediaMaxMb`
- obrazy sa automatycznie optymalizowane (zmiana rozmiaru/jakosci) aby zmiescic sie w limitach
- przy awarii wysylki mediow zastepczym pierwszego elementu wysyla ostrzezenie tekstowe zamiast cicho porzucac odpowiedz

Reakcje potwierdzajace

WhatsApp obsluguje natychmiastowe reakcje ack na odebrane przychodzace przez channels.whatsapp.ackReaction.

{
  channels: {
    whatsapp: {
      ackReaction: {
        emoji: "👀",
        direct: true,
        group: "mentions", // always | mentions | never
      },
    },
  },
}

Uwagi dotyczace zachowania:

• wysylane natychmiast po zaakceptowaniu przychodzacej (przed odpowiedzia)
• awarie sa logowane, ale nie blokuja normalnego dostarczania odpowiedzi
• tryb grupowy mentions reaguje na turach wyzwolonych wzmiankami; aktywacja grupowa always dziala jako obejscie tego sprawdzenia
• WhatsApp uzywa channels.whatsapp.ackReaction (starsze messages.ackReaction nie jest tu uzywane)

Wiele kont i dane logowania

- ID kont pochodza z `channels.whatsapp.accounts`
- domyslny wybor konta: `default` jesli obecny, w przeciwnym razie pierwsze skonfigurowane ID konta (posortowane)
- ID kont sa normalizowane wewnetrznie do wyszukiwania

- aktualna sciezka autoryzacji: `~/.openclaw/credentials/whatsapp/<accountId>/creds.json`
- plik kopii zapasowej: `creds.json.bak`
- starsze domyslne autoryzacje w `~/.openclaw/credentials/` sa nadal rozpoznawane/migrowane dla przeplywow domyslnego konta

`openclaw channels logout --channel whatsapp [--account <id>]` czysci stan autoryzacji WhatsApp dla tego konta.

W starszych katalogach autoryzacji `oauth.json` jest zachowywany, a pliki autoryzacji Baileys sa usuwane.

Narzedzia, akcje i zapisy konfiguracji

• Obsluga narzedzi agenta obejmuje akcje reakcji WhatsApp (react).
• Bramki akcji:
  • channels.whatsapp.actions.reactions
  • channels.whatsapp.actions.polls
• Zapisy konfiguracji inicjowane z kanalu sa domyslnie wlaczone (wylacz przez channels.whatsapp.configWrites=false).

Rozwiazywanie problemow

Objaw: status kanalu raportuje brak polaczenia.

Rozwiazanie:

```bash
openclaw channels login --channel whatsapp
openclaw channels status
```

Objaw: polaczone konto z powtarzajacymi sie rozlaczeniami lub probami ponownego laczenia.

Rozwiazanie:

```bash
openclaw doctor
openclaw logs --follow
```

Jesli potrzeba, polacz ponownie przez `channels login`.

Wysylki wychodzace natychmiast nie dzialaja gdy nie istnieje aktywny listener gateway dla docelowego konta.

Upewnij sie, ze gateway dziala i konto jest polaczone.

Sprawdz w kolejnosci:

- `groupPolicy`
- `groupAllowFrom` / `allowFrom`
- wpisy listy dozwolonych `groups`
- bramkowanie wzmiankami (`requireMention` + wzorce wzmianek)
- zduplikowane klucze w `openclaw.json` (JSON5): pozniejsze wpisy nadpisuja wczesniejsze, wiec utrzymuj pojedynczy `groupPolicy` na zakres

Runtime gateway WhatsApp powinien uzywac Node. Bun jest oznaczony jako niekompatybilny dla stabilnej operacji gateway WhatsApp/Telegram.

Wskazowki referencji konfiguracji

Glowna referencja:

• Referencja konfiguracji - WhatsApp

Klucozwe pola WhatsApp:

• dostep: dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups
• dostarczanie: textChunkLimit, chunkMode, mediaMaxMb, sendReadReceipts, ackReaction
• wielokontowe: accounts.<id>.enabled, accounts.<id>.authDir, nadpisania na poziomie konta
• operacje: configWrites, debounceMs, web.enabled, web.heartbeatSeconds, web.reconnect.*
• zachowanie sesji: session.dmScope, historyLimit, dmHistoryLimit, dms.<id>.historyLimit

Powiazane

• Parowanie
• Routing kanalow
• Routing wieloagentowy
• Rozwiazywanie problemow