​

WhatsApp (kanał webowy)

​

Instalacja (na żądanie)

• Onboarding (openclaw onboard) i openclaw channels add --channel whatsapp przy pierwszym wyborze tego kanału proponują instalację pluginu WhatsApp.
• openclaw channels login --channel whatsapp również oferuje przepływ instalacji, gdy plugin nie jest jeszcze obecny.
• Kanał developerski + checkout z gita: domyślnie używa lokalnej ścieżki pluginu.
• Stable/Beta: domyślnie używa pakietu npm @openclaw/whatsapp.

openclaw plugins install @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 gateway

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>

​

Wzorce wdrożenia

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

​

Model środowiska uruchomieniowego

• Gateway jest właścicielem gniazda WhatsApp i pętli ponownego połączenia.
• Wysyłanie wychodzące wymaga aktywnego listenera WhatsApp dla konta docelowego.
• Czaty statusów i broadcastów są ignorowane (@status, @broadcast).
• Czaty bezpośrednie używają reguł sesji DM (session.dmScope; domyślnie main zwija DM do głównej sesji agenta).
• Sesje grupowe są izolowane (agent:<agentId>:whatsapp:group:<jid>).
• 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 WhatsApp specyficznych dla kanału.

​

Kontrola dostępu i aktywacja

​

Zachowanie numeru prywatnego i czatu z samym sobą

• pomijanie potwierdzeń odczytu dla tur czatu z samym sobą
• ignorowanie zachowania automatycznego wyzwalania mention-JID, które w przeciwnym razie wywołałoby ping do samego siebie
• jeśli messages.responsePrefix nie jest ustawione, odpowiedzi w czacie z samym sobą domyślnie używają [{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

​

Poziom reakcji

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

​

Reakcje potwierdzające

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

• wysyłane natychmiast po zaakceptowaniu wiadomości przychodzącej (przed odpowiedzią)
• błędy są logowane, ale nie blokują normalnego dostarczenia odpowiedzi
• tryb grupowy mentions reaguje przy turach wyzwolonych wzmianką; aktywacja grupy always działa jako obejście tego sprawdzenia
• WhatsApp używa channels.whatsapp.ackReaction (starsze messages.ackReaction nie jest tu używane)

​

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 z kanału są domyślnie włączone (wyłącz przez channels.whatsapp.configWrites=false).

​

Rozwiązywanie problemów

openclaw channels login --channel whatsapp
openclaw channels status

openclaw doctor
openclaw logs --follow

​

Prompty systemowe

1. Prompt systemowy specyficzny dla grupy (groups["<groupId>"].systemPrompt): używany, jeśli wpis dla konkretnej grupy definiuje systemPrompt.
2. Prompt systemowy z wildcardem grupy (groups["*"].systemPrompt): używany, gdy wpis dla konkretnej grupy nie istnieje lub nie definiuje systemPrompt.

1. Prompt systemowy specyficzny dla czatu bezpośredniego (direct["<peerId>"].systemPrompt): używany, jeśli wpis dla konkretnego peer definiuje systemPrompt.
2. Prompt systemowy z wildcardem czatu bezpośredniego (direct["*"].systemPrompt): używany, gdy wpis dla konkretnego peer nie istnieje lub nie definiuje systemPrompt.

• channels.whatsapp.groups jest zarówno mapą konfiguracji per grupa, jak i allowlistą grup na poziomie czatu. W zakresie głównym i zakresach kont groups["*"] oznacza „wszystkie grupy są dopuszczone” dla tego zakresu.
• Dodawaj wildcard group systemPrompt tylko wtedy, gdy i tak chcesz, aby ten zakres dopuszczał wszystkie grupy. Jeśli nadal chcesz, aby kwalifikował się tylko ustalony zestaw ID grup, nie używaj groups["*"] jako domyślnego promptu. Zamiast tego powtórz prompt przy każdym jawnie wpisanym na allowlistę wpisie grupy.
• Dopuszczenie grupy i autoryzacja nadawcy to osobne sprawdzenia. 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 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ż dopuszczone przez dmPolicy plus allowFrom lub reguły pairing-store.

{
  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 groups.
        "*": { systemPrompt: "Default prompt for all groups." },
      },
      direct: {
        // Dotyczy wszystkich kont, które nie definiują własnej mapy direct.
        "*": { systemPrompt: "Default prompt for all direct chats." },
      },
      accounts: {
        work: {
          groups: {
            // To konto definiuje własne groups, więc główne groups zostaje w pełni
            // zastąpione. Aby zachować wildcard, jawnie zdefiniuj tu również "*".
            "120363406415684625@g.us": {
              requireMention: false,
              systemPrompt: "Focus on project management.",
            },
            // Używaj tylko wtedy, gdy wszystkie grupy mają być dopuszczone na tym koncie.
            "*": { systemPrompt: "Default prompt for work groups." },
          },
          direct: {
            // To konto definiuje własną mapę direct, więc główne wpisy direct są
            // całkowicie zastępowane. Aby zachować wildcard, jawnie zdefiniuj tu również "*".
            "+15551234567": { systemPrompt: "Prompt for a specific work direct chat." },
            "*": { systemPrompt: "Default prompt for work direct chats." },
          },
        },
      },
    },
  },
}

​

Wskaźniki do referencji konfiguracji

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