Zalo osobisty

Stan: eksperymentalne. Ta integracja automatyzuje osobiste konto Zalo przez natywne zca-js wewnątrz OpenClaw.

Dołączony Plugin

Zalo Personal jest dostarczany jako dołączony Plugin w aktualnych wydaniach OpenClaw, więc zwykłe pakietowane kompilacje nie wymagają osobnej instalacji.

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

• Instalacja przez CLI: openclaw plugins install @openclaw/zalouser
• Przypięta wersja: openclaw plugins install @openclaw/zalouser@2026.5.2
• Albo z checkoutu źródłowego: openclaw plugins install ./path/to/local/zalouser-plugin
• Szczegóły: Plugins

Nie jest wymagany zewnętrzny plik binarny CLI zca/openzca.

Szybka konfiguracja (dla początkujących)

1. Upewnij się, że Plugin Zalo Personal jest dostępny.
   • Aktualne pakietowane wydania OpenClaw już go zawierają.
   • Starsze/niestandardowe instalacje mogą dodać go ręcznie za pomocą powyższych poleceń.
2. Zaloguj się (QR, na maszynie Gateway):
   • openclaw channels login --channel zalouser
   • Zeskanuj kod QR aplikacją mobilną Zalo.
3. Włącz kanał:

{  channels: {    zalouser: {      enabled: true,      dmPolicy: "pairing",    },  },}

4. Uruchom ponownie Gateway (albo zakończ konfigurację).
5. Dostęp przez DM domyślnie używa parowania; zatwierdź kod parowania przy pierwszym kontakcie.

Czym to jest

• Działa w całości w procesie przez zca-js.
• Używa natywnych nasłuchiwaczy zdarzeń do odbierania wiadomości przychodzących.
• Wysyła odpowiedzi bezpośrednio przez API JS (tekst/media/link).
• Zaprojektowane do przypadków użycia „konta osobistego”, gdy Zalo Bot API nie jest dostępne.

Nazewnictwo

Identyfikator kanału to zalouser, aby jednoznacznie wskazać, że automatyzuje osobiste konto użytkownika Zalo (nieoficjalnie). zalo rezerwujemy dla potencjalnej przyszłej oficjalnej integracji z API Zalo.

Znajdowanie identyfikatorów (katalog)

Użyj CLI katalogu, aby odkrywać peerów/grupy i ich identyfikatory:

openclaw directory self --channel zalouseropenclaw directory peers list --channel zalouser --query "name"openclaw directory groups list --channel zalouser --query "work"

Limity

• Tekst wychodzący jest dzielony na fragmenty po około 2000 znaków (limity klienta Zalo).
• Strumieniowanie jest domyślnie blokowane.

Kontrola dostępu (DM)

channels.zalouser.dmPolicy obsługuje: pairing | allowlist | open | disabled (domyślnie: pairing).

channels.zalouser.allowFrom powinno używać stabilnych identyfikatorów użytkowników Zalo. Może też odwoływać się do statycznych grup dostępu nadawców (accessGroup:<name>). Podczas interaktywnej konfiguracji wprowadzone nazwy mogą być rozwiązywane na identyfikatory z użyciem wyszukiwania kontaktów w procesie Plugina.

Jeśli surowa nazwa pozostanie w konfiguracji, przy starcie zostanie rozwiązana tylko wtedy, gdy włączone jest channels.zalouser.dangerouslyAllowNameMatching: true. Bez tej świadomej zgody sprawdzanie nadawców w czasie działania opiera się wyłącznie na identyfikatorach, a surowe nazwy są ignorowane przy autoryzacji.

Zatwierdź przez:

• openclaw pairing list zalouser
• openclaw pairing approve zalouser <code>

Dostęp grupowy (opcjonalnie)

• Domyślnie: channels.zalouser.groupPolicy = "open" (grupy dozwolone). Użyj channels.defaults.groupPolicy, aby nadpisać wartość domyślną, gdy nie jest ustawiona.
• Ogranicz do listy dozwolonych za pomocą:
  • channels.zalouser.groupPolicy = "allowlist"
  • channels.zalouser.groups (klucze powinny być stabilnymi identyfikatorami grup; nazwy są rozwiązywane na identyfikatory przy starcie tylko wtedy, gdy włączone jest channels.zalouser.dangerouslyAllowNameMatching: true)
  • channels.zalouser.groupAllowFrom (kontroluje, którzy nadawcy w dozwolonych grupach mogą uruchamiać bota; do statycznych grup dostępu nadawców można odwoływać się przez accessGroup:<name>)
• Zablokuj wszystkie grupy: channels.zalouser.groupPolicy = "disabled".
• Kreator konfiguracji może zapytać o listy dozwolonych grup.
• Przy starcie OpenClaw rozwiązuje nazwy grup/użytkowników na listach dozwolonych na identyfikatory i loguje mapowanie tylko wtedy, gdy włączone jest channels.zalouser.dangerouslyAllowNameMatching: true.
• Dopasowywanie listy dozwolonych grup domyślnie opiera się wyłącznie na identyfikatorach. Nierozwiązane nazwy są ignorowane przy autoryzacji, chyba że włączone jest channels.zalouser.dangerouslyAllowNameMatching: true.
• channels.zalouser.dangerouslyAllowNameMatching: true to awaryjny tryb zgodności, który ponownie włącza zmienne rozwiązywanie nazw przy starcie i dopasowywanie nazw grup w czasie działania.
• Jeśli groupAllowFrom nie jest ustawione, w czasie działania sprawdzanie nadawców w grupach używa zastępczo allowFrom.
• Sprawdzanie nadawców dotyczy zarówno zwykłych wiadomości grupowych, jak i poleceń sterujących (na przykład /new, /reset).

Przykład:

{  channels: {    zalouser: {      groupPolicy: "allowlist",      groupAllowFrom: ["1471383327500481391"],      groups: {        "123456789": { allow: true },        "Work Chat": { allow: true },      },    },  },}

Bramkowanie wzmianek w grupie

• channels.zalouser.groups.<group>.requireMention kontroluje, czy odpowiedzi w grupie wymagają wzmianki.
• Kolejność rozwiązywania: dokładny identyfikator/nazwa grupy -> znormalizowany slug grupy -> * -> wartość domyślna (true).
• Dotyczy to zarówno grup z listy dozwolonych, jak i trybu otwartych grup.
• Cytowanie wiadomości bota liczy się jako niejawna wzmianka do aktywacji w grupie.
• Autoryzowane polecenia sterujące (na przykład /new) mogą omijać bramkowanie wzmianek.
• Gdy wiadomość grupowa zostanie pominięta, ponieważ wymagana jest wzmianka, OpenClaw zapisuje ją jako oczekującą historię grupy i dołącza przy następnej przetwarzanej wiadomości grupowej.
• Limit historii grup domyślnie wynosi messages.groupChat.historyLimit (wartość zastępcza 50). Możesz nadpisać go dla konta za pomocą channels.zalouser.historyLimit.

Przykład:

{  channels: {    zalouser: {      groupPolicy: "allowlist",      groups: {        "*": { allow: true, requireMention: true },        "Work Chat": { allow: true, requireMention: false },      },    },  },}

Wiele kont

Konta mapują się na profile zalouser w stanie OpenClaw. Przykład:

{  channels: {    zalouser: {      enabled: true,      defaultAccount: "default",      accounts: {        work: { enabled: true, profile: "work" },      },    },  },}

Zmienne środowiskowe

Plugin Zalo Personal może też odczytywać wybór profilu ze zmiennych środowiskowych:

• ZALOUSER_PROFILE: nazwa profilu używana, gdy w konfiguracji kanału lub konta nie ustawiono profile.
• ZCA_PROFILE: starsza zastępcza nazwa profilu, używana tylko wtedy, gdy ZALOUSER_PROFILE nie jest ustawione.

Nazwy profili wybierają zapisane dane logowania Zalo w stanie OpenClaw. Kolejność rozwiązywania:

1. Jawne profile w konfiguracji.
2. ZALOUSER_PROFILE.
3. ZCA_PROFILE.
4. Identyfikator konta dla kont innych niż domyślne albo default dla konta domyślnego.

W konfiguracjach z wieloma kontami preferuj ustawienie profile dla każdego konta w konfiguracji, aby jedna zmienna środowiskowa nie powodowała współdzielenia tej samej sesji logowania przez wiele kont.

Pisanie, reakcje i potwierdzenia dostarczenia

• OpenClaw wysyła zdarzenie pisania przed wysłaniem odpowiedzi (best-effort).
• Akcja reakcji na wiadomość react jest obsługiwana dla zalouser w akcjach kanału.
  • Użyj remove: true, aby usunąć określone emoji reakcji z wiadomości.
  • Semantyka reakcji: Reakcje
• Dla wiadomości przychodzących, które zawierają metadane zdarzenia, OpenClaw wysyła potwierdzenia dostarczenia i wyświetlenia (best-effort).

Rozwiązywanie problemów

Logowanie nie zostaje zapamiętane:

• openclaw channels status --probe
• Ponowne logowanie: openclaw channels logout --channel zalouser && openclaw channels login --channel zalouser

Nazwa na liście dozwolonych/grupy nie została rozwiązana:

• Użyj numerycznych identyfikatorów w allowFrom/groupAllowFrom oraz stabilnych identyfikatorów grup w groups. Jeśli celowo potrzebujesz dokładnych nazw znajomych/grup, włącz channels.zalouser.dangerouslyAllowNameMatching: true.

Aktualizacja ze starej konfiguracji opartej na CLI:

• Usuń wszelkie stare założenia dotyczące zewnętrznego procesu zca.
• Kanał działa teraz w pełni w OpenClaw bez zewnętrznych plików binarnych CLI.

Powiązane

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