Regional platforms

Zalo

Stato: sperimentale. I DM sono supportati. La sezione Funzionalità qui sotto riflette il comportamento attuale dei bot Marketplace.

Plugin in bundle

Zalo viene distribuito come Plugin in bundle nelle versioni attuali di OpenClaw, quindi le normali build pacchettizzate non richiedono un'installazione separata.

Se usi una build precedente o un'installazione personalizzata che esclude Zalo, installa direttamente il pacchetto npm:

Installa tramite CLI: openclaw plugins install @openclaw/zalo
Versione fissata: openclaw plugins install @openclaw/[email protected]
Oppure da un checkout sorgente: openclaw plugins install ./path/to/local/zalo-plugin
Dettagli: Plugin

Configurazione rapida (principianti)

Assicurati che il Plugin Zalo sia disponibile.
- Le versioni pacchettizzate attuali di OpenClaw lo includono già.
- Le installazioni precedenti/personalizzate possono aggiungerlo manualmente con i comandi sopra.
Imposta il token:
- Env: ZALO_BOT_TOKEN=...
- Oppure configurazione: channels.zalo.accounts.default.botToken: "...".
Riavvia il gateway (o completa la configurazione).
L'accesso DM usa il pairing per impostazione predefinita; approva il codice di pairing al primo contatto.

Configurazione minima:

{
  channels: {
    zalo: {
      enabled: true,
      accounts: {
        default: {
          botToken: "12345689:abc-xyz",
          dmPolicy: "pairing",
        },
      },
    },
  },
}

Che cos'è

Zalo è un'app di messaggistica orientata al Vietnam; la sua Bot API consente al Gateway di eseguire un bot per conversazioni 1:1. È adatta per supporto o notifiche quando vuoi un routing deterministico verso Zalo.

Questa pagina riflette il comportamento attuale di OpenClaw per i bot Zalo Bot Creator / Marketplace. I bot Zalo Official Account (OA) sono una superficie di prodotto Zalo diversa e potrebbero comportarsi diversamente.

Un canale Zalo Bot API posseduto dal Gateway.
Routing deterministico: le risposte tornano a Zalo; il modello non sceglie mai i canali.
I DM condividono la sessione principale dell'agente.
La sezione Funzionalità qui sotto mostra il supporto attuale dei bot Marketplace.

Configurazione (percorso rapido)

1) Crea un token bot (Zalo Bot Platform)

Vai su https://bot.zaloplatforms.com e accedi.
Crea un nuovo bot e configura le sue impostazioni.
Copia il token bot completo (in genere numeric_id:secret). Per i bot Marketplace, il token runtime utilizzabile potrebbe comparire nel messaggio di benvenuto del bot dopo la creazione.

2) Configura il token (env o configurazione)

Esempio:

{
  channels: {
    zalo: {
      enabled: true,
      accounts: {
        default: {
          botToken: "12345689:abc-xyz",
          dmPolicy: "pairing",
        },
      },
    },
  },
}

Se in seguito passi a una superficie bot Zalo in cui i gruppi sono disponibili, puoi aggiungere esplicitamente configurazioni specifiche per i gruppi come groupPolicy e groupAllowFrom. Per il comportamento attuale dei bot Marketplace, vedi Funzionalità.

Opzione env: ZALO_BOT_TOKEN=... (funziona solo per l'account predefinito).

Supporto multi-account: usa channels.zalo.accounts con token per account e name opzionale.

Riavvia il gateway. Zalo si avvia quando viene risolto un token (env o configurazione).
L'accesso DM usa il pairing per impostazione predefinita. Approva il codice quando il bot viene contattato per la prima volta.

Come funziona (comportamento)

I messaggi in ingresso vengono normalizzati nella busta di canale condivisa con placeholder per i media.
Le risposte vengono sempre instradate alla stessa chat Zalo.
Long polling per impostazione predefinita; modalità Webhook disponibile con channels.zalo.webhookUrl.

Limiti

Il testo in uscita viene suddiviso in blocchi da 2000 caratteri (limite API Zalo).
Download/upload dei media sono limitati da channels.zalo.mediaMaxMb (predefinito 5).
Lo streaming è bloccato per impostazione predefinita perché il limite di 2000 caratteri rende lo streaming meno utile.

Controllo accessi (DM)

Accesso DM

Predefinito: channels.zalo.dmPolicy = "pairing". I mittenti sconosciuti ricevono un codice di pairing; i messaggi vengono ignorati finché non vengono approvati (i codici scadono dopo 1 ora).
Approva tramite:
- openclaw pairing list zalo
- openclaw pairing approve zalo <CODE>
Il pairing è lo scambio token predefinito. Dettagli: Pairing
channels.zalo.allowFrom accetta ID utente numerici (non è disponibile la ricerca per nome utente).

Controllo accessi (gruppi)

Per i bot Zalo Bot Creator / Marketplace, il supporto gruppi non era disponibile in pratica perché il bot non poteva essere aggiunto a nessun gruppo.

Questo significa che le chiavi di configurazione relative ai gruppi qui sotto esistono nello schema, ma non erano utilizzabili per i bot Marketplace:

channels.zalo.groupPolicy controlla la gestione dei messaggi in ingresso nei gruppi: open | allowlist | disabled.
channels.zalo.groupAllowFrom limita quali ID mittente possono attivare il bot nei gruppi.
Se groupAllowFrom non è impostato, Zalo ripiega su allowFrom per i controlli del mittente.
Nota runtime: se channels.zalo manca completamente, il runtime ripiega comunque su groupPolicy="allowlist" per sicurezza.

I valori della policy di gruppo (quando l'accesso ai gruppi è disponibile sulla tua superficie bot) sono:

groupPolicy: "disabled" — blocca tutti i messaggi di gruppo.
groupPolicy: "open" — consente qualsiasi membro del gruppo (vincolato alla menzione).
groupPolicy: "allowlist" — impostazione predefinita fail-closed; sono accettati solo i mittenti consentiti.

Se usi una superficie di prodotto bot Zalo diversa e hai verificato un comportamento dei gruppi funzionante, documentalo separatamente invece di presumere che corrisponda al flusso dei bot Marketplace.

Long polling vs Webhook

Predefinito: long polling (nessun URL pubblico richiesto).
Modalità Webhook: imposta channels.zalo.webhookUrl e channels.zalo.webhookSecret.
- Il segreto Webhook deve essere di 8-256 caratteri.
- L'URL Webhook deve usare HTTPS.
- Zalo invia eventi con l'intestazione X-Bot-Api-Secret-Token per la verifica.
- L'HTTP del Gateway gestisce le richieste Webhook in channels.zalo.webhookPath (per impostazione predefinita il percorso dell'URL Webhook).
- Le richieste devono usare Content-Type: application/json (o tipi media +json).
- Gli eventi duplicati (event_name + message_id) vengono ignorati per una breve finestra di replay.
- Il traffico a raffica è soggetto a rate limit per percorso/origine e può restituire HTTP 429.

Nota: getUpdates (polling) e Webhook si escludono a vicenda secondo la documentazione API Zalo.

Tipi di messaggi supportati

Per una rapida panoramica del supporto, vedi Funzionalità. Le note qui sotto aggiungono dettagli dove il comportamento richiede ulteriore contesto.

Messaggi di testo: supporto completo con suddivisione in blocchi da 2000 caratteri.
URL semplici nel testo: si comportano come normale input testuale.
Anteprime link / schede link avanzate: vedi lo stato dei bot Marketplace in Funzionalità; non attivavano in modo affidabile una risposta.
Messaggi immagine: vedi lo stato dei bot Marketplace in Funzionalità; la gestione delle immagini in ingresso era inaffidabile (indicatore di digitazione senza risposta finale).
Sticker: vedi lo stato dei bot Marketplace in Funzionalità.
Note vocali / file audio / video / allegati file generici: vedi lo stato dei bot Marketplace in Funzionalità.
Tipi non supportati: registrati nei log (per esempio, messaggi da utenti protetti).

Funzionalità

Questa tabella riassume il comportamento attuale dei bot Zalo Bot Creator / Marketplace in OpenClaw.

Funzionalità	Stato
Messaggi diretti	✅ Supportati
Gruppi	❌ Non disponibili per i bot Marketplace
Media (immagini in ingresso)	⚠️ Limitato / verifica nel tuo ambiente
Media (immagini in uscita)	⚠️ Non ritestato per i bot Marketplace
URL semplici nel testo	✅ Supportati
Anteprime link	⚠️ Inaffidabili per i bot Marketplace
Reazioni	❌ Non supportate
Sticker	⚠️ Nessuna risposta agente per i bot Marketplace
Note vocali / audio / video	⚠️ Nessuna risposta agente per i bot Marketplace
Allegati file	⚠️ Nessuna risposta agente per i bot Marketplace
Thread	❌ Non supportati
Sondaggi	❌ Non supportati
Comandi nativi	❌ Non supportati
Streaming	⚠️ Bloccato (limite di 2000 caratteri)

Destinazioni di consegna (CLI/cron)

Usa un ID chat come destinazione.
Esempio: openclaw message send --channel zalo --target 123456789 --message "hi".

Risoluzione dei problemi

Il bot non risponde:

Controlla che il token sia valido: openclaw channels status --probe
Verifica che il mittente sia approvato (pairing o allowFrom)
Controlla i log del gateway: openclaw logs --follow

Il Webhook non riceve eventi:

Assicurati che l'URL Webhook usi HTTPS
Verifica che il token segreto sia di 8-256 caratteri
Conferma che l'endpoint HTTP del gateway sia raggiungibile sul percorso configurato
Controlla che il polling getUpdates non sia in esecuzione (si escludono a vicenda)

Riferimento configurazione (Zalo)

Configurazione completa: Configurazione

Le chiavi piatte di primo livello (channels.zalo.botToken, channels.zalo.dmPolicy e simili) sono una scorciatoia legacy per account singolo. Preferisci channels.zalo.accounts.<id>.* per le nuove configurazioni. Entrambe le forme sono ancora documentate qui perché esistono nello schema.

Opzioni provider:

channels.zalo.enabled: abilita/disabilita l'avvio del canale.
channels.zalo.botToken: token bot da Zalo Bot Platform.
channels.zalo.tokenFile: legge il token da un percorso file regolare. I symlink sono rifiutati.
channels.zalo.dmPolicy: pairing | allowlist | open | disabled (predefinito: pairing).
channels.zalo.allowFrom: allowlist DM (ID utente). open richiede "*". La procedura guidata chiederà ID numerici.
channels.zalo.groupPolicy: open | allowlist | disabled (predefinito: allowlist). Presente nella configurazione; vedi Funzionalità e Controllo accessi (gruppi) per il comportamento attuale dei bot Marketplace.
channels.zalo.groupAllowFrom: allowlist dei mittenti di gruppo (ID utente). Ripiega su allowFrom quando non impostato.
channels.zalo.mediaMaxMb: limite media in ingresso/uscita (MB, predefinito 5).
channels.zalo.webhookUrl: abilita la modalità Webhook (HTTPS richiesto).
channels.zalo.webhookSecret: segreto Webhook (8-256 caratteri).
channels.zalo.webhookPath: percorso Webhook sul server HTTP del gateway.
channels.zalo.proxy: URL proxy per le richieste API.

Opzioni multi-account:

channels.zalo.accounts.<id>.botToken: token per account.
channels.zalo.accounts.<id>.tokenFile: file token regolare per account. I symlink sono rifiutati.
channels.zalo.accounts.<id>.name: nome visualizzato.
channels.zalo.accounts.<id>.enabled: abilita/disabilita l'account.
channels.zalo.accounts.<id>.dmPolicy: policy DM per account.
channels.zalo.accounts.<id>.allowFrom: allowlist per account.
channels.zalo.accounts.<id>.groupPolicy: policy di gruppo per account. Presente nella configurazione; vedi Funzionalità e Controllo accessi (gruppi) per il comportamento attuale dei bot Marketplace.
channels.zalo.accounts.<id>.groupAllowFrom: allowlist dei mittenti di gruppo per account.
channels.zalo.accounts.<id>.webhookUrl: URL Webhook per account.
channels.zalo.accounts.<id>.webhookSecret: segreto Webhook per account.
channels.zalo.accounts.<id>.webhookPath: percorso Webhook per account.
channels.zalo.accounts.<id>.proxy: URL proxy per account.

Correlati

Panoramica canali — tutti i canali supportati
Pairing — autenticazione DM e flusso di pairing
Gruppi — comportamento delle chat di gruppo e gating tramite menzione
Routing canali — routing delle sessioni per i messaggi
Sicurezza — modello di accesso e hardening

# Plugin in bundle

# Configurazione rapida (principianti)

# Che cos'è

# Configurazione (percorso rapido)

# 1) Crea un token bot (Zalo Bot Platform)

# 2) Configura il token (env o configurazione)

# Come funziona (comportamento)

# Limiti

# Controllo accessi (DM)

# Accesso DM

# Controllo accessi (gruppi)

# Long polling vs Webhook

# Tipi di messaggi supportati

# Funzionalità

# Destinazioni di consegna (CLI/cron)

# Risoluzione dei problemi

# Riferimento configurazione (Zalo)

# Correlati