Zalo Personal (non ufficiale)

Stato: sperimentale. Questa integrazione automatizza un account personale Zalo tramite zca-js nativo all’interno di OpenClaw.

Attenzione: Questa e un’integrazione non ufficiale e potrebbe causare la sospensione/ban dell’account. Usala a tuo rischio.

Plugin necessario

Zalo Personal e distribuito come plugin e non e incluso nell’installazione core.

Installa da CLI: openclaw plugins install @openclaw/zalouser
Oppure da un checkout sorgente: openclaw plugins install ./extensions/zalouser
Dettagli: Plugin

Nessun binario CLI esterno zca/openzca e necessario.

Setup rapido (principianti)

Installa il plugin (vedi sopra).
Login (QR, sulla macchina del Gateway):
- openclaw channels login --channel zalouser
- Scansiona il codice QR con l’app Zalo mobile.
Abilita il canale:

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

Riavvia il Gateway (o completa l’onboarding).
L’accesso DM e in pairing per impostazione predefinita; approva il codice di pairing al primo contatto.

Cos’e

Funziona interamente in-process tramite zca-js.
Usa listener di eventi nativi per ricevere i messaggi in ingresso.
Invia risposte direttamente tramite l’API JS (testo/media/link).
Progettato per casi d’uso con “account personale” dove la Zalo Bot API non e disponibile.

Denominazione

L’ID canale e zalouser per rendere esplicito che si sta automatizzando un account utente personale Zalo (non ufficiale). Manteniamo zalo riservato per una potenziale futura integrazione ufficiale con l’API Zalo.

Trovare gli ID (directory)

Usa la CLI directory per scoprire peer/gruppi e i loro ID:

openclaw directory self --channel zalouser
openclaw directory peers list --channel zalouser --query "nome"
openclaw directory groups list --channel zalouser --query "lavoro"

Limiti

Il testo in uscita viene segmentato a ~2000 caratteri (limiti del client Zalo).
Lo streaming e bloccato per impostazione predefinita.

Controllo degli accessi (DM)

channels.zalouser.dmPolicy supporta: pairing | allowlist | open | disabled (predefinito: pairing).

channels.zalouser.allowFrom accetta ID utente o nomi. Durante l’onboarding, i nomi vengono risolti in ID usando il lookup dei contatti in-process del plugin.

Approvazione tramite:

openclaw pairing list zalouser
openclaw pairing approve zalouser <code>

Accesso ai gruppi (opzionale)

Predefinito: channels.zalouser.groupPolicy = "open" (gruppi consentiti). Usa channels.defaults.groupPolicy per sovrascrivere il valore predefinito se non impostato.
Limita a un’allowlist con:
- channels.zalouser.groupPolicy = "allowlist"
- channels.zalouser.groups (le chiavi dovrebbero essere ID di gruppo stabili; i nomi vengono risolti in ID all’avvio quando possibile)
- channels.zalouser.groupAllowFrom (controlla quali mittenti nei gruppi consentiti possono attivare il bot)
Blocca tutti i gruppi: channels.zalouser.groupPolicy = "disabled".
Il wizard di configurazione puo richiedere le allowlist dei gruppi.
All’avvio, OpenClaw risolve i nomi di gruppo/utente nelle allowlist in ID e registra la mappatura.
Il matching dell’allowlist gruppi e solo per ID per impostazione predefinita. I nomi non risolti sono ignorati per l’autorizzazione a meno che channels.zalouser.dangerouslyAllowNameMatching: true non sia abilitato.
channels.zalouser.dangerouslyAllowNameMatching: true e una modalita di compatibilita break-glass che riabilita il matching mutabile per nome di gruppo.
Se groupAllowFrom non e impostato, il runtime usa allowFrom come fallback per i controlli mittente dei gruppi.
I controlli sui mittenti si applicano sia ai messaggi normali di gruppo che ai comandi di controllo (ad esempio /new, /reset).

Esempio:

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

Gating menzione per gruppi

channels.zalouser.groups.<group>.requireMention controlla se le risposte nei gruppi richiedono una menzione.
Ordine di risoluzione: ID/nome esatto del gruppo -> slug normalizzato del gruppo -> * -> predefinito (true).
Questo si applica sia ai gruppi in allowlist che alla modalita gruppi aperti.
I comandi di controllo autorizzati (ad esempio /new) possono bypassare il gating menzione.
Quando un messaggio di gruppo viene saltato perche la menzione e richiesta, OpenClaw lo memorizza come storico di gruppo in sospeso e lo include al successivo messaggio di gruppo elaborato.
Il limite dello storico di gruppo e messages.groupChat.historyLimit per impostazione predefinita (fallback 50). Puoi sovrascrivere per account con channels.zalouser.historyLimit.

Esempio:

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

Multi-account

Gli account mappano ai profili zalouser nello stato di OpenClaw. Esempio:

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

Digitazione, reazioni e conferme di consegna

OpenClaw invia un evento di digitazione prima di inviare una risposta (best-effort).
L’azione di reazione react e supportata per zalouser nelle azioni del canale.
- Usa remove: true per rimuovere un emoji di reazione specifico da un messaggio.
- Semantica delle reazioni: Reazioni
Per i messaggi in ingresso che includono metadati degli eventi, OpenClaw invia conferme di consegna + lettura (best-effort).

Risoluzione problemi

Il login non persiste:

openclaw channels status --probe
Rifai il login: openclaw channels logout --channel zalouser && openclaw channels login --channel zalouser

L’allowlist/nome del gruppo non si e risolto:

Usa ID numerici in allowFrom/groupAllowFrom/groups, o nomi esatti di amici/gruppi.

Aggiornamento da vecchio setup basato su CLI:

Rimuovi qualsiasi vecchia dipendenza dal processo esterno zca.
Il canale ora funziona interamente in OpenClaw senza binari CLI esterni.