WhatsApp

Status: gotowe do użytku produkcyjnego za pośrednictwem WhatsApp Web (Baileys). Gateway zarządza połączonymi sesjami; nie istnieje osobny kanał Twilio WhatsApp.

Instalacja

openclaw onboard i openclaw channels add --channel whatsapp wyświetlają monit o zainstalowanie pluginu przy jego pierwszym wyborze; openclaw channels login --channel whatsapp oferuje ten sam proces instalacji, jeśli brakuje pluginu. Wersje deweloperskie używają lokalnej ścieżki pluginu; instalacje stabilne/beta najpierw instalują @openclaw/whatsapp z ClawHub, a w razie niepowodzenia korzystają z npm. Środowisko uruchomieniowe WhatsApp jest dostarczane poza podstawowym pakietem npm OpenClaw, dlatego jego zależności uruchomieniowe pozostają w zewnętrznym pluginie. Instalacja ręczna:

openclaw plugins install clawhub:@openclaw/whatsapp

Używaj samego pakietu npm (@openclaw/whatsapp) wyłącznie jako rozwiązania rezerwowego dla rejestru; przypinaj dokładną wersję tylko wtedy, gdy potrzebujesz powtarzalnej instalacji.

Szybka konfiguracja

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

openclaw channels login --channel whatsapp

openclaw channels login --channel whatsapp --account work

openclaw channels add --channel whatsapp --account work --auth-dir /path/to/wa-authopenclaw channels login --channel whatsapp --account work

openclaw gateway

openclaw pairing list whatsappopenclaw pairing approve whatsapp <CODE>

Wzorce wdrażania

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

Model środowiska uruchomieniowego

• Gateway zarządza gniazdem WhatsApp i pętlą ponownego łączenia.
• Mechanizm nadzorujący śledzi niezależnie dwa sygnały: surową aktywność transportu WhatsApp Web oraz aktywność wiadomości aplikacji. Cicha, lecz połączona sesja nie jest ponownie uruchamiana tylko dlatego, że ostatnio nie nadeszła żadna wiadomość; ponowne połączenie jest wymuszane wyłącznie wtedy, gdy ramki transportowe przestają napływać przez stały wewnętrzny okres (niekonfigurowalny przez użytkownika) lub wiadomości aplikacji nie pojawiają się przez okres przekraczający czterokrotność standardowego limitu czasu wiadomości. Bezpośrednio po ponownym połączeniu niedawno aktywnej sesji pierwsze okno używa krótszego, standardowego limitu czasu wiadomości zamiast okna czterokrotnie dłuższego. OpenClaw może automatycznie odpowiadać na wiadomości offline, które Baileys dostarcza na wczesnym etapie tego ponownego połączenia, z ograniczeniem wynikającym z czasu życia deduplikacji identyfikatorów wiadomości przychodzących; początkowe uruchomienie zachowuje krótki mechanizm ochrony przed nieaktualną historią.
• Czasy gniazda Baileys są jawnie określone w web.whatsapp.*: keepAliveIntervalMs (interwał sygnału ping aplikacji), connectTimeoutMs (limit czasu początkowego uzgadniania połączenia), defaultQueryTimeoutMs (oczekiwanie na zapytania Baileys oraz limity czasu wysyłania i sygnalizowania obecności przez OpenClaw, a także potwierdzeń odczytu wiadomości przychodzących).
• Wysyłanie wiadomości wychodzących wymaga aktywnego nasłuchiwania WhatsApp dla konta docelowego; w przeciwnym razie wysyłanie natychmiast kończy się niepowodzeniem.
• Wiadomości wysyłane do grup dołączają natywne metadane wzmianek dla tokenów @+<digits> i @<digits> (w tekście i podpisach multimediów), gdy token odpowiada bieżącym metadanym uczestnika, również w grupach opartych na LID.
• Czaty statusowe i transmisyjne (@status, @broadcast) są ignorowane.
• Czaty bezpośrednie używają reguł sesji wiadomości prywatnych (session.dmScope; domyślna wartość main scala wiadomości prywatne z główną sesją agenta). Sesje grupowe są izolowane dla każdego JID (agent:<agentId>:whatsapp:group:<jid>).
• Kanały/biuletyny WhatsApp mogą być jawnymi celami wychodzącymi za pośrednictwem natywnego JID @newsletter, przy użyciu metadanych sesji kanału (agent:<agentId>:whatsapp:channel:<jid>) zamiast semantyki wiadomości prywatnych.
• Transport WhatsApp Web respektuje standardowe zmienne środowiskowe serwera proxy na hoście Gateway (HTTPS_PROXY, HTTP_PROXY, NO_PROXY oraz ich warianty pisane małymi literami). Preferuj konfigurację serwera proxy na poziomie hosta zamiast ustawień poszczególnych kanałów.
• Gdy messages.removeAckAfterReply jest włączone, OpenClaw usuwa reakcję potwierdzenia po dostarczeniu widocznej odpowiedzi.

Zadzwoń do bieżącego nadawcy za pomocą MeowCaller (funkcja eksperymentalna)

Plugin może udostępnić whatsapp_call w turach agenta pochodzących z WhatsApp. Używa MeowCaller do nawiązania połączenia głosowego WhatsApp z bieżącym autoryzowanym nadawcą i odtworzenia wiadomości TTS OpenClaw po odebraniu połączenia. Narzędzie nie ma parametru numeru docelowego, więc polecenie nie może przekierować połączenia. Domyślnie wyłączone.

{"channels": {"whatsapp": {  "actions": {    "calls": true  }}}}

git clone --branch feat/send-only-notify https://github.com/steipete/meowcaller.gitcd meowcallergit checkout 752050471fc2bf7a8cdfbf7dbd3cd4e865d85d3fmkdir -p "$HOME/.local/bin"go build -o "$HOME/.local/bin/meowcaller" ./cmd/meowcaller

state_dir="$HOME/.openclaw/credentials/whatsapp-calls/default"mkdir -p "$state_dir"chmod 700 "$state_dir"meowcaller pair --store "$state_dir/wa-voip.db"

Ograniczenia: wyłącznie wychodzące połączenia audio jeden-do-jednego, brak dowolnych numerów docelowych, brak współdzielonego uwierzytelniania z połączeniem czatu, brak połączeń do samego siebie w trybie numeru osobistego/czatu z samym sobą, syntetyzowany dźwięk ograniczony do 60 sekund, brak potwierdzenia słyszalności po stronie telefonu poza zakończeniem przez MeowCaller etapów odebrania, odtworzenia i rozłączenia oraz zatrzymanie procesu towarzyszącego przez OpenClaw po ograniczonym okresie 115–175 sekund (obejmującym fazy łączenia, odbierania, odtwarzania i zamykania MeowCaller).

Monity zatwierdzania

WhatsApp może wyświetlać monity zatwierdzania wykonania i pluginów jako reakcje 👍/👎, sterowane przez konfigurację przekazywania zatwierdzeń najwyższego poziomu:

{  approvals: {    exec: {      enabled: true,      mode: "session",    },    plugin: {      enabled: true,      mode: "targets",      targets: [{ channel: "whatsapp", to: "+15551234567" }],    },  },}

approvals.exec i approvals.plugin są niezależne; włączenie WhatsApp jako kanału jedynie łączy transport i niczego nie wysyła, chyba że odpowiednia rodzina zatwierdzeń jest włączona i kierowana do tego kanału. Tryb sesji dostarcza natywne zatwierdzenia za pomocą emoji wyłącznie dla zatwierdzeń pochodzących z WhatsApp. Tryb celów używa współdzielonego potoku przekazywania dla jawnych celów i nie tworzy osobnego rozsyłania wiadomości prywatnych do zatwierdzających.

Reakcje zatwierdzające WhatsApp wymagają jawnie określonych zatwierdzających w allowFrom (lub "*"). defaultTo ustawia zwykłe domyślne cele wiadomości, a nie listę zatwierdzających. Ręczne polecenia /approve nadal przechodzą standardową ścieżkę autoryzacji nadawcy WhatsApp przed rozstrzygnięciem zatwierdzenia.

Punkty zaczepienia pluginów i prywatność

Przychodzące wiadomości WhatsApp mogą zawierać treści osobiste, numery telefonów, identyfikatory grup, nazwy nadawców i pola korelacji sesji. WhatsApp nie rozgłasza przychodzących ładunków punktu zaczepienia message_received do pluginów, chyba że jawnie wyrazisz na to zgodę:

{  channels: {    whatsapp: {      pluginHooks: {        messageReceived: true,      },    },  },}

Ogranicz zgodę do jednego konta w channels.whatsapp.accounts.<id>.pluginHooks.messageReceived. Włączaj tę opcję tylko dla pluginów, którym ufasz w zakresie dostępu do treści i identyfikatorów przychodzących z WhatsApp.

Kontrola dostępu i aktywacja

Skonfigurowane powiązania ACP

WhatsApp obsługuje trwałe powiązania ACP za pomocą bindings[] najwyższego poziomu:

{  bindings: [    {      type: "acp",      agentId: "codex",      match: {        channel: "whatsapp",        accountId: "work",        peer: { kind: "direct", id: "+15555550123" },      },    },    {      type: "acp",      agentId: "codex",      match: {        channel: "whatsapp",        accountId: "work",        peer: { kind: "group", id: "120363424282127706@g.us" },      },    },  ],}

Czaty bezpośrednie są dopasowywane według numerów E.164, a grupy według identyfikatorów JID grup WhatsApp. Listy dozwolonych grup, zasady nadawców oraz warunki aktywacji przez wzmiankę lub polecenie są stosowane, zanim OpenClaw zapewni istnienie powiązanej sesji ACP. Dopasowane powiązanie przejmuje trasę — grupy rozgłoszeniowe nie rozsyłają tej tury do zwykłych sesji WhatsApp.

Zachowanie numeru osobistego i czatu z samym sobą

Gdy połączony własny numer znajduje się również w allowFrom, aktywują się zabezpieczenia czatu z samym sobą: potwierdzenia odczytu są pomijane dla tur takiego czatu, ignorowane jest automatyczne wyzwalanie przez JID wzmianki, które wysyłałoby powiadomienia do samego siebie, a odpowiedzi domyślnie otrzymują prefiks [{identity.name}] (lub [openclaw]), gdy messages.responsePrefix nie jest ustawione.

Normalizacja wiadomości i kontekst

[Replying to <sender> id:<stanzaId>]<quoted body or media placeholder>[/Replying]

{ channels: { whatsapp: { sendReadReceipts: false } } }

Dostarczanie, dzielenie na fragmenty i multimedia

Cytowanie odpowiedzi

channels.whatsapp.replyToMode steruje natywnym cytowaniem odpowiedzi (odpowiedzi wychodzące widocznie cytują wiadomość przychodzącą):

Ustawienie zastępcze dla konta: channels.whatsapp.accounts.<id>.replyToMode.

{ channels: { whatsapp: { replyToMode: "first" } } }

Poziom reakcji

channels.whatsapp.reactionLevel określa, jak szeroko agent używa reakcji emoji:

Ustawienie zastępcze dla konta: channels.whatsapp.accounts.<id>.reactionLevel.

{ channels: { whatsapp: { reactionLevel: "ack" } } }

Reakcje potwierdzające

channels.whatsapp.ackReaction wysyła natychmiastową reakcję po odebraniu wiadomości przychodzącej, zależnie od reactionLevel (pomijana przy "off"):

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

Uwagi: reakcja jest wysyłana natychmiast po zaakceptowaniu wiadomości przychodzącej (przed odpowiedzią); jeśli ackReaction jest obecne bez emoji, WhatsApp używa emoji tożsamości przypisanego agenta, a awaryjnie „👀” (pomiń ackReaction lub ustaw emoji: "", aby wyłączyć potwierdzenie); błędy są rejestrowane, ale nie blokują dostarczenia odpowiedzi; tryb grupowy mentions reaguje tylko na tury wyzwolone wzmianką, natomiast aktywacja grupy always pomija to sprawdzenie; WhatsApp używa wyłącznie channels.whatsapp.ackReaction (starsze messages.ackReaction nie ma tutaj zastosowania).

Reakcje stanu cyklu życia

Ustaw messages.statusReactions.enabled: true, aby WhatsApp podczas tury zastępował reakcję potwierdzającą zamiast pozostawiać statyczne emoji potwierdzenia odbioru, przechodząc kolejno przez stany takie jak oczekiwanie w kolejce, myślenie, aktywność narzędzi, Compaction, ukończenie i błąd:

{  messages: {    statusReactions: {      enabled: true,      emojis: {        deploy: "🛫",        build: "🏗️",        concierge: "💁",      },    },  },}

Uwagi: channels.whatsapp.ackReaction nadal określa dostępność dla wiadomości bezpośrednich i grup; stan oczekiwania w kolejce używa tego samego efektywnego emoji co zwykłe reakcje potwierdzające; WhatsApp udostępnia jedno miejsce na reakcję bota dla każdej wiadomości, dlatego aktualizacje cyklu życia zastępują bieżącą reakcję w miejscu; messages.removeAckAfterReply: true usuwa końcową reakcję stanu po skonfigurowanym czasie utrzymywania stanu ukończenia/błędu; kategorie emoji narzędzi obejmują tool, coding, web, deploy, build i concierge.

Wiele kont i dane uwierzytelniające

Narzędzia, działania i zapisy konfiguracji

• Obsługa narzędzi agenta obejmuje działanie reakcji WhatsApp (react).
• Bramki działań: channels.whatsapp.actions.reactions, channels.whatsapp.actions.polls (istniejące działania mają domyślnie wartość true), channels.whatsapp.actions.calls (domyślnie false; zobacz MeowCaller powyżej).
• Zapisy konfiguracji inicjowane przez kanał są domyślnie włączone; można je wyłączyć przez channels.whatsapp.configWrites: false.

Rozwiązywanie problemów

openclaw channels login --channel whatsappopenclaw channels status

{  web: {    whatsapp: {      keepAliveIntervalMs: 15000,      connectTimeoutMs: 60000,      defaultQueryTimeoutMs: 60000,    },  },}

openclaw channels status --probeopenclaw doctoropenclaw logs --followopenclaw gateway status

cp -a ~/.openclaw/credentials/whatsapp/<accountId> \  ~/.openclaw/credentials/whatsapp/<accountId>.bakopenclaw channels logout --channel whatsapp --account <accountId>openclaw channels login --channel whatsapp --account <accountId>

Monity systemowe

WhatsApp obsługuje monity systemowe w stylu Telegram dla grup i czatów bezpośrednich za pośrednictwem map groups i direct.

Rozstrzyganie dla wiadomości grupowych: najpierw wyznaczana jest obowiązująca mapa groups — jeśli konto w ogóle definiuje własny klucz groups, całkowicie zastępuje on główną mapę groups (bez głębokiego scalania). Następnie wyszukiwanie monitu odbywa się w tej jednej wynikowej mapie:

1. Monit właściwy dla grupy (groups["<groupId>"].systemPrompt): używany, gdy wpis grupy istnieje i jego klucz systemPrompt jest zdefiniowany. Pusty ciąg ("") wyłącza symbol wieloznaczny i nie stosuje żadnego monitu.
2. Monit grupowy z symbolem wieloznacznym (groups["*"].systemPrompt): używany, gdy nie ma wpisu dla konkretnej grupy lub gdy wpis istnieje bez klucza systemPrompt.

Rozstrzyganie dla wiadomości bezpośrednich przebiega według identycznego wzorca względem mapy direct i direct["*"].

Różnica względem Telegram: Telegram pomija główne groups dla każdego konta w konfiguracji wielokontowej (nawet dla kont bez własnego groups), aby uniemożliwić botowi odbieranie wiadomości z grup, do których nie należy. WhatsApp nie stosuje tego zabezpieczenia — główne groups/direct są dziedziczone przez każde konto bez własnego nadpisania, niezależnie od liczby kont. W wielokontowej konfiguracji WhatsApp zdefiniuj jawnie pełną mapę dla każdego konta, jeśli chcesz stosować monity właściwe dla poszczególnych kont.

Ważne działanie:

• channels.whatsapp.groups jest jednocześnie mapą konfiguracji poszczególnych grup oraz listą dozwolonych grup na poziomie czatu. Zarówno w zakresie głównym, jak i konta groups["*"] oznacza „wszystkie grupy są dopuszczone” w tym zakresie.
• Dodawaj systemPrompt z symbolem wieloznacznym tylko wtedy, gdy dany zakres ma już dopuszczać wszystkie grupy. Aby zachować dostępność tylko dla ustalonego zbioru identyfikatorów grup, powtórz monit w każdym jawnie dozwolonym wpisie zamiast używać groups["*"].
• Dopuszczenie grupy i autoryzacja nadawcy są oddzielnymi kontrolami. groups["*"] rozszerza zbiór grup przekazywanych do obsługi grupowej; nie autoryzuje wszystkich nadawców w tych grupach — nadal kontrolują to groupPolicy/groupAllowFrom.
• channels.whatsapp.direct nie wywołuje analogicznego skutku ubocznego dla wiadomości bezpośrednich: direct["*"] zapewnia jedynie konfigurację domyślną po wcześniejszym dopuszczeniu wiadomości bezpośredniej przez dmPolicy wraz z allowFrom lub regułami magazynu parowania.

Przykład:

{  channels: {    whatsapp: {      groups: {        // Używaj tylko wtedy, gdy wszystkie grupy mają być dopuszczone w zakresie głównym.        // Dotyczy wszystkich kont, które nie definiują własnej mapy grup.        "*": { systemPrompt: "Domyślny monit dla wszystkich grup." },      },      direct: {        // Dotyczy wszystkich kont, które nie definiują własnej mapy wiadomości bezpośrednich.        "*": { systemPrompt: "Domyślny monit dla wszystkich czatów bezpośrednich." },      },      accounts: {        work: {          groups: {            // To konto definiuje własne grupy, więc grupy główne zostają całkowicie            // zastąpione. Aby zachować symbol wieloznaczny, zdefiniuj tutaj jawnie także "*".            "120363406415684625@g.us": {              requireMention: false,              systemPrompt: "Skup się na zarządzaniu projektem.",            },            // Używaj tylko wtedy, gdy wszystkie grupy mają być dopuszczone na tym koncie.            "*": { systemPrompt: "Domyślny monit dla grup służbowych." },          },          direct: {            // To konto definiuje własną mapę wiadomości bezpośrednich, więc główne wpisy            // zostają całkowicie zastąpione. Aby zachować symbol wieloznaczny, zdefiniuj tutaj jawnie także "*".            "+15551234567": { systemPrompt: "Monit dla konkretnego służbowego czatu bezpośredniego." },            "*": { systemPrompt: "Domyślny monit dla służbowych czatów bezpośrednich." },          },        },      },    },  },}

Odnośniki do dokumentacji konfiguracji

Główne źródło: Dokumentacja konfiguracji — WhatsApp

Powiązane

• Parowanie
• Grupy
• Bezpieczeństwo
• Trasowanie kanałów
• Trasowanie wielu agentów
• Rozwiązywanie problemów