Zalo personale

Stato: sperimentale. Questa integrazione automatizza un account Zalo personale tramite zca-js nativo, nello stesso processo, senza alcun binario CLI esterno.

Installazione

Zalo Personal è un plugin esterno ufficiale, non incluso nel core. Installalo prima dell'uso:

openclaw plugins install @openclaw/zalouser

• Fissare una versione: openclaw plugins install @openclaw/zalouser@<version>
• Da un checkout del codice sorgente: openclaw plugins install ./path/to/local/zalouser-plugin
• Dettagli: Plugin

Configurazione rapida

1. Installa il plugin (come indicato sopra).
2. Effettua l'accesso (tramite QR, sulla macchina del Gateway):
   • openclaw channels login --channel zalouser
   • Scansiona il codice QR con l'app mobile Zalo.
3. Abilita il canale:

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

4. Riavvia il Gateway (oppure completa la configurazione).
5. Per impostazione predefinita, l'accesso ai messaggi diretti usa l'associazione; approva il codice di associazione al primo contatto.

Che cos'è

• Viene eseguito interamente nello stesso processo tramite la libreria zca-js (senza binari esterni zca/openzca).
• Utilizza listener di eventi nativi (message, error) per ricevere i messaggi in entrata.
• Invia le risposte direttamente tramite l'API JS (testo, contenuti multimediali e collegamenti).
• È progettato per i casi d'uso con un "account personale" nei quali l'API Zalo Bot non è disponibile.

Denominazione

L'ID del canale è zalouser per indicare esplicitamente che automatizza un account utente Zalo personale (in modo non ufficiale). zalo è riservato a una possibile futura integrazione ufficiale con l'API Zalo.

Individuazione degli ID (directory)

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

Limiti

• Il testo in uscita viene suddiviso in blocchi di 2.000 caratteri (limite del client Zalo).
• Lo streaming non è supportato.

Controllo degli accessi (messaggi diretti)

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

channels.zalouser.allowFrom deve utilizzare ID utente Zalo stabili. Può anche fare riferimento a gruppi statici di accesso dei mittenti (accessGroup:<name>). Durante la configurazione interattiva, i nomi inseriti possono essere risolti in ID tramite la ricerca dei contatti interna al processo del plugin.

Se nella configurazione rimane un nome non elaborato, all'avvio viene risolto solo quando è abilitato channels.zalouser.dangerouslyAllowNameMatching: true. Senza questa abilitazione esplicita, i controlli dei mittenti in fase di esecuzione utilizzano esclusivamente gli ID e i nomi non elaborati vengono ignorati ai fini dell'autorizzazione.

Approva tramite:

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

Accesso ai gruppi (facoltativo)

• Valore predefinito: channels.zalouser.groupPolicy = "allowlist" (i gruppi richiedono una voce esplicita nell'elenco consentiti).
• Aprire tutti i gruppi: channels.zalouser.groupPolicy = "open".
• Bloccare tutti i gruppi: channels.zalouser.groupPolicy = "disabled".
• Con groupPolicy = "allowlist":
  • Le chiavi di channels.zalouser.groups devono essere ID di gruppo stabili; i nomi vengono risolti in ID all'avvio solo quando è abilitato channels.zalouser.dangerouslyAllowNameMatching: true.
  • channels.zalouser.groupAllowFrom controlla quali mittenti nei gruppi consentiti possono attivare il bot; è possibile fare riferimento ai gruppi statici di accesso dei mittenti con accessGroup:<name>.
• La procedura guidata di configurazione può richiedere gli elenchi di gruppi consentiti.
• Per impostazione predefinita, la corrispondenza con l'elenco dei gruppi consentiti utilizza esclusivamente gli ID. I nomi non risolti vengono ignorati ai fini dell'autorizzazione, a meno che non sia abilitato channels.zalouser.dangerouslyAllowNameMatching: true.
• channels.zalouser.dangerouslyAllowNameMatching: true è una modalità di compatibilità di emergenza che riabilita la risoluzione all'avvio dei nomi modificabili e la corrispondenza dei nomi dei gruppi in fase di esecuzione.
• Per i normali messaggi di gruppo, groupAllowFrom non utilizza allowFrom come ripiego: se viene lasciato vuoto per un gruppo presente nell'elenco consentiti, qualsiasi mittente può accedere a quel gruppo. I comandi di controllo autorizzati (ad esempio /new) costituiscono un'eccezione; quando groupAllowFrom è vuoto, i controlli sul mittente dei comandi utilizzano allowFrom come ripiego.

Esempio:

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

Attivazione tramite menzione nei gruppi

• channels.zalouser.groups.<group>.requireMention determina se le risposte nei gruppi richiedono una menzione.
• Ordine di risoluzione: ID del gruppo -> alias group:<id> -> nome/slug del gruppo (i candidati basati sul nome si applicano solo quando dangerouslyAllowNameMatching: true) -> * -> valore predefinito (true).
• Si applica sia ai gruppi presenti nell'elenco consentiti sia alla modalità con gruppi aperti.
• Citare un messaggio del bot conta come menzione implicita ai fini dell'attivazione nel gruppo.
• I comandi di controllo autorizzati (ad esempio /new) possono ignorare il requisito della menzione.
• Quando un messaggio di gruppo viene ignorato perché è richiesta una menzione, OpenClaw lo memorizza come cronologia di gruppo in sospeso e lo include nel successivo messaggio di gruppo elaborato.
• Limite della cronologia dei gruppi: channels.zalouser.historyLimit, quindi messages.groupChat.historyLimit, infine un valore di ripiego pari a 50.

Esempio:

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

Account multipli

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

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

Variabili d'ambiente

La selezione del profilo può provenire anche dalle variabili d'ambiente:

I nomi dei profili selezionano le credenziali di accesso a Zalo salvate nello stato di OpenClaw. Ordine di risoluzione:

1. profile esplicito nella configurazione.
2. ZALOUSER_PROFILE.
3. ZCA_PROFILE.
4. L'ID account per gli account non predefiniti oppure default per l'account predefinito.

Per le configurazioni con più account, è preferibile impostare profile per ciascun account nella configurazione, affinché una singola variabile d'ambiente non faccia condividere la stessa sessione di accesso a più account.

Digitazione, reazioni e conferme di consegna

• OpenClaw invia un evento di digitazione prima di inoltrare una risposta (con il massimo impegno possibile).
• L'azione di reazione ai messaggi react è supportata per zalouser nelle azioni del canale.
  • Utilizza remove: true per rimuovere da un messaggio una specifica emoji di reazione.
  • Semantica delle reazioni: Reazioni
• Per i messaggi in entrata che includono i metadati dell'evento, OpenClaw invia conferme di consegna e lettura (con il massimo impegno possibile).

Risoluzione dei problemi

L'accesso non rimane memorizzato:

• openclaw channels status --probe
• Accedi nuovamente: openclaw channels logout --channel zalouser && openclaw channels login --channel zalouser

Il nome nell'elenco consentiti o del gruppo non è stato risolto:

• Utilizza ID numerici in allowFrom/groupAllowFrom e ID di gruppo stabili in groups. Se hai intenzionalmente bisogno di nomi esatti di amici o gruppi, abilita channels.zalouser.dangerouslyAllowNameMatching: true.

Aggiornamento da una vecchia configurazione basata su zca esterno/CLI:

• Rimuovi qualsiasi presupposto relativo a un processo zca esterno; ora il canale viene eseguito interamente nello stesso processo tramite zca-js, senza alcun binario CLI esterno.

Argomenti correlati

• Panoramica dei canali - tutti i canali supportati
• Associazione - autenticazione dei messaggi diretti e flusso di associazione
• Gruppi - comportamento delle chat di gruppo e attivazione tramite menzione
• Instradamento dei canali - instradamento delle sessioni per i messaggi
• Sicurezza - modello di accesso e protezione avanzata