WhatsApp

Stan: 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 zainstalowanie 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 git: domyślnie używa lokalnej ścieżki Pluginu.
• Stable/Beta: używa pakietu npm @openclaw/whatsapp z bieżącego oficjalnego tagu wydania.

Instalacja ręczna pozostaje dostępna:

openclaw plugins install @openclaw/whatsapp

Użyj samej nazwy pakietu, aby śledzić bieżący oficjalny tag wydania. Przypnij dokładną wersję tylko wtedy, gdy potrzebujesz powtarzalnej instalacji.

W systemie Windows Plugin WhatsApp wymaga Git w PATH podczas instalacji npm, ponieważ jedna z jego zależności Baileys/libsignal jest pobierana z adresu URL git. Zainstaluj Git for Windows, następnie uruchom ponownie powłokę i ponów instalację:

winget install --id Git.Git -e

Portable Git także działa, jeśli jego katalog bin znajduje się w PATH.

# 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-auth
openclaw channels login --channel whatsapp --account work

openclaw gateway

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>

# Wzorce wdrożenia

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

# Model działania

• 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 aplikacyjnych, 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 aplikacyjnej nadal wymusza ponowne połączenie, jeśli ramki transportowe nadal przychodzą, ale żadne wiadomości aplikacyjne nie są obsługiwane przez czas okna watchdog; po przejściowym ponownym połączeniu dla niedawno aktywnej sesji ten test ciszy aplikacyjnej używa normalnego limitu czasu wiadomości dla pierwszego okna odzyskiwania.
• Czasy gniazda Baileys są jawne w web.whatsapp.*: keepAliveIntervalMs kontroluje pingi aplikacyjne WhatsApp Web, connectTimeoutMs kontroluje limit czasu otwierającego uzgadniania, a defaultQueryTimeoutMs kontroluje limity czasu zapytań Baileys.
• Wysyłanie wychodzące wymaga aktywnego nasłuchiwacza WhatsApp dla konta docelowego.
• Wysyłki grupowe dołączają natywne metadane wzmianek dla tokenów @+<digits> i @<digits> w tekście oraz podpisach mediów, gdy token pasuje do bieżących metadanych uczestników WhatsApp, w tym grup opartych na LID.
• Czaty statusowe i broadcast są ignorowane (@status, @broadcast).
• Watchdog ponownego łączenia śledzi aktywność transportu WhatsApp Web, a nie tylko wolumen przychodzących wiadomości aplikacyjnych: ciche sesje połączonego urządzenia pozostają aktywne, gdy ramki transportowe nadal płyną, ale zastój 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>).
• WhatsApp Channels/Newsletters mogą być jawnymi celami wychodzącymi ze swoim natywnym JID @newsletter. Wysyłki wychodzące do newslettera używają metadanych sesji kanału (agent:<agentId>:whatsapp:channel:<jid>), a nie semantyki sesji DM.
• Transport WhatsApp Web honoruje 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 WhatsApp specyficznych dla kanału.
• Gdy messages.removeAckAfterReply jest włączone, OpenClaw czyści reakcję potwierdzenia WhatsApp po dostarczeniu widocznej odpowiedzi.

# 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 rozgłasza przychodzących ładunków hooka message_received do Pluginów, chyba że jawnie to włączysz:

{
  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 otrzymywania treści i identyfikatorów przychodzących wiadomości WhatsApp.

# Kontrola dostępu i aktywacja

# Zachowanie numeru osobistego i czatu z samym sobą

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

• pomijanie potwierdzeń odczytu dla tur czatu z samym sobą
• ignorowanie zachowania automatycznego wyzwalania przez 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 mają postać [{identity.name}] lub [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 multimedia

# Cytowanie odpowiedzi

WhatsApp obsługuje natywne cytowanie odpowiedzi, w którym odpowiedzi wychodzące widocznie cytują wiadomość przychodzącą. Steruj tym 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 steruje tym, jak szeroko agent używa reakcji emoji na WhatsApp:

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ą blokowane, 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ą)
• niepowodzenia są logowane, ale nie blokują normalnego dostarczania odpowiedzi
• tryb grupy mentions reaguje w turach wyzwolonych 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)

# Wiele kont i dane uwierzytelniające

# Narzędzia, akcje i zapisy konfiguracji

• Obsługa narzędzi agenta obejmuje akcję reakcji WhatsApp (react).
• Bramy 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 whatsapp
openclaw channels status

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

openclaw doctor
openclaw logs --follow

# 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 konkretnej grupy (groups["<groupId>"].systemPrompt): używany, gdy wpis konkretnej grupy istnieje w mapie i jego klucz systemPrompt jest zdefiniowany. Jeśli systemPrompt jest pustym ciągiem (""), wieloznacznik jest blokowany i żaden prompt systemowy nie jest stosowany.
2. Prompt systemowy wieloznacznika grupy (groups["*"].systemPrompt): używany, gdy wpis konkretnej 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 peera istnieje w mapie i jego klucz systemPrompt jest zdefiniowany. Jeśli systemPrompt jest pustym ciągiem (""), symbol wieloznaczny jest pomijany i żaden prompt systemowy nie jest stosowany.
2. Prompt systemowy z symbolem wieloznacznym dla czatu bezpośredniego (direct["*"].systemPrompt): używany, gdy konkretny wpis peera całkowicie nie występuje w mapie albo gdy istnieje, ale nie definiuje klucza systemPrompt.

Różnica względem zachowania wielu kont Telegram: W Telegram główne groups jest celowo pomijane dla wszystkich kont w konfiguracji wielokontowej — nawet dla kont, które nie definiują własnych groups — aby zapobiec odbieraniu przez bota wiadomości grupowych z grup, do których nie należy. WhatsApp nie stosuje tego zabezpieczenia: 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 wielokontowej konfiguracji WhatsApp, jeśli chcesz mieć prompty grupowe lub bezpośrednie zależne od konta, zdefiniuj pełną mapę jawnie pod każdym kontem zamiast polegać na domyślnych wartościach z poziomu głównego.

Ważne zachowanie:

• channels.whatsapp.groups jest jednocześnie mapą konfiguracji dla każdej grupy oraz listą dozwolonych grup na poziomie czatu. Na poziomie głównym albo konta groups["*"] oznacza „wszystkie grupy są dopuszczone” dla tego zakresu.
• Dodawaj grupowy systemPrompt z symbolem wieloznacznym tylko wtedy, gdy już chcesz, aby dany 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 w każdym jawnie dozwolonym wpisie grupy.
• Dopuszczanie grup i autoryzacja nadawców to osobne kontrole. groups["*"] poszerza zestaw grup, które mogą trafić do obsługi grupowej, ale samo w sobie nie autoryzuje każdego nadawcy w tych grupach. Dostęp nadawców nadal jest kontrolowany osobno przez channels.whatsapp.groupPolicy i channels.whatsapp.groupAllowFrom.
• channels.whatsapp.direct nie ma takiego samego efektu ubocznego dla DM. direct["*"] dostarcza tylko domyślną konfigurację czatu bezpośredniego po tym, jak DM został już dopuszczony przez dmPolicy oraz reguły allowFrom lub 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.
            "[email protected]": {
              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

Główna 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 wieloagentowy
• Rozwiązywanie problemów