// dokumentacja openclaw

Integracja OpenClaw z WhatsApp — konfiguracja i połączenie

Wprowadzenie

OpenClaw integruje się z WhatsApp za pośrednictwem WhatsApp Web, korzystając z technologii Baileys. Kanał jest gotowy do użycia produkcyjnego i pozwala na prowadzenie rozmów prywatnych, obsługę grup, wymianę mediów oraz konfigurację reakcji.

Metody instalacji

Wtyczkę WhatsApp można zainstalować na trzy sposoby:

  • Kreator konfiguracji: openclaw onboard lub openclaw channels add --channel whatsapp
  • Logowanie: openclaw channels login --channel whatsapp
  • Ręczna instalacja: openclaw plugins install @openclaw/whatsapp

Szybka konfiguracja

Konfiguracja WhatsApp obejmuje cztery kroki:

  1. Ustaw politykę dostępu — określ, kto może pisać do bota (DM, grupy, lista dozwolonych)
  2. Połącz konto WhatsApp — zeskanuj kod QR poleceniem openclaw channels login --channel whatsapp
  3. Uruchom Gateway — openclaw gateway
  4. Zatwierdź parowanie — jeśli używasz trybu parowania: openclaw pairing approve whatsapp KOD

OpenClaw zaleca używanie dedykowanego numeru telefonu zamiast prywatnego konta, gdy jest to możliwe.

Wzorce wdrożeń

Dedykowany numer (zalecane)

Osobna tożsamość WhatsApp zapewnia wyraźne granice routingu i minimalną konfigurację polityki. Użyj dmPolicy: "allowlist" z listą zaufanych numerów.

Numer osobisty

Możesz też korzystać z osobistego konta WhatsApp. W takim wypadku włącz tryb samokonwersacji (selfChatMode: true) i dodaj swój numer do allowFrom. System automatycznie pominie potwierdzenia odczytu i auto-wyzwalacze dla wiadomości do siebie.

Kontrola dostępu

Polityka DM

  • pairing (domyślny) — nieznani nadawcy otrzymują kod parowania
  • allowlist — tylko skonfigurowane numery mogą pisać
  • open — wymaga "*" w allowFrom
  • disabled — wiadomości prywatne zablokowane

System akceptuje numery w formacie E.164 i automatycznie łączy zatwierdzenia parowania z listami dozwolonych.

Polityka grup

Grupy korzystają z dwuwarstwowego systemu: lista dozwolonych grup oraz lista dozwolonych nadawców w grupach.

  • open — pomija ograniczenia nadawcy
  • allowlist — wymaga dopasowania nadawcy
  • disabled — blokuje wiadomości grupowe

Jeśli groupAllowFrom nie jest ustawione, system korzysta z allowFrom jako wartości domyślnej.

Wymaganie wzmianki

Domyślnie w grupach bot wymaga wzmianki (mention). Jawne wzmianki @nazwa, wzorce regex i wykrywanie odpowiedzi na wiadomości bota spełniają to wymaganie. Sesyjne komendy aktywacji: /activation mention lub /activation always.

Obsługa wiadomości

Kontekst przychodzących wiadomości

Wiadomości zawierają kontekst odpowiedzi sformatowany jako:

[Replying to <nadawca> id:<stanzaId>]
<treść lub placeholder mediów>
[/Replying]

Media

Obsługiwane typy mediów: obrazy, wideo, audio (notatki głosowe PTT), dokumenty i naklejki. Domyślny limit rozmiaru to 50 MB (mediaMaxMb). Format audio/ogg jest automatycznie konwertowany do audio/ogg; codecs=opus. Animowane GIF-y działają z ustawieniem gifPlayback: true.

Dzielenie tekstu

Domyślny limit to 4000 znaków (textChunkLimit). Tryby podziału:

  • length — dzielenie po osiągnięciu limitu znaków
  • newline — preferuje dzielenie na granicach akapitów

Reakcje

Ustawienie reactionLevel kontroluje używanie reakcji emoji:

  • off — brak reakcji
  • ack — tylko potwierdzenie odbioru
  • minimal (domyślny) — konserwatywne reakcje agenta
  • extensive — zachęcanie do częstych reakcji

Reakcje potwierdzające są wysyłane po zaakceptowaniu wiadomości, przed wygenerowaniem odpowiedzi. Ewentualne niepowodzenia nie blokują dostarczenia odpowiedzi.

Zarządzanie wieloma kontami

Możesz skonfigurować wiele kont WhatsApp w sekcji channels.whatsapp.accounts. Domyślnie używane jest konto default, a jeśli nie istnieje — pierwsze w kolejności sortowania. Dane uwierzytelniające przechowywane są w ~/.openclaw/credentials/whatsapp/<accountId>/creds.json.

Wylogowanie: openclaw channels logout --channel whatsapp [--account <id>]

Rozwiązywanie problemów

  • Brak połączenia — uruchom openclaw channels login --channel whatsapp i sprawdź openclaw channels status
  • Rozłączenia — wykonaj openclaw doctor i openclaw logs --follow
  • Błędy wysyłki — sprawdź, czy Gateway działa i konto jest połączone
  • Ignorowane wiadomości grupowe — zweryfikuj groupPolicy, listy dozwolonych, wpisy groups, wymaganie wzmianki i duplikację kluczy w JSON5
  • Runtime Bun — użyj Node zamiast Bun, który jest oznaczony jako niekompatybilny
Wróc do dokumentacji