WhatsApp

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

Instalacja

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

openclaw plugins install clawhub:@openclaw/whatsapp

Podstawowego pakietu npm (@openclaw/whatsapp) należy używać tylko jako rozwiązania rezerwowego dla rejestru; dokładną wersję należy przypinać wyłącznie w celu zapewnienia 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 niezależnie śledzi dwa sygnały: aktywność nieprzetworzonego transportu WhatsApp Web oraz aktywność wiadomości aplikacji. Cicha, lecz połączona sesja nie jest uruchamiana ponownie tylko dlatego, że ostatnio nie nadeszła żadna wiadomość; ponowne połączenie jest wymuszane wyłącznie wtedy, gdy ramki transportowe przestaną napływać przez stały wewnętrzny okres (niekonfigurowalny przez użytkownika) albo wiadomości aplikacji nie pojawią się przez czas przekraczający 4-krotność normalnego limitu czasu wiadomości. Bezpośrednio po ponownym połączeniu niedawno aktywnej sesji pierwszy okres używa krótszego, normalnego limitu czasu wiadomości zamiast okresu 4-krotnie dłuższego. OpenClaw może automatycznie odpowiadać na wiadomości offline, które Baileys dostarczy na początku tego ponownego połączenia, w granicach czasu przechowywania identyfikatorów wiadomości do deduplikacji; podczas początkowego uruchomienia zachowywane jest krótkie zabezpieczenie 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), defaultQueryTimeoutMs (oczekiwanie na zapytania Baileys oraz limity czasu wysyłania wychodzącego, obecności i przychodzących potwierdzeń odczytu w OpenClaw).
• 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 zawierają natywne metadane wzmianek dla tokenów @+<digits> i @<digits> (w tekście i podpisach multimediów), jeśli token odpowiada bieżącym metadanym uczestnika, również w grupach opartych na LID.
• Czaty statusowe i transmisyjne (@status, @broadcast) są ignorowane.
• Czaty bezpośrednie korzystają z reguł sesji wiadomości prywatnych (session.dmScope; domyślna wartość main łączy wiadomości prywatne w głównej sesji agenta). Sesje grupowe są izolowane dla każdego JID (agent:<agentId>:whatsapp:group:<jid>).
• Kanały/biuletyny WhatsApp mogą być jawnymi celami wiadomości wychodzących za pośrednictwem ich natywnego JID @newsletter, z użyciem 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, również warianty pisane małymi literami). Zaleca się konfigurację serwera proxy na poziomie hosta zamiast ustawień poszczególnych kanałów.
• Gdy opcja messages.removeAckAfterReply jest włączona, OpenClaw usuwa reakcję potwierdzenia po dostarczeniu widocznej odpowiedzi.

Nawiązywanie połączenia z bieżącym nadawcą za pomocą MeowCaller (eksperymentalne)

Plugin może udostępniać whatsapp_call podczas tur agenta pochodzących z WhatsApp. Używa narzędzia MeowCaller do nawiązania połączenia głosowego WhatsApp z bieżącym upoważnionym nadawcą i odtworzenia komunikatu TTS OpenClaw po odebraniu połączenia. Narzędzie nie ma parametru numeru docelowego, dlatego monit nie może przekierować połączenia. 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"

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

Monity o zatwierdzenie

WhatsApp może wyświetlać monity o zatwierdzenie wykonywania poleceń 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 nie wysyła niczego, jeśli odpowiednia rodzina zatwierdzeń nie jest włączona i kierowana do tego kanału. Tryb sesji dostarcza natywne zatwierdzenia za pomocą emoji wyłącznie w przypadku zatwierdzeń pochodzących z WhatsApp. Tryb celu używa współdzielonego potoku przekazywania dla jawnie określonych celów i nie tworzy osobnego rozsyłania wiadomości prywatnych do zatwierdzających.

Reakcje zatwierdzające WhatsApp wymagają jawnego określenia zatwierdzających w allowFrom (lub "*"). defaultTo określa 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.

Hooki 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 rozsyła do pluginów przychodzących danych hooka message_received, chyba że zostanie to włączone:

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

Zgodę można ograniczyć do jednego konta w channels.whatsapp.accounts.<id>.pluginHooks.messageReceived. Funkcję należy włączać wyłącznie dla pluginów, którym ufa się w zakresie dostępu do przychodzących treści i identyfikatorów WhatsApp.

Kontrola dostępu i aktywacja

Skonfigurowane powiązania ACP

WhatsApp obsługuje trwałe powiązania ACP za pomocą elementu 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 są dopasowywane do numerów E.164, a grupy do 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 ze sobą

Gdy powiązany własny numer znajduje się również w allowFrom, aktywują się zabezpieczenia czatu ze sobą: potwierdzenia odczytu są pomijane dla tur czatu ze sobą, ignorowane jest automatyczne wyzwalanie przez JID wzmianki, które powodowałoby wysłanie powiadomienia do siebie, a odpowiedzi domyślnie trafiają do [{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 zawierają widoczny cytat wiadomości przychodzącej):

Nadpisanie dla konta: channels.whatsapp.accounts.<id>.replyToMode.

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

Poziom reakcji

channels.whatsapp.reactionLevel określa zakres używania przez agenta reakcji emoji:

Nadpisanie 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, z uwzględnieniem warunku reactionLevel (pomijana, gdy "off"):

{  channels: {    whatsapp: {      ackReaction: {        emoji: "👀",        direct: true,        group: "mentions", // zawsze | wzmianki | nigdy      },    },  },}

Uwagi: 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 w razie jego braku „👀” (należy pominąć ackReaction lub ustawić emoji: "", aby wyłączyć potwierdzenie); błędy są rejestrowane, ale nie blokują dostarczania 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

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

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

Uwagi: channels.whatsapp.ackReaction nadal steruje kwalifikowaniem wiadomości bezpośrednich i grup; stan oczekiwania w kolejce używa tego samego obowiązującego emoji co zwykłe reakcje potwierdzające; WhatsApp ma jedno miejsce na reakcję bota na wiadomość, dlatego aktualizacje cyklu życia zastępują bieżącą reakcję w miejscu; messages.removeAckAfterReply: true usuwa końcową reakcję stanu po skonfigurowanym czasie wyświetlania 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, patrz MeowCaller powyżej).
• Zapisy konfiguracji inicjowane przez kanał są domyślnie włączone; można je wyłączyć za pomocą 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 określana 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 pojedynczej 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 ("") pomija symbol wieloznaczny i nie stosuje żadnego monitu.
2. Monit grupowy z symbolem wieloznacznym (groups["*"].systemPrompt): używany, gdy wpis właściwy dla danej grupy nie istnieje lub istnieje bez klucza systemPrompt.

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

Różnica względem Telegram: Telegram pomija główny groups dla każdego konta w konfiguracji wielokontowej (nawet dla kont bez własnego groups), aby bot nie odbierał 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 należy jawnie zdefiniować pełną mapę dla każdego konta, jeśli monity mają być właściwe dla poszczególnych kont.

Ważne zachowanie:

• channels.whatsapp.groups jest zarówno mapą konfiguracji poszczególnych grup, jak i listą grup dozwolonych na poziomie czatu. Zarówno w zakresie głównym, jak i konta, groups["*"] oznacza „wszystkie grupy są dozwolone” w tym zakresie.
• Symbol wieloznaczny systemPrompt należy dodawać tylko wtedy, gdy dany zakres ma już dopuszczać wszystkie grupy. Aby kwalifikował się wyłącznie stały zestaw identyfikatorów grup, powtórz monit w każdym jawnie dozwolonym wpisie zamiast używać groups["*"].
• Dopuszczanie grup i autoryzacja nadawców są oddzielnymi kontrolami. groups["*"] rozszerza zakres grup przekazywanych do obsługi grupowej; nie autoryzuje wszystkich nadawców w tych grupach — pozostaje to pod kontrolą groupPolicy/groupAllowFrom.
• channels.whatsapp.direct nie ma równoważnego efektu ubocznego dla wiadomości bezpośrednich: direct["*"] dostarcza jedynie konfigurację domyślną po uprzednim 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, jawnie zdefiniuj tutaj również "*".            "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            // wiadomości bezpośrednich zostają całkowicie zastąpione. Aby zachować symbol            // wieloznaczny, jawnie zdefiniuj tutaj również "*".            "+15551234567": { systemPrompt: "Monit dla określonego służbowego czatu bezpośredniego." },            "*": { systemPrompt: "Domyślny monit dla służbowych czatów bezpośrednich." },          },        },      },    },  },}

Odnośniki do dokumentacji konfiguracji

Główna dokumentacja: Dokumentacja konfiguracji — WhatsApp

Powiązane

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