WhatsApp

Status: gotowe do produkcji przez WhatsApp Web (Baileys). Gateway zarządza połączonymi sesjami.

Instalacja (na żądanie)

• Onboarding (openclaw onboard) oraz openclaw channels add --channel whatsapp proszą o instalację Pluginu WhatsApp przy pierwszym wyborze.
• openclaw channels login --channel whatsapp także oferuje przepływ instalacji, gdy Plugin nie jest jeszcze obecny.
• Kanał deweloperski + checkout z git: domyślnie używa lokalnej ścieżki Pluginu.
• Stable/Beta: najpierw instaluje oficjalny Plugin @openclaw/whatsapp z ClawHub, z npm jako rozwiązaniem awaryjnym.
• Runtime WhatsApp jest dystrybuowany poza głównym pakietem npm OpenClaw, aby zależności runtime specyficzne dla WhatsApp pozostały w zewnętrznym Pluginie.

Ręczna instalacja pozostaje dostępna:

openclaw plugins install clawhub:@openclaw/whatsapp

Używaj samego pakietu npm (@openclaw/whatsapp) tylko wtedy, gdy potrzebujesz awaryjnego użycia 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>

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

Plugin WhatsApp może udostępniać whatsapp_call w turach agenta pochodzących z WhatsApp. Narzędzie używa MeowCaller, aby wykonać połączenie głosowe WhatsApp do bieżącego autoryzowanego nadawcy i odtworzyć komunikat OpenClaw TTS po odebraniu. Narzędzie nie przyjmuje numeru docelowego, więc prompt nie może przekierować połączenia do strony trzeciej. Ta eksperymentalna funkcja jest domyślnie wyłączona.

{"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"

Obecne ograniczenia:

• tylko 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ą
• zsyntetyzowany dźwięk jest ograniczony do 60 sekund
• brak potwierdzenia słyszalności po stronie telefonu poza zakończeniem odebrania/odtwarzania/rozłączenia przez MeowCaller
• OpenClaw zatrzymuje proces towarzyszący po ograniczonym oknie 115–175 sekund, obejmującym fazy połączenia, odebrania, odtwarzania i zamknięcia MeowCaller

Wzorce wdrożenia

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

Model runtime

• Gateway zarządza gniazdem WhatsApp i pętlą ponownego łączenia.
• Watchdog ponownego łączenia używa aktywności transportu WhatsApp Web, a nie tylko wolumenu przychodzących wiadomości aplikacji, więc cicha sesja połączonego urządzenia nie jest restartowana wyłącznie dlatego, że nikt ostatnio nie wysłał wiadomości. Dłuższy limit ciszy aplikacji nadal wymusza ponowne połączenie, jeśli ramki transportu dalej przychodzą, ale w oknie watchdoga nie są obsługiwane żadne wiadomości aplikacji; po przejściowym ponownym połączeniu dla ostatnio aktywnej sesji ten test ciszy aplikacji używa normalnego timeoutu wiadomości dla pierwszego okna odzyskiwania.
• Czasy gniazda Baileys są jawne pod web.whatsapp.*: keepAliveIntervalMs kontroluje pingi aplikacji WhatsApp Web, connectTimeoutMs kontroluje timeout początkowego uzgadniania połączenia, a defaultQueryTimeoutMs kontroluje oczekiwania zapytań Baileys oraz lokalne limity operacji wysyłki wychodzącej/obecności i potwierdzeń odczytu przychodzącego w OpenClaw.
• Wysyłki wychodzące wymagają aktywnego listenera WhatsApp dla konta docelowego.
• Wysyłki grupowe dołączają natywne metadane wzmianek dla tokenów @+<digits> i @<digits> w tekście i podpisach mediów, gdy token pasuje do bieżących metadanych uczestnika WhatsApp, w tym grup opartych na LID.
• Czaty statusowe i broadcast są ignorowane (@status, @broadcast).
• Watchdog ponownego łączenia podąża za aktywnością transportu WhatsApp Web, a nie tylko wolumenem przychodzących wiadomości aplikacji: ciche sesje połączonych urządzeń pozostają aktywne, dopóki ramki transportu nadal przychodzą, ale zatrzymanie transportu wymusza ponowne połączenie dużo wcześniej niż późniejsza ścieżka zdalnego rozłączenia.
• 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>).
• Kanały/Newslettery WhatsApp mogą być jawnymi celami wychodzącymi z natywnym JID @newsletter. Wysyłki wychodzące do newsletterów używają metadanych sesji kanału (agent:<agentId>:whatsapp:channel:<jid>) zamiast semantyki sesji DM.
• Transport WhatsApp Web respektuje standardowe zmienne środowiskowe proxy na hoście gateway (HTTPS_PROXY, HTTP_PROXY, NO_PROXY / warianty małymi literami). Preferuj konfigurację proxy na poziomie hosta zamiast ustawień proxy specyficznych dla kanału WhatsApp.
• Gdy messages.removeAckAfterReply jest włączone, OpenClaw czyści reakcję potwierdzenia WhatsApp po dostarczeniu widocznej odpowiedzi.

Prompty zatwierdzania

WhatsApp może renderować prompty zatwierdzania exec i Pluginu z reakcjami 👍 / 👎. Dostarczaniem steruje najwyższego poziomu konfiguracja przekazywania zatwierdzeń:

{  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 tylko łączy transport; nie wysyła promptów zatwierdzania, chyba że odpowiednia rodzina zatwierdzeń jest włączona i kieruje do WhatsApp. Tryb sesji dostarcza natywne zatwierdzenia emoji tylko dla zatwierdzeń, które pochodzą z WhatsApp. Tryb celu używa współdzielonego potoku przekazywania dla jawnych celów WhatsApp i nie tworzy osobnego rozsyłania do DM zatwierdzających.

Reakcje zatwierdzania WhatsApp wymagają jawnych zatwierdzających WhatsApp z allowFrom lub "*". defaultTo kontroluje zwykłe domyślne cele wiadomości; nie jest zatwierdzającym zatwierdzeń. Ręczne polecenia /approve nadal przechodzą przez normalną ścieżkę autoryzacji nadawcy WhatsApp przed rozstrzygnięciem zatwierdzenia.

Hooki Pluginu i prywatność

Wiadomości przychodzące WhatsApp mogą zawierać osobistą treść wiadomości, numery telefonów, identyfikatory grup, nazwy nadawców i pola korelacji sesji. Z tego powodu WhatsApp nie rozsyła przychodzących ładunków haka message_received do pluginów, chyba że jawnie wyrazisz na to zgodę:

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

Możesz ograniczyć zgodę do jednego konta:

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

Włączaj to tylko dla pluginów, którym ufasz w zakresie odbierania przychodzącej treści wiadomości WhatsApp i identyfikatorów.

Kontrola dostępu i aktywacja

Skonfigurowane powiązania ACP

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

{  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 pasują do numerów E.164, takich jak +15555550123.
• Grupy pasują do JID grup WhatsApp, takich jak 120363424282127706@g.us.
• Listy dozwolonych grup, polityka nadawców oraz bramkowanie wzmianką lub aktywacją działają, zanim OpenClaw upewni się, że skonfigurowana sesja ACP istnieje.
• Dopasowane skonfigurowane powiązanie ACP przejmuje trasę. Grupy rozgłoszeniowe WhatsApp nie rozsyłają tej tury do zwykłych sesji WhatsApp.

Zachowanie numeru osobistego i czatu z samym sobą

Gdy połączony własny numer jest także obecny w allowFrom, aktywują się zabezpieczenia czatu WhatsApp z samym sobą:

• pomijanie potwierdzeń odczytu dla tur czatu z samym sobą
• ignorowanie automatycznego wyzwalania przez JID wzmianki, które w przeciwnym razie powiadomiłoby ciebie samego
• jeśli messages.responsePrefix nie jest ustawione, odpowiedzi w czacie z samym sobą domyślnie używają [{identity.name}] albo [openclaw]

Normalizacja wiadomości i kontekst

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

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

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

Dostarczanie, dzielenie na fragmenty i media

Cytowanie odpowiedzi

WhatsApp obsługuje natywne cytowanie odpowiedzi, w którym odpowiedzi wychodzące widocznie cytują wiadomość przychodzącą. Kontroluj to za pomocą channels.whatsapp.replyToMode.

Domyślnie: "off". Nadpisania dla kont używają channels.whatsapp.accounts.<id>.replyToMode.

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

Poziom reakcji

channels.whatsapp.reactionLevel kontroluje, jak szeroko agent używa reakcji emoji w WhatsApp:

Domyślnie: "minimal".

Nadpisania dla kont używają channels.whatsapp.accounts.<id>.reactionLevel.

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

Reakcje potwierdzenia

WhatsApp obsługuje natychmiastowe reakcje potwierdzenia przy odebraniu wiadomości przychodzącej przez channels.whatsapp.ackReaction. Reakcje potwierdzenia są bramkowane przez reactionLevel — są tłumione, gdy reactionLevel ma wartość "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ą)
• jeśli ackReaction występuje bez emoji, WhatsApp używa emoji tożsamości kierowanego agenta, z wycofaniem do "👀"; pomiń ackReaction albo ustaw emoji: "", aby nie wysyłać reakcji potwierdzenia
• błędy są logowane, ale nie blokują normalnego dostarczenia odpowiedzi
• tryb grupy mentions reaguje na tury wyzwolone wzmianką; aktywacja grupy always działa jako obejście tego sprawdzenia
• WhatsApp używa channels.whatsapp.ackReaction (starsze messages.ackReaction nie jest tutaj używane)

Reakcje statusu cyklu życia

Ustaw messages.statusReactions.enabled: true, aby WhatsApp zastępował reakcję potwierdzenia podczas tury zamiast pozostawiać statyczne emoji potwierdzenia odbioru. Gdy ta opcja jest włączona, OpenClaw używa tego samego miejsca reakcji na wiadomość przychodzącą dla stanów cyklu życia, takich jak w kolejce, myślenie, aktywność narzędzi, Compaction, gotowe i błąd.

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

Uwagi dotyczące zachowania:

• channels.whatsapp.ackReaction nadal kontroluje, czy reakcje statusu kwalifikują się dla wiadomości bezpośrednich i grup.
• Reakcja statusu w kolejce używa tego samego efektywnego emoji potwierdzenia co zwykłe reakcje potwierdzenia.
• WhatsApp ma jedno miejsce reakcji bota na wiadomość, więc aktualizacje cyklu życia zastępują bieżącą reakcję w miejscu.
• messages.removeAckAfterReply: true czyści końcową reakcję statusu po skonfigurowanym czasie podtrzymania stanu gotowe/błąd.
• Kategorie emoji narzędzi obejmują tool, coding, web, deploy, build i concierge.

Wiele kont i poświadczenia

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

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>

Prompty systemowe

WhatsApp obsługuje prompty systemowe w stylu Telegram dla grup i czatów bezpośrednich przez mapy groups i direct.

Hierarchia rozstrzygania dla wiadomości grupowych:

Efektywna mapa groups jest ustalana najpierw: jeśli konto definiuje własne groups, w pełni zastępuje główną mapę groups (bez głębokiego scalania). Wyszukiwanie promptu działa potem na wynikowej pojedynczej mapie:

1. Prompt systemowy specyficzny dla grupy (groups["<groupId>"].systemPrompt): używany, gdy konkretny wpis grupy istnieje w mapie i jego klucz systemPrompt jest zdefiniowany. Jeśli systemPrompt jest pustym ciągiem (""), wildcard jest tłumiony i żaden prompt systemowy nie jest stosowany.
2. Prompt systemowy wildcard grupy (groups["*"].systemPrompt): używany, gdy konkretny wpis grupy jest całkowicie nieobecny w mapie albo gdy istnieje, ale nie definiuje klucza systemPrompt.

Hierarchia rozstrzygania dla wiadomości bezpośrednich:

Efektywna mapa direct jest ustalana najpierw: jeśli konto definiuje własne direct, w pełni zastępuje główną mapę direct (bez głębokiego scalania). Wyszukiwanie promptu działa potem na wynikowej pojedynczej mapie:

1. Prompt systemowy specyficzny dla czatu bezpośredniego (direct["<peerId>"].systemPrompt): używany, gdy konkretny wpis rozmówcy istnieje w mapie i jego klucz systemPrompt jest zdefiniowany. Jeśli systemPrompt jest pustym ciągiem (""), wildcard jest tłumiony i żaden prompt systemowy nie jest stosowany.
2. Prompt systemowy wildcard czatu bezpośredniego (direct["*"].systemPrompt): używany, gdy konkretny wpis rozmówcy jest całkowicie nieobecny w mapie albo gdy istnieje, ale nie definiuje klucza systemPrompt.

Różnica względem zachowania Telegram z wieloma kontami: W Telegram główne groups jest celowo tłumione dla wszystkich kont w konfiguracji wielokontowej — nawet kont, które nie definiują własnego groups — aby zapobiec odbieraniu przez bota wiadomości grupowych z grup, do których nie należy. WhatsApp nie stosuje tej ochrony: główne groups i główne direct są zawsze dziedziczone przez konta, które nie definiują nadpisania na poziomie konta, niezależnie od liczby skonfigurowanych kont. W konfiguracji WhatsApp z wieloma kontami, jeśli chcesz promptów grupowych lub bezpośrednich per konto, zdefiniuj pełną mapę jawnie pod każdym kontem zamiast polegać na domyślnych ustawieniach poziomu głównego.

Ważne zachowanie:

• channels.whatsapp.groups jest zarówno mapą konfiguracji per grupa, jak i listą dozwolonych grup na poziomie czatu. W zakresie głównym lub konta groups["*"] oznacza „wszystkie grupy są dopuszczone” dla tego zakresu.
• Dodawaj wildcard grupy systemPrompt tylko wtedy, gdy już chcesz, aby ten zakres dopuszczał wszystkie grupy. Jeśli nadal chcesz, aby kwalifikował się tylko stały zestaw identyfikatorów grup, nie używaj groups["*"] jako domyślnego promptu. Zamiast tego powtórz prompt przy każdym jawnie dozwolonym wpisie grupy.
• Dopuszczenie grupy i autoryzacja nadawcy są osobnymi sprawdzeniami. groups["*"] poszerza zestaw grup, które mogą dotrzeć do obsługi grup, ale samo w sobie nie autoryzuje każdego nadawcy w tych grupach. Dostęp nadawcy jest nadal kontrolowany oddzielnie przez channels.whatsapp.groupPolicy i channels.whatsapp.groupAllowFrom.
• channels.whatsapp.direct nie ma tego samego efektu ubocznego dla DM. direct["*"] zapewnia tylko domyślną konfigurację czatu bezpośredniego po tym, jak DM zostanie już dopuszczony przez dmPolicy oraz allowFrom albo reguły magazynu parowania.

Przykład:

{  channels: {    whatsapp: {      groups: {        // Use only if all groups should be admitted at the root scope.        // Applies to all accounts that do not define their own groups map.        "*": { systemPrompt: "Default prompt for all groups." },      },      direct: {        // Applies to all accounts that do not define their own direct map.        "*": { systemPrompt: "Default prompt for all direct chats." },      },      accounts: {        work: {          groups: {            // This account defines its own groups, so root groups are fully            // replaced. To keep a wildcard, define "*" explicitly here too.            "120363406415684625@g.us": {              requireMention: false,              systemPrompt: "Focus on project management.",            },            // Use only if all groups should be admitted in this account.            "*": { systemPrompt: "Default prompt for work groups." },          },          direct: {            // This account defines its own direct map, so root direct entries are            // fully replaced. To keep a wildcard, define "*" explicitly here too.            "+15551234567": { systemPrompt: "Prompt for a specific work direct chat." },            "*": { systemPrompt: "Default prompt for work direct chats." },          },        },      },    },  },}

Wskaźniki dokumentacji konfiguracji

Podstawowa dokumentacja:

• Dokumentacja konfiguracji - WhatsApp

Najważniejsze pola WhatsApp:

• 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.*, web.whatsapp.*
• zachowanie sesji: session.dmScope, historyLimit, dmHistoryLimit, dms.<id>.historyLimit
• prompty: groups.<id>.systemPrompt, groups["*"].systemPrompt, direct.<id>.systemPrompt, direct["*"].systemPrompt

Powiązane

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