Regional platforms

Zalo

Status: eksperymentalny. DM są obsługiwane. Poniższa sekcja Możliwości odzwierciedla obecne działanie botów Marketplace.

Wbudowany Plugin

Zalo jest dostarczane jako wbudowany Plugin w obecnych wydaniach OpenClaw, więc zwykłe spakowane kompilacje nie wymagają osobnej instalacji.

Jeśli używasz starszej kompilacji lub niestandardowej instalacji, która wyklucza Zalo, zainstaluj pakiet npm bezpośrednio:

Instalacja przez CLI: openclaw plugins install @openclaw/zalo
Przypięta wersja: openclaw plugins install @openclaw/[email protected]
Albo z checkoutu źródłowego: openclaw plugins install ./path/to/local/zalo-plugin
Szczegóły: Pluginy

Szybka konfiguracja (dla początkujących)

Upewnij się, że Plugin Zalo jest dostępny.
- Obecne spakowane wydania OpenClaw już go zawierają.
- Starsze/niestandardowe instalacje mogą dodać go ręcznie poleceniami powyżej.
Ustaw token:
- Env: ZALO_BOT_TOKEN=...
- Albo konfiguracja: channels.zalo.accounts.default.botToken: "...".
Uruchom ponownie Gateway (albo dokończ konfigurację).
Dostęp przez DM domyślnie używa parowania; zatwierdź kod parowania przy pierwszym kontakcie.

Minimalna konfiguracja:

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

Czym to jest

Zalo to aplikacja komunikacyjna skupiona na Wietnamie; jej Bot API pozwala Gateway uruchamiać bota do rozmów 1:1. Dobrze sprawdza się w obsłudze klienta lub powiadomieniach, gdy chcesz mieć deterministyczny routing z powrotem do Zalo.

Ta strona odzwierciedla obecne działanie OpenClaw dla botów Zalo Bot Creator / Marketplace. Boty Zalo Official Account (OA) są inną powierzchnią produktu Zalo i mogą działać inaczej.

Kanał Zalo Bot API zarządzany przez Gateway.
Deterministyczny routing: odpowiedzi wracają do Zalo; model nigdy nie wybiera kanałów.
DM współdzielą główną sesję agenta.
Poniższa sekcja Możliwości pokazuje obecną obsługę botów Marketplace.

Konfiguracja (szybka ścieżka)

1) Utwórz token bota (Zalo Bot Platform)

Przejdź do https://bot.zaloplatforms.com i zaloguj się.
Utwórz nowego bota i skonfiguruj jego ustawienia.
Skopiuj pełny token bota (zwykle numeric_id:secret). W przypadku botów Marketplace używalny token runtime może pojawić się w wiadomości powitalnej bota po utworzeniu.

2) Skonfiguruj token (env lub konfiguracja)

Przykład:

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

Jeśli później przejdziesz na powierzchnię bota Zalo, gdzie dostępne są grupy, możesz jawnie dodać konfigurację specyficzną dla grup, taką jak groupPolicy i groupAllowFrom. Obecne działanie botów Marketplace opisuje sekcja Możliwości.

Opcja env: ZALO_BOT_TOKEN=... (działa tylko dla konta domyślnego).

Obsługa wielu kont: użyj channels.zalo.accounts z tokenami dla poszczególnych kont oraz opcjonalnym name.

Uruchom ponownie Gateway. Zalo startuje, gdy token zostanie rozstrzygnięty (env lub konfiguracja).
Dostęp przez DM domyślnie używa parowania. Zatwierdź kod po pierwszym kontakcie z botem.

Jak to działa (zachowanie)

Wiadomości przychodzące są normalizowane do współdzielonej koperty kanału z placeholderami mediów.
Odpowiedzi zawsze wracają do tego samego czatu Zalo.
Domyślnie używany jest long-polling; tryb webhook jest dostępny przez channels.zalo.webhookUrl.

Limity

Tekst wychodzący jest dzielony na fragmenty po 2000 znaków (limit Zalo API).
Pobieranie/wysyłanie mediów jest ograniczone przez channels.zalo.mediaMaxMb (domyślnie 5).
Streaming jest domyślnie blokowany, ponieważ limit 2000 znaków zmniejsza jego użyteczność.

Kontrola dostępu (DM)

Dostęp przez DM

Domyślnie: channels.zalo.dmPolicy = "pairing". Nieznani nadawcy otrzymują kod parowania; wiadomości są ignorowane do czasu zatwierdzenia (kody wygasają po 1 godzinie).
Zatwierdzanie przez:
- openclaw pairing list zalo
- openclaw pairing approve zalo <CODE>
Parowanie jest domyślną wymianą tokenu. Szczegóły: Parowanie
channels.zalo.allowFrom akceptuje numeryczne identyfikatory użytkowników (wyszukiwanie po nazwie użytkownika nie jest dostępne).

Kontrola dostępu (grupy)

Dla botów Zalo Bot Creator / Marketplace obsługa grup nie była dostępna w praktyce, ponieważ bota w ogóle nie dało się dodać do grupy.

Oznacza to, że poniższe klucze konfiguracji związane z grupami istnieją w schemacie, ale nie były użyteczne dla botów Marketplace:

channels.zalo.groupPolicy kontroluje obsługę przychodzącą w grupach: open | allowlist | disabled.
channels.zalo.groupAllowFrom ogranicza, które identyfikatory nadawców mogą wywołać bota w grupach.
Jeśli groupAllowFrom nie jest ustawione, Zalo wraca do allowFrom przy sprawdzaniu nadawców.
Uwaga runtime: jeśli channels.zalo całkowicie brakuje, runtime nadal wraca do groupPolicy="allowlist" ze względów bezpieczeństwa.

Wartości polityki grupowej (gdy dostęp do grup jest dostępny na powierzchni Twojego bota) to:

groupPolicy: "disabled" — blokuje wszystkie wiadomości grupowe.
groupPolicy: "open" — dopuszcza dowolnego członka grupy (z bramkowaniem przez wzmiankę).
groupPolicy: "allowlist" — domyślne zachowanie fail-closed; akceptowani są tylko dozwoleni nadawcy.

Jeśli używasz innej powierzchni produktu bota Zalo i zweryfikowano działające zachowanie grupowe, udokumentuj je osobno, zamiast zakładać, że odpowiada przepływowi bota Marketplace.

Long-polling kontra webhook

Domyślnie: long-polling (publiczny URL nie jest wymagany).
Tryb webhook: ustaw channels.zalo.webhookUrl i channels.zalo.webhookSecret.
- Sekret webhook musi mieć 8-256 znaków.
- URL webhook musi używać HTTPS.
- Zalo wysyła zdarzenia z nagłówkiem X-Bot-Api-Secret-Token do weryfikacji.
- HTTP Gateway obsługuje żądania webhook pod channels.zalo.webhookPath (domyślnie ścieżka z URL webhook).
- Żądania muszą używać Content-Type: application/json (albo typów mediów +json).
- Zduplikowane zdarzenia (event_name + message_id) są ignorowane przez krótkie okno ponownego odtworzenia.
- Ruch skokowy jest limitowany per ścieżka/źródło i może zwrócić HTTP 429.

Uwaga: getUpdates (polling) i webhook wzajemnie się wykluczają zgodnie z dokumentacją Zalo API.

Obsługiwane typy wiadomości

Szybki przegląd obsługi znajdziesz w sekcji Możliwości. Poniższe uwagi dodają szczegóły tam, gdzie zachowanie wymaga dodatkowego kontekstu.

Wiadomości tekstowe: Pełna obsługa z dzieleniem na fragmenty po 2000 znaków.
Zwykłe URL w tekście: Zachowują się jak normalne wejście tekstowe.
Podglądy linków / bogate karty linków: Zobacz status bota Marketplace w sekcji Możliwości; nie wywoływały one niezawodnie odpowiedzi.
Wiadomości obrazkowe: Zobacz status bota Marketplace w sekcji Możliwości; obsługa obrazów przychodzących była zawodna (wskaźnik pisania bez końcowej odpowiedzi).
Naklejki: Zobacz status bota Marketplace w sekcji Możliwości.
Notatki głosowe / pliki audio / wideo / ogólne załączniki plików: Zobacz status bota Marketplace w sekcji Możliwości.
Nieobsługiwane typy: Logowane (na przykład wiadomości od chronionych użytkowników).

Możliwości

Ta tabela podsumowuje obecne działanie bota Zalo Bot Creator / Marketplace w OpenClaw.

Funkcja	Status
Wiadomości bezpośrednie	✅ Obsługiwane
Grupy	❌ Niedostępne dla botów Marketplace
Media (obrazy przychodzące)	⚠️ Ograniczone / zweryfikuj w swoim środowisku
Media (obrazy wychodzące)	⚠️ Nie przetestowano ponownie dla botów Marketplace
Zwykłe URL w tekście	✅ Obsługiwane
Podglądy linków	⚠️ Zawodne dla botów Marketplace
Reakcje	❌ Nieobsługiwane
Naklejki	⚠️ Brak odpowiedzi agenta dla botów Marketplace
Notatki głosowe / audio / wideo	⚠️ Brak odpowiedzi agenta dla botów Marketplace
Załączniki plików	⚠️ Brak odpowiedzi agenta dla botów Marketplace
Wątki	❌ Nieobsługiwane
Ankiety	❌ Nieobsługiwane
Polecenia natywne	❌ Nieobsługiwane
Streaming	⚠️ Zablokowany (limit 2000 znaków)

Cele dostarczania (CLI/cron)

Użyj identyfikatora czatu jako celu.
Przykład: openclaw message send --channel zalo --target 123456789 --message "hi".

Rozwiązywanie problemów

Bot nie odpowiada:

Sprawdź, czy token jest prawidłowy: openclaw channels status --probe
Zweryfikuj, że nadawca jest zatwierdzony (parowanie albo allowFrom)
Sprawdź logi Gateway: openclaw logs --follow

Webhook nie odbiera zdarzeń:

Upewnij się, że URL webhook używa HTTPS
Zweryfikuj, że token sekretu ma 8-256 znaków
Potwierdź, że punkt końcowy HTTP Gateway jest osiągalny na skonfigurowanej ścieżce
Sprawdź, czy polling getUpdates nie działa (wzajemnie się wykluczają)

Odniesienie konfiguracji (Zalo)

Pełna konfiguracja: Konfiguracja

Płaskie klucze najwyższego poziomu (channels.zalo.botToken, channels.zalo.dmPolicy i podobne) są starszym skrótem dla pojedynczego konta. Dla nowych konfiguracji preferuj channels.zalo.accounts.<id>.*. Obie formy nadal są tutaj udokumentowane, ponieważ istnieją w schemacie.

Opcje dostawcy:

channels.zalo.enabled: włącza/wyłącza uruchamianie kanału.
channels.zalo.botToken: token bota z Zalo Bot Platform.
channels.zalo.tokenFile: odczytuje token ze zwykłej ścieżki pliku. Dowiązania symboliczne są odrzucane.
channels.zalo.dmPolicy: pairing | allowlist | open | disabled (domyślnie: pairing).
channels.zalo.allowFrom: allowlist DM (identyfikatory użytkowników). open wymaga "*". Kreator poprosi o numeryczne identyfikatory.
channels.zalo.groupPolicy: open | allowlist | disabled (domyślnie: allowlist). Obecne w konfiguracji; bieżące działanie botów Marketplace opisują Możliwości i Kontrola dostępu (grupy).
channels.zalo.groupAllowFrom: allowlist nadawców grupowych (identyfikatory użytkowników). Wraca do allowFrom, gdy nie jest ustawione.
channels.zalo.mediaMaxMb: limit mediów przychodzących/wychodzących (MB, domyślnie 5).
channels.zalo.webhookUrl: włącza tryb webhook (wymagane HTTPS).
channels.zalo.webhookSecret: sekret webhook (8-256 znaków).
channels.zalo.webhookPath: ścieżka webhook na serwerze HTTP Gateway.
channels.zalo.proxy: URL proxy dla żądań API.

Opcje wielu kont:

channels.zalo.accounts.<id>.botToken: token dla konta.
channels.zalo.accounts.<id>.tokenFile: zwykły plik tokenu dla konta. Dowiązania symboliczne są odrzucane.
channels.zalo.accounts.<id>.name: nazwa wyświetlana.
channels.zalo.accounts.<id>.enabled: włącza/wyłącza konto.
channels.zalo.accounts.<id>.dmPolicy: polityka DM dla konta.
channels.zalo.accounts.<id>.allowFrom: allowlist dla konta.
channels.zalo.accounts.<id>.groupPolicy: polityka grupowa dla konta. Obecne w konfiguracji; bieżące działanie botów Marketplace opisują Możliwości i Kontrola dostępu (grupy).
channels.zalo.accounts.<id>.groupAllowFrom: allowlist nadawców grupowych dla konta.
channels.zalo.accounts.<id>.webhookUrl: URL webhook dla konta.
channels.zalo.accounts.<id>.webhookSecret: sekret webhook dla konta.
channels.zalo.accounts.<id>.webhookPath: ścieżka webhook dla konta.
channels.zalo.accounts.<id>.proxy: URL proxy dla konta.

Powiązane

Przegląd kanałów — wszystkie obsługiwane kanały
Parowanie — uwierzytelnianie DM i przepływ parowania
Grupy — zachowanie czatu grupowego i bramkowanie przez wzmianki
Routing kanałów — routing sesji dla wiadomości
Bezpieczeństwo — model dostępu i wzmacnianie zabezpieczeń

# Wbudowany Plugin

# Szybka konfiguracja (dla początkujących)

# Czym to jest

# Konfiguracja (szybka ścieżka)

# 1) Utwórz token bota (Zalo Bot Platform)

# 2) Skonfiguruj token (env lub konfiguracja)

# Jak to działa (zachowanie)

# Limity

# Kontrola dostępu (DM)

# Dostęp przez DM

# Kontrola dostępu (grupy)

# Long-polling kontra webhook

# Obsługiwane typy wiadomości

# Możliwości

# Cele dostarczania (CLI/cron)

# Rozwiązywanie problemów

# Odniesienie konfiguracji (Zalo)

# Powiązane