WhatsApp

​

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.

openclaw plugins install clawhub:@openclaw/whatsapp

​

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>

​

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

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

git clone --branch feat/send-only-notify https://github.com/steipete/meowcaller.git
cd meowcaller
git checkout 752050471fc2bf7a8cdfbf7dbd3cd4e865d85d3f
mkdir -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"

• 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

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

​

Hooki Pluginu i prywatność

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

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

​

Kontrola dostępu i aktywacja

​

Skonfigurowane powiązania ACP

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

• 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

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

​

Poziom reakcji

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

​

Reakcje potwierdzenia

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

• 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

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

• 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 whatsapp
openclaw channels status

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

openclaw channels status --probe
openclaw doctor
openclaw logs --follow
openclaw gateway status

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

​

Prompty systemowe

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.

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.

• 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.

{
  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

• Dokumentacja konfiguracji - 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