Zalo

​

Dołączony plugin

• Instalacja: openclaw plugins install @openclaw/zalo
• Przypięta wersja: openclaw plugins install @openclaw/zalo@2026.6.11
• Z lokalnego repozytorium roboczego: openclaw plugins install ./path/to/local/zalo-plugin
• Szczegóły: Pluginy

​

Szybka konfiguracja

1. Utwórz token bota na stronie https://bot.zaloplatforms.com (zaloguj się, utwórz bota i skonfiguruj ustawienia). Token ma postać numeric_id:secret; w przypadku botów Marketplace token używany w środowisku uruchomieniowym może znajdować się w wiadomości powitalnej bota.
2. Ustaw token jako zmienną środowiskową ZALO_BOT_TOKEN=... (tylko dla konta domyślnego) lub w konfiguracji.
3. Uruchom ponownie Gateway.
4. Przy pierwszym kontakcie przez wiadomość bezpośrednią zatwierdź kod parowania (domyślna zasada wiadomości bezpośrednich to parowanie).

{
  channels: {
    zalo: {
      enabled: true,
      accounts: {
        default: {
          botToken: "12345689:abc-xyz",
          dmPolicy: "pairing",
        },
      },
    },
  },
}

​

Czym jest Zalo

​

Jak to działa

• Wiadomości przychodzące są normalizowane do wspólnej otoczki kanału z symbolami zastępczymi multimediów.
• Odpowiedzi są zawsze kierowane z powrotem do tego samego czatu Zalo; odpowiedź z cytowaniem nie jest używana (replyToMode jest trwale wyłączony).
• Domyślnie używane jest długie odpytywanie (getUpdates); tryb Webhook jest dostępny przez channels.zalo.webhookUrl.
• W grupach do wywołania bota wymagane jest użycie @wzmianki; nie można tego skonfigurować osobno dla kanału.

​

Limity

​

Kontrola dostępu

​

Wiadomości bezpośrednie

• channels.zalo.dmPolicy: pairing (domyślnie) | allowlist | open | disabled.
• Parowanie: nieznani nadawcy otrzymują kod parowania; wiadomości są ignorowane do czasu zatwierdzenia. Kody wygasają po 1 godzinie.
  • openclaw pairing list zalo
  • openclaw pairing approve zalo <CODE>
  • Szczegóły: Parowanie
• channels.zalo.allowFrom przyjmuje numeryczne identyfikatory użytkowników Zalo (bez wyszukiwania według nazwy użytkownika). open wymaga "*".

​

Grupy

• channels.zalo.groupPolicy: open | allowlist | disabled.
• channels.zalo.groupAllowFrom ogranicza identyfikatory nadawców, którzy mogą wywołać bota w grupach; jeśli nie ustawiono tej opcji, używana jest wartość allowFrom.
• Domyślne rozstrzyganie: gdy skonfigurowano channels.zalo, nieustawiona wartość groupPolicy jest rozstrzygana jako open. Gdy całkowicie brakuje channels.zalo, środowisko uruchomieniowe bezpiecznie przyjmuje allowlist.
• Zgłaszane zastrzeżenie z praktycznego użycia: w niektórych konfiguracjach botów Marketplace nie można było w ogóle dodać bota do grupy. Jeśli wystąpi ten problem, zweryfikuj ustawienia bota na Zalo Bot Platform; jest to ograniczenie platformy, a nie zasada OpenClaw.

​

Długie odpytywanie a Webhook

• Domyślnie: długie odpytywanie (publiczny adres URL nie jest wymagany).
• Tryb Webhook: ustaw channels.zalo.webhookUrl i channels.zalo.webhookSecret.
  • Adres URL Webhook musi używać HTTPS.
  • Sekret Webhook musi mieć od 8 do 256 znaków.
  • Zalo wysyła zdarzenia z nagłówkiem X-Bot-Api-Secret-Token, który jest sprawdzany za pomocą porównania w stałym czasie.
  • Serwer HTTP Gateway obsługuje żądania Webhook pod ścieżką channels.zalo.webhookPath (domyślnie jest to ścieżka adresu URL Webhook).
  • Żądania muszą używać Content-Type: application/json (lub typu multimediów z przyrostkiem +json).
  • Zgodnie z dokumentacją API Zalo odpytywanie getUpdates i Webhook wzajemnie się wykluczają.

​

Obsługiwane typy wiadomości

• Tekst: pełna obsługa, dzielony na fragmenty po 2000 znaków.
• Multimedia: przychodzące i wychodzące, ograniczone przez mediaMaxMb.
• Reakcje, wątki, ankiety i polecenia natywne: nie są obsługiwane przez plugin.
• Przesyłanie strumieniowe: plugin deklaruje możliwość strumieniowego przesyłania bloków, ale Zalo nie ma osobnych opcji dostrajania kolejki wychodzącej ani scalania tekstu (w przeciwieństwie do niektórych innych kanałów regionalnych); jeśli ma to znaczenie w Twoim zastosowaniu, zweryfikuj bieżące zachowanie w swoim środowisku.

​

Możliwości

​

Cele dostarczania (CLI/Cron)

openclaw message send --channel zalo --target 123456789 --message "hi"

​

Rozwiązywanie problemów

• Sprawdź token: openclaw channels status --probe
• Sprawdź, czy nadawca został zatwierdzony (przez parowanie lub allowFrom)
• Sprawdź dzienniki Gateway: openclaw logs --follow

• Upewnij się, że adres URL Webhook używa HTTPS
• Upewnij się, że sekret ma od 8 do 256 znaków
• Upewnij się, że punkt końcowy HTTP Gateway jest dostępny pod skonfigurowaną ścieżką
• Upewnij się, że odpytywanie getUpdates nie jest również uruchomione (te tryby wzajemnie się wykluczają)
• Nagły wzrost liczby żądań może powodować zwracanie HTTP 429 (120 żądań / 60 s na ścieżkę i adres IP); zwiększ odstęp i spróbuj ponownie

​

Dokumentacja konfiguracji

​

Powiązane

• Przegląd kanałów - wszystkie obsługiwane kanały
• Parowanie - uwierzytelnianie wiadomości bezpośrednich i proces parowania
• Grupy - zachowanie czatów grupowych i wymóg wzmianki
• Kierowanie kanałów - kierowanie sesji dla wiadomości
• Bezpieczeństwo - model dostępu i wzmacnianie zabezpieczeń