Zalo osobiste

Status: eksperymentalna. Ta integracja automatyzuje osobiste konto Zalo za pomocą natywnego zca-js, wewnątrz procesu, bez zewnętrznego pliku binarnego CLI.

Instalacja

Zalo Personal jest oficjalnym zewnętrznym pluginem, niedołączonym do rdzenia. Zainstaluj go przed użyciem:

openclaw plugins install @openclaw/zalouser

• Przypnij wersję: openclaw plugins install @openclaw/zalouser@<version>
• Z kopii roboczej kodu źródłowego: openclaw plugins install ./path/to/local/zalouser-plugin
• Szczegóły: Pluginy

Szybka konfiguracja

1. Zainstaluj plugin (powyżej).
2. Zaloguj się (kod QR, na komputerze z Gateway):
   • openclaw channels login --channel zalouser
   • Zeskanuj kod QR za pomocą aplikacji mobilnej Zalo.
3. Włącz kanał:

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

4. Uruchom ponownie Gateway (lub dokończ konfigurację).
5. Dostęp do wiadomości prywatnych domyślnie korzysta z parowania; przy pierwszym kontakcie zatwierdź kod parowania.

Czym jest ta integracja

• Działa w całości wewnątrz procesu za pośrednictwem biblioteki zca-js (bez zewnętrznego pliku binarnego zca/openzca).
• Używa natywnych detektorów zdarzeń (message, error) do odbierania wiadomości przychodzących.
• Wysyła odpowiedzi bezpośrednio przez interfejs API JS (tekst/multimedia/link).
• Jest przeznaczona do zastosowań z „kontem osobistym”, w których interfejs Zalo Bot API nie jest dostępny.

Nazewnictwo

Identyfikator kanału to zalouser, aby wyraźnie wskazać, że automatyzowane jest osobiste konto użytkownika Zalo (nieoficjalnie). Identyfikator zalo jest zarezerwowany dla potencjalnej przyszłej oficjalnej integracji z interfejsem API Zalo.

Znajdowanie identyfikatorów (katalog)

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

Ograniczenia

• Tekst wychodzący jest dzielony na fragmenty po 2000 znaków (limit klienta Zalo).
• Strumieniowanie nie jest obsługiwane.

Kontrola dostępu (wiadomości prywatne)

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

W channels.zalouser.allowFrom należy używać stabilnych identyfikatorów użytkowników Zalo. Można również odwoływać się do statycznych grup dostępu nadawców (accessGroup:<name>). Podczas interaktywnej konfiguracji wprowadzone nazwy mogą zostać przekształcone na identyfikatory za pomocą działającego wewnątrz procesu mechanizmu wyszukiwania kontaktów pluginu.

Jeśli w konfiguracji pozostanie nieprzetworzona nazwa, podczas uruchamiania zostanie przekształcona tylko wtedy, gdy włączono channels.zalouser.dangerouslyAllowNameMatching: true. Bez tego jawnego ustawienia kontrole nadawców w czasie działania opierają się wyłącznie na identyfikatorach, a nieprzetworzone nazwy są ignorowane podczas autoryzacji.

Zatwierdź za pomocą:

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

Dostęp grupowy (opcjonalny)

• Domyślnie: channels.zalouser.groupPolicy = "allowlist" (grupy wymagają jawnego wpisu na liście dozwolonych).
• Otwórz wszystkie grupy: channels.zalouser.groupPolicy = "open".
• Zablokuj wszystkie grupy: channels.zalouser.groupPolicy = "disabled".
• Przy groupPolicy = "allowlist":
  • Kluczami channels.zalouser.groups powinny być stabilne identyfikatory grup; nazwy są przekształcane na identyfikatory podczas uruchamiania tylko wtedy, gdy włączono channels.zalouser.dangerouslyAllowNameMatching: true.
  • channels.zalouser.groupAllowFrom określa, którzy nadawcy w dozwolonych grupach mogą aktywować bota; do statycznych grup dostępu nadawców można odwoływać się za pomocą accessGroup:<name>.
• Kreator konfiguracji może wyświetlić monit o listy dozwolonych grup.
• Domyślnie dopasowywanie listy dozwolonych grup opiera się wyłącznie na identyfikatorach. Nazwy, których nie udało się przekształcić, są ignorowane podczas autoryzacji, chyba że włączono channels.zalouser.dangerouslyAllowNameMatching: true.
• channels.zalouser.dangerouslyAllowNameMatching: true to awaryjny tryb zgodności, który ponownie włącza przekształcanie zmiennych nazw podczas uruchamiania i dopasowywanie nazw grup w czasie działania.
• W przypadku zwykłych wiadomości grupowych groupAllowFrom nie używa zastępczo allowFrom: pozostawienie tej wartości pustej dla grupy znajdującej się na liście dozwolonych otwiera tę grupę dla dowolnego nadawcy. Wyjątkiem są autoryzowane polecenia sterujące (na przykład /new); gdy groupAllowFrom jest puste, kontrole nadawcy polecenia używają zastępczo allowFrom.

Przykład:

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

Wymaganie wzmianki w grupie

• channels.zalouser.groups.<group>.requireMention określa, czy odpowiedzi w grupie wymagają wzmianki.
• Kolejność rozstrzygania: identyfikator grupy -> alias group:<id> -> nazwa/skrót grupy (kandydaci oparci na nazwach mają zastosowanie tylko przy dangerouslyAllowNameMatching: true) -> * -> wartość domyślna (true).
• Dotyczy zarówno grup z listy dozwolonych, jak i trybu otwartych grup.
• Zacytowanie wiadomości bota jest traktowane jako niejawna wzmianka aktywująca grupę.
• Autoryzowane polecenia sterujące (na przykład /new) mogą pomijać wymóg wzmianki.
• Gdy wiadomość grupowa zostanie pominięta z powodu wymaganej wzmianki, OpenClaw zapisuje ją jako oczekującą historię grupy i dołącza do następnej przetwarzanej wiadomości grupowej.
• Limit historii grupy: channels.zalouser.historyLimit, następnie messages.groupChat.historyLimit, a potem wartość zastępcza 50.

Przykład:

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

Wiele kont

Konta są mapowane na profile zalouser w stanie OpenClaw. Przykład:

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

Zmienne środowiskowe

Profil można również wybrać za pomocą zmiennych środowiskowych:

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

1. Jawnie określony profile w konfiguracji.
2. ZALOUSER_PROFILE.
3. ZCA_PROFILE.
4. Identyfikator konta w przypadku kont innych niż domyślne albo default w przypadku konta domyślnego.

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

Wskaźnik pisania, reakcje i potwierdzenia dostarczenia

• OpenClaw wysyła zdarzenie pisania przed przekazaniem odpowiedzi do wysłania (w miarę możliwości).
• Akcja reakcji na wiadomość react jest obsługiwana dla zalouser w akcjach kanału.
  • Użyj remove: true, aby usunąć określoną reakcję emoji z wiadomości.
  • Zasady działania reakcji: Reakcje
• W przypadku wiadomości przychodzących zawierających metadane zdarzenia OpenClaw wysyła potwierdzenia dostarczenia i wyświetlenia (w miarę możliwości).

Rozwiązywanie problemów

Logowanie nie jest zachowywane:

• openclaw channels status --probe
• Zaloguj się ponownie: openclaw channels logout --channel zalouser && openclaw channels login --channel zalouser

Nie udało się przekształcić nazwy na liście dozwolonych lub nazwy grupy:

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

Aktualizacja ze starej konfiguracji opartej na zewnętrznym zca/CLI:

• Usuń wszelkie założenia dotyczące zewnętrznego procesu zca; kanał działa teraz w całości wewnątrz procesu za pośrednictwem zca-js, bez zewnętrznego pliku binarnego CLI.

Powiązane materiały

• Przegląd kanałów - wszystkie obsługiwane kanały
• Parowanie - uwierzytelnianie wiadomości prywatnych i przebieg parowania
• Grupy - działanie czatów grupowych i wymóg wzmianki
• Trasowanie kanałów - trasowanie sesji dla wiadomości
• Bezpieczeństwo - model dostępu i wzmacnianie zabezpieczeń