Zalo personale

​

Installazione

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

​

Individuazione degli ID (directory)

openclaw directory self --channel zalouser
openclaw 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)

• 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.

{
  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.

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

​

Account multipli

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

​

Variabili d’ambiente

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.

​

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

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

• 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.

• 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