> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Zalo osobisty
Stan: eksperymentalne. Ta integracja automatyzuje **osobiste konto Zalo** przez natywne `zca-js` wewnątrz OpenClaw.
To nieoficjalna integracja i może skutkować zawieszeniem lub zbanowaniem konta. Używasz jej na własne ryzyko.
## 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](/pl/tools/plugin)
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ł:
```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
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:
```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw directory self --channel zalouser
openclaw 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:`). 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 `
## 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:`)
* 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:
```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
channels: {
zalouser: {
groupPolicy: "allowlist",
groupAllowFrom: ["1471383327500481391"],
groups: {
"123456789": { allow: true },
"Work Chat": { allow: true },
},
},
},
}
```
### Bramkowanie wzmianek w grupie
* `channels.zalouser.groups..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:
```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
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:
```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
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](/pl/tools/reactions)
* 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](/pl/channels) — wszystkie obsługiwane kanały
* [Parowanie](/pl/channels/pairing) — uwierzytelnianie DM i przepływ parowania
* [Grupy](/pl/channels/groups) — zachowanie czatu grupowego i bramkowanie wzmianek
* [Routing kanałów](/pl/channels/channel-routing) — routing sesji dla wiadomości
* [Bezpieczeństwo](/pl/gateway/security) — model dostępu i utwardzanie