Przejdź do głównej treści

​
WhatsApp (kanał Web)

Status: gotowy do użycia produkcyjnego przez WhatsApp Web (Baileys). Brama zarządza połączonymi sesjami.

​
Instalacja (na żądanie)

  • Onboarding (openclaw onboard) i openclaw channels add --channel whatsapp przy pierwszym wybraniu kanału proponują instalację pluginu WhatsApp.
  • openclaw channels login --channel whatsapp także oferuje przepływ instalacji, gdy plugin nie jest jeszcze obecny.
  • Kanał deweloperski + checkout git: domyślnie używa lokalnej ścieżki pluginu.
  • Stable/Beta: domyślnie używa pakietu npm @openclaw/whatsapp.
Instalacja ręczna nadal jest dostępna: 
openclaw plugins install @openclaw/whatsapp

Parowanie

Domyślna polityka DM dla nieznanych nadawców to parowanie.

Rozwiązywanie problemów z kanałem

Diagnostyka międzykanałowa i procedury naprawcze.

Konfiguracja bramy

Pełne wzorce konfiguracji kanałów i przykłady.

​
Szybka konfiguracja

1

Skonfiguruj politykę dostępu WhatsApp

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

Połącz WhatsApp (QR)

openclaw channels login --channel whatsapp
Dla konkretnego konta:
openclaw channels login --channel whatsapp --account work
3

Uruchom bramę

openclaw gateway
4

Zatwierdź pierwszą prośbę o parowanie (jeśli używasz trybu parowania)

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>
Prośby o parowanie wygasają po 1 godzinie. Liczba oczekujących próśb jest ograniczona do 3 na kanał.
OpenClaw zaleca, jeśli to możliwe, uruchamianie WhatsApp na osobnym numerze. (Metadane kanału i przepływ konfiguracji są zoptymalizowane pod taki układ, ale konfiguracje z numerem osobistym również są obsługiwane.)

​
Wzorce wdrożenia

To najczystszy tryb operacyjny:
  • osobna tożsamość WhatsApp dla OpenClaw
  • wyraźniejsze listy dozwolonych DM i granice routingu
  • mniejsze ryzyko niejasności związanych z czatem z samym sobą
Minimalny wzorzec polityki:
{
  channels: {
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15551234567"],
    },
  },
}
Onboarding obsługuje tryb numeru osobistego i zapisuje bazową konfigurację przyjazną czatowi z samym sobą:
  • dmPolicy: "allowlist"
  • allowFrom zawiera Twój numer osobisty
  • selfChatMode: true
W czasie działania zabezpieczenia czatu z samym sobą opierają się na połączonym własnym numerze i allowFrom.
Kanał platformy wiadomości w bieżącej architekturze kanałów OpenClaw jest oparty na WhatsApp Web (Baileys).W wbudowanym rejestrze kanałów czatu nie ma osobnego kanału wiadomości WhatsApp przez Twilio.

​
Model działania

  • Brama zarządza gniazdem WhatsApp i pętlą ponownego łączenia.
  • Wysyłanie wychodzące wymaga aktywnego nasłuchu WhatsApp dla docelowego konta.
  • Czaty statusów i rozgłoszeniowe są ignorowane (@status, @broadcast).
  • Czaty bezpośrednie używają reguł sesji DM (session.dmScope; domyślne main zwija DM do głównej sesji agenta).
  • Sesje grupowe są izolowane (agent:<agentId>:whatsapp:group:<jid>).

​
Kontrola dostępu i aktywacja

channels.whatsapp.dmPolicy kontroluje dostęp do czatów bezpośrednich:
  • pairing (domyślnie)
  • allowlist
  • open (wymaga, aby allowFrom zawierało "*")
  • disabled
allowFrom akceptuje numery w stylu E.164 (normalizowane wewnętrznie).Nadpisanie dla wielu kont: channels.whatsapp.accounts.<id>.dmPolicy (oraz allowFrom) ma pierwszeństwo przed domyślnymi ustawieniami na poziomie kanału dla tego konta.Szczegóły zachowania w czasie działania:
  • parowania są utrwalane w magazynie list dozwolonych kanału i łączone ze skonfigurowanym allowFrom
  • jeśli nie skonfigurowano żadnej listy dozwolonych, połączony własny numer jest domyślnie dozwolony
  • wychodzące DM fromMe nigdy nie są automatycznie parowane

​
Numer osobisty i zachowanie czatu z samym sobą

Gdy połączony własny numer jest również obecny w allowFrom, aktywują się zabezpieczenia czatu z samym sobą w WhatsApp:
  • pomijanie potwierdzeń odczytu dla tur czatu z samym sobą
  • ignorowanie zachowania automatycznego wyzwalania mention-JID, które w przeciwnym razie pingowałoby Ciebie
  • jeśli messages.responsePrefix nie jest ustawione, odpowiedzi w czacie z samym sobą domyślnie używają [{identity.name}] lub [openclaw]

​
Normalizacja wiadomości i kontekst

Przychodzące wiadomości WhatsApp są opakowywane we wspólną kopertę wejściową.Jeśli istnieje cytowana odpowiedź, kontekst jest dołączany w tej postaci:
[Odpowiedź na <sender> id:<stanzaId>]
<quoted body or media placeholder>
[/Odpowiedź]
Pola metadanych odpowiedzi są również wypełniane, gdy są dostępne (ReplyToId, ReplyToBody, ReplyToSender, nadawca JID/E.164).
Przychodzące wiadomości zawierające tylko multimedia są normalizowane za pomocą symboli zastępczych, takich jak:
  • <media:image>
  • <media:video>
  • <media:audio>
  • <media:document>
  • <media:sticker>
Ładunki lokalizacji i kontaktów są normalizowane do kontekstu tekstowego przed routingiem.
W przypadku grup nieprzetworzone wiadomości mogą być buforowane i wstrzykiwane jako kontekst, gdy bot zostanie w końcu wyzwolony.
  • domyślny limit: 50
  • konfiguracja: channels.whatsapp.historyLimit
  • zapasowo: messages.groupChat.historyLimit
  • 0 wyłącza
Markery wstrzyknięcia:
  • [Wiadomości czatu od Twojej ostatniej odpowiedzi - dla kontekstu]
  • [Bieżąca wiadomość - odpowiedz na nią]
Potwierdzenia odczytu są domyślnie włączone dla zaakceptowanych przychodzących wiadomości WhatsApp.Wyłącz globalnie:
{
  channels: {
    whatsapp: {
      sendReadReceipts: false,
    },
  },
}
Nadpisanie dla konta:
{
  channels: {
    whatsapp: {
      accounts: {
        work: {
          sendReadReceipts: false,
        },
      },
    },
  },
}
Tury czatu z samym sobą pomijają potwierdzenia odczytu nawet wtedy, gdy są globalnie włączone.

​
Dostarczanie, dzielenie i multimedia

  • domyślny limit fragmentu: channels.whatsapp.textChunkLimit = 4000
  • channels.whatsapp.chunkMode = "length" | "newline"
  • tryb newline preferuje granice akapitów (puste wiersze), a następnie wraca do bezpiecznego dzielenia według długości
  • obsługuje ładunki obrazów, wideo, audio (głosowe PTT) i dokumentów
  • audio/ogg jest przepisywane na audio/ogg; codecs=opus dla zgodności z wiadomościami głosowymi
  • odtwarzanie animowanych GIF-ów jest obsługiwane przez gifPlayback: true przy wysyłaniu wideo
  • podpisy są stosowane do pierwszego elementu multimedialnego podczas wysyłania odpowiedzi wielomediowych
  • źródłem multimediów może być HTTP(S), file:// lub ścieżka lokalna
  • limit zapisu mediów przychodzących: channels.whatsapp.mediaMaxMb (domyślnie 50)
  • limit wysyłania mediów wychodzących: channels.whatsapp.mediaMaxMb (domyślnie 50)
  • nadpisania dla kont używają channels.whatsapp.accounts.<accountId>.mediaMaxMb
  • obrazy są automatycznie optymalizowane (zmiana rozmiaru/przebieg jakości), aby zmieścić się w limitach
  • przy błędzie wysyłania mediów zapasowy mechanizm dla pierwszego elementu wysyła ostrzeżenie tekstowe zamiast cicho porzucać odpowiedź

​
Poziom reakcji

channels.whatsapp.reactionLevel kontroluje, jak szeroko agent używa reakcji emoji w WhatsApp:
PoziomReakcje potwierdzająceReakcje inicjowane przez agentaOpis
"off"NieNieBrak jakichkolwiek reakcji
"ack"TakNieTylko reakcje potwierdzające (potwierdzenie przed odpowiedzią)
"minimal"TakTak (zachowawczo)Potwierdzenie + reakcje agenta z zachowawczymi wskazówkami
"extensive"TakTak (zalecane)Potwierdzenie + reakcje agenta z zalecanymi wskazówkami
Domyślnie: "minimal". Nadpisania dla kont używają channels.whatsapp.accounts.<id>.reactionLevel. 
{
  channels: {
    whatsapp: {
      reactionLevel: "ack",
    },
  },
}

​
Reakcje potwierdzające

WhatsApp obsługuje natychmiastowe reakcje potwierdzające po odebraniu wiadomości przychodzącej przez channels.whatsapp.ackReaction. Reakcje potwierdzające są kontrolowane przez reactionLevel — są wyciszane, gdy reactionLevel to "off". 
{
  channels: {
    whatsapp: {
      ackReaction: {
        emoji: "👀",
        direct: true,
        group: "mentions", // always | mentions | never
      },
    },
  },
}
Uwagi dotyczące zachowania:
  • wysyłane natychmiast po zaakceptowaniu wiadomości przychodzącej (przed odpowiedzią)
  • błędy są logowane, ale nie blokują normalnego dostarczenia odpowiedzi
  • tryb grupowy mentions reaguje przy turach wyzwolonych wzmianką; aktywacja grupowa always działa jako obejście tego sprawdzenia
  • WhatsApp używa channels.whatsapp.ackReaction (starsze messages.ackReaction nie jest tutaj używane)

​
Wiele kont i poświadczenia

  • identyfikatory kont pochodzą z channels.whatsapp.accounts
  • domyślny wybór konta: default, jeśli istnieje, w przeciwnym razie pierwszy skonfigurowany identyfikator konta (posortowany)
  • identyfikatory kont są wewnętrznie normalizowane na potrzeby wyszukiwania
  • bieżąca ścieżka uwierzytelniania: ~/.openclaw/credentials/whatsapp/<accountId>/creds.json
  • plik kopii zapasowej: creds.json.bak
  • starsze domyślne uwierzytelnianie w ~/.openclaw/credentials/ jest nadal rozpoznawane/migrowane dla przepływów domyślnego konta
openclaw channels logout --channel whatsapp [--account <id>] czyści stan uwierzytelniania WhatsApp dla tego konta.W starszych katalogach uwierzytelniania oauth.json jest zachowywany, podczas gdy pliki uwierzytelniania Baileys są usuwane.

​
Narzędzia, akcje i zapisy konfiguracji

  • Obsługa narzędzi agenta obejmuje akcję reakcji WhatsApp (react).
  • Bramki akcji:
    • channels.whatsapp.actions.reactions
    • channels.whatsapp.actions.polls
  • Zapisy konfiguracji inicjowane przez kanał są domyślnie włączone (wyłącz przez channels.whatsapp.configWrites=false).

​
Rozwiązywanie problemów

Objaw: status kanału zgłasza brak połączenia.Naprawa:
openclaw channels login --channel whatsapp
openclaw channels status
Objaw: połączone konto z powtarzającymi się rozłączeniami lub próbami ponownego połączenia.Naprawa:
openclaw doctor
openclaw logs --follow
W razie potrzeby połącz ponownie przez channels login.
Wysyłanie wychodzące szybko kończy się błędem, gdy dla docelowego konta nie istnieje aktywny nasłuch bramy.Upewnij się, że brama działa i konto jest połączone.
Sprawdź w tej kolejności:
  • groupPolicy
  • groupAllowFrom / allowFrom
  • wpisy listy dozwolonych groups
  • bramkowanie wzmianek (requireMention + wzorce wzmianek)
  • zduplikowane klucze w openclaw.json (JSON5): późniejsze wpisy nadpisują wcześniejsze, więc zachowaj tylko jedno groupPolicy na zakres
Środowisko działania bramy WhatsApp powinno używać Node. Bun jest oznaczony jako niekompatybilny ze stabilnym działaniem bramy WhatsApp/Telegram.

​
Wskaźniki dokumentacji konfiguracji

Podstawowa dokumentacja: Pola WhatsApp o wysokim znaczeniu:
  • dostęp: dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups
  • dostarczanie: textChunkLimit, chunkMode, mediaMaxMb, sendReadReceipts, ackReaction, reactionLevel
  • wiele kont: 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

​
Powiązane