OpenClaw + WhatsApp — kompletny poradnik konfiguracji

1. Jak dziala integracja WhatsApp?

OpenClaw łączy się z WhatsApp za pomoca biblioteki Baileys — open-source'owej implementacji protokolu WhatsApp Web napisanej w TypeScript. To ta sama technologia, która uzywa WhatsApp Web w przegladarce, ale zamiast wyswietlac interfejs graficzny, OpenClaw przetwarza wiadomosci programistycznie.

W praktyce oznacza to, ze OpenClaw dziala jak dodatkowe "powiazane urządzenie" (Linked Device) na Twoim koncie WhatsApp — dokladnie tak samo jak WhatsApp Desktop czy WhatsApp Web. Twój telefon pozostaje glownym urzadzeniem, a OpenClaw łączy się jako urządzenie pomocnicze.

Gateway w OpenClaw kontroluje połączenie WebSocket i obsluguje automatyczne ponowne łączenie w przypadku zerwania połączenia. Wszystkie wiadomosci przechodzace przez gateway sa przetwarzane przez skonfigurowane agenty AI i skills.

2. Wymagania wstepne

Zanim zaczniesz konfigurowac kanal WhatsApp, upewnij się, ze masz przygotowane następujące rzeczy:

• ✓ OpenClaw zainstalowany i dzialajacy — jeśli jeszcze nie masz, zobacz poradnik instalacji
• ✓ Node.js 20 lub nowszy — Bun nie jest wspierany dla kanalu WhatsApp (stabilnosc WebSocket)
• ✓ Telefon z aktywnym WhatsApp — najlepiej z dedykowanym numerem (nie Twój główny numer osobisty)
• ✓ Skonfigurowany model AI — np. Claude, GPT-4, Gemini lub model lokalny
• ✓ Stabilne połączenie internetowe — gateway musi byc włączony 24/7 dla ciaglej komunikacji

3. Instalacja pluginu WhatsApp

WhatsApp jest dostarczany jako oficjalny plugin OpenClaw. Instalacja to jedna komenda:

$ openclaw plugins install @openclaw/whatsapp

Możesz też zainstalowac plugin automatycznie przy pierwszym wyborze kanalu WhatsApp:

$ openclaw channels add --channel whatsapp

Po instalacji sprawdz, czy plugin zostal poprawnie zaladowany:

$ openclaw channels status

Powinienes zobaczyc kanal whatsapp na liscie z informacja "not linked" — to normalne, bo jeszcze nie polaczyles konta.

4. Logowanie przez QR kod

Połączenie z WhatsApp odbywa się identycznie jak łączenie WhatsApp Web — skanujesz kod QR telefonem. Oto dokladne kroki:

$ openclaw channels login --channel whatsapp

$ openclaw channels status
# whatsapp: linked (default account)

Jeśli uzywasz wielu kont (np. prywatne i sluzbowe), możesz zalogowac się na konkretne konto:

$ openclaw channels login --channel whatsapp --account work

Dane uwierzytelniajace sa przechowywane w ~/.openclaw/credentials/whatsapp/<accountId>/creds.json. Traktuj ten plik jak haslo — nie udostepniaj go nikomu i nie wrzucaj do repozytorium Git.

5. Konfiguracja polityk dostepu

Po polaczeniu musisz zdecydowac, kto może rozmawiac z Twoim asystentem AI. OpenClaw oferuje cztery tryby dostepu dla wiadomosci prywatnych (DM):

Przykład: konfiguracja z allowlista

Dla dedykowanego numeru, gdzie chcesz dopuscic tylko swoj osobisty telefon:

// openclaw.config.json5
{
  channels: {
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+48501234567"],
    },
  },
}

Przykład: tryb parowania

W trybie parowania, gdy ktos nowy napisze do bota, dostanie kod, który musisz zatwierdzic:

// openclaw.config.json5
{
  channels: {
    whatsapp: {
      dmPolicy: "pairing",
      allowFrom: ["+48501234567"],
    },
  },
}

Zatwierdzanie oczekujących parowan:

# Lista oczekujących parowan
$ openclaw pairing list whatsapp

# Zatwierdzenie konkretnego kodu
$ openclaw pairing approve whatsapp ABC123

6. Integracja z czatami grupowymi

OpenClaw może dzialac w czatach grupowych WhatsApp, odpowiadajac na wiadomosci oznaczajace bota lub na wszystkie wiadomosci w grupie. Konfiguracja grupowa jest niezalezna od polityki DM.

Ustawienia grupowe

// openclaw.config.json5
{
  channels: {
    whatsapp: {
      dmPolicy: "pairing",
      allowFrom: ["+48501234567"],
      groupPolicy: "allowlist",
      groupAllowFrom: ["+48501234567", "+48509876543"],
    },
  },
}

Pole groupPolicy przyjmuje wartości:

• open — kazdy w grupie może wyzwalac odpowiedzi bota
• allowlist — tylko numery z groupAllowFrom moga aktywowac bota
• disabled — bot ignoruje wszystkie wiadomosci grupowe

Wyzwalanie bota w grupie

Bot w grupie reaguje na wzmianki (mentions). Wzmianke można wywolac na trzy sposoby:

• ✓ Natywna wzmianka WhatsApp (oznaczenie @)
• ✓ Skonfigurowane wzorce regex (mention patterns)
• ✓ Odpowiedź (reply) na wiadomosc bota

Możesz też przelaczac tryb aktywacji w trakcie sesji komendami:

# Bot reaguje na wszystkie wiadomosci w grupie
/activation always

# Bot reaguje tylko na wzmianki (domyslne)
/activation mention

7. Multi-device i limity polaczen

WhatsApp pozwala na połączenie maksymalnie 4 powiazanych urządzeń jednoczesnie (nie liczac głównego telefonu). OpenClaw zajmuje jeden slot, wiec zostaja Ci 3 wolne miejsca na:

• • WhatsApp Web (przegladarka)
• • WhatsApp Desktop (Windows/macOS)
• • Inne powiazane urządzenie

OpenClaw obsluguje też wiele kont WhatsApp jednoczesnie. Kazde konto to osobne połączenie z wlasnym tokenem sesji:

// Konfiguracja wielu kont
{
  channels: {
    whatsapp: {
      accounts: {
        personal: {
          sendReadReceipts: true,
        },
        work: {
          sendReadReceipts: false,
          mediaMaxMb: 100,
        },
      },
    },
  },
}

8. Bezpieczeństwo i ryzyko bana

Ochrona danych sesji

Plik creds.json w katalogu ~/.openclaw/credentials/whatsapp/ zawiera klucze sesji WhatsApp. Traktuj go jak haslo:

• ✓ Dodaj .openclaw/ do .gitignore
• ✓ Ustaw odpowiednie uprawnienia: chmod 600 creds.json
• ✓ Nie udostepniaj tego pliku przez internet
• ✓ OpenClaw tworzy automatyczny backup jako creds.json.bak

Ochrona przed self-chat

Jeśli Twój wlasny numer jest na liscie allowFrom, OpenClaw automatycznie wlacza zabezpieczenia dla wiadomosci do samego siebie:

• • Potwierdzenia odczytu (read receipts) sa pomijane
• • Automatyczne wyzwalanie przez wzmianka JID jest wylaczone
• • Odpowiedzi sa oznaczone prefiksem [openclaw] lub nazwa agenta

9. Best practices — jak unikac bana

Na podstawie doświadczeń spolecznosci OpenClaw i wiedzy o systemach anti-automation WhatsApp, oto sprawdzone praktyki minimalizujace ryzyko blokady:

sendReadReceipts: false

10. Obsługa mediow

OpenClaw obsluguje przesylanie i odbieranie różnych typow mediow przez WhatsApp:

W wiadomosciach przychodzacych, media sa reprezentowane jako placeholdery, które agent AI może interpretowac:

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

Kontekst odpowiedzi (reply) jest automatycznie dolaczany w formacie: [Replying to <sender> id:<stanzaId>]. Lokalizacja i kontakty sa normalizowane do tekstu.

11. Troubleshooting — najczestsze problemy

Poniżej znajdziesz rozwiązania najczesciej spotykanych problemow z kanalem WhatsApp w OpenClaw.

$ openclaw channels login --channel whatsapp
# Zeskanuj QR kod ponownie

# Diagnostyka
$ openclaw doctor
$ openclaw logs --follow

# Sprawdz, czy uzywasz Node.js (nie Bun)
$ node --version

# Sprawdz status połączenia
$ openclaw channels status

# Upewnij się, ze gateway jest uruchomiony
$ openclaw gateway

$ openclaw doctor            # Pełna diagnostyka
$ openclaw channels status   # Status kanalow
$ openclaw logs --follow     # Logi na zywo

12. Podsumowanie i następne kroki

Gratulacje! Jeśli wykonales wszystkie kroki, Twój asystent AI OpenClaw powinien byc teraz dostepny przez WhatsApp. Oto szybkie podsumowanie tego, co skonfigurowalas:

• ✓ Plugin WhatsApp zainstalowany i polaczony przez QR
• ✓ Polityki dostepu (DM i grupy) skonfigurowane
• ✓ Bezpieczeństwo zweryfikowane (dedykowany numer, creds.json chroniony)
• ✓ Gateway uruchomiony i nasluchujacy

Co dalej?