WhatsApp (canale Web)

Stato: pronto per la produzione tramite WhatsApp Web (Baileys). Il gateway gestisce le sessioni collegate.

Installazione (su richiesta)

L’onboarding (openclaw onboard) e openclaw channels add --channel whatsapp chiedono di installare il plugin WhatsApp la prima volta che lo selezioni.
openclaw channels login --channel whatsapp offre anche il flusso di installazione quando il plugin non è ancora presente.
Canale dev + checkout git: per impostazione predefinita usa il percorso del plugin locale.
Stable/Beta: per impostazione predefinita usa il pacchetto npm @openclaw/whatsapp.

L’installazione manuale resta disponibile:

openclaw plugins install @openclaw/whatsapp

Abbinamento

Il criterio predefinito per i DM è l’abbinamento per i mittenti sconosciuti.

Risoluzione dei problemi del canale

Diagnostica cross-channel e procedure di ripristino.

Configurazione del gateway

Modelli ed esempi completi di configurazione del canale.

Configurazione rapida

Configura il criterio di accesso WhatsApp

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing",
      allowFrom: ["+15551234567"],
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
    },
  },
}

Collega WhatsApp (QR)

openclaw channels login --channel whatsapp

Per un account specifico:

openclaw channels login --channel whatsapp --account work

Avvia il gateway

openclaw gateway

Approva la prima richiesta di abbinamento (se usi la modalità pairing)

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>

Le richieste di abbinamento scadono dopo 1 ora. Le richieste in sospeso sono limitate a 3 per canale.

OpenClaw consiglia di eseguire WhatsApp su un numero separato quando possibile. (I metadati del canale e il flusso di configurazione sono ottimizzati per questa configurazione, ma sono supportate anche configurazioni con numero personale.)

Modelli di distribuzione

Numero dedicato (consigliato)

Questa è la modalità operativa più pulita:

identità WhatsApp separata per OpenClaw
allowlist dei DM e confini di instradamento più chiari
minore probabilità di confusione con le chat verso sé stessi

Modello di criterio minimo:

{
  channels: {
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15551234567"],
    },
  },
}

Fallback con numero personale

L’onboarding supporta la modalità numero personale e scrive una baseline adatta alla chat con sé stessi:

dmPolicy: "allowlist"
allowFrom include il tuo numero personale
selfChatMode: true

In fase di esecuzione, le protezioni per la chat con sé stessi si basano sul numero proprio collegato e su allowFrom.

Ambito del canale solo WhatsApp Web

Il canale della piattaforma di messaggistica è basato su WhatsApp Web (Baileys) nell’attuale architettura dei canali di OpenClaw.Non esiste un canale di messaggistica WhatsApp Twilio separato nel registro integrato dei canali chat.

Modello di runtime

Il gateway gestisce il socket WhatsApp e il ciclo di riconnessione.
Gli invii in uscita richiedono un listener WhatsApp attivo per l’account di destinazione.
Le chat di stato e broadcast vengono ignorate (@status, @broadcast).
Le chat dirette usano le regole di sessione DM (session.dmScope; il valore predefinito main comprime i DM nella sessione principale dell’agente).
Le sessioni di gruppo sono isolate (agent:<agentId>:whatsapp:group:<jid>).
Il trasporto WhatsApp Web rispetta le variabili d’ambiente proxy standard sull’host gateway (HTTPS_PROXY, HTTP_PROXY, NO_PROXY / varianti minuscole). Preferisci la configurazione proxy a livello host rispetto alle impostazioni proxy WhatsApp specifiche del canale.

Controllo degli accessi e attivazione

Criterio DM
Criterio gruppo + allowlist
Menzioni + /activation

channels.whatsapp.dmPolicy controlla l’accesso alle chat dirette:

pairing (predefinito)
allowlist
open (richiede che allowFrom includa "*")
disabled

allowFrom accetta numeri in stile E.164 (normalizzati internamente).Override multi-account: channels.whatsapp.accounts.<id>.dmPolicy (e allowFrom) hanno la precedenza sui valori predefiniti a livello di canale per quell’account.Dettagli del comportamento in runtime:

gli abbinamenti vengono mantenuti nell’allow-store del canale e uniti con allowFrom configurato
se non è configurata alcuna allowlist, il numero proprio collegato è consentito per impostazione predefinita
i DM in uscita fromMe non vengono mai abbinati automaticamente

L’accesso ai gruppi ha due livelli:

Allowlist di appartenenza al gruppo (channels.whatsapp.groups)
- se groups è omesso, tutti i gruppi sono idonei
- se groups è presente, agisce come allowlist di gruppo ("*" consentito)
Criterio mittente del gruppo (channels.whatsapp.groupPolicy + groupAllowFrom)
- open: l’allowlist del mittente viene bypassata
- allowlist: il mittente deve corrispondere a groupAllowFrom (o *)
- disabled: blocca tutto il traffico in entrata dei gruppi

Fallback dell’allowlist del mittente:

se groupAllowFrom non è impostato, il runtime usa allowFrom come fallback quando disponibile
le allowlist del mittente vengono valutate prima dell’attivazione per menzione/risposta

Nota: se non esiste affatto alcun blocco channels.whatsapp, il fallback del criterio di gruppo in runtime è allowlist (con un log di avviso), anche se channels.defaults.groupPolicy è impostato.

Le risposte nei gruppi richiedono una menzione per impostazione predefinita.Il rilevamento delle menzioni include:

menzioni WhatsApp esplicite dell’identità del bot
pattern regex di menzione configurati (agents.list[].groupChat.mentionPatterns, fallback messages.groupChat.mentionPatterns)
rilevamento implicito della risposta al bot (il mittente della risposta corrisponde all’identità del bot)

Nota di sicurezza:

la citazione/risposta soddisfa solo il gating della menzione; non concede l’autorizzazione al mittente
con groupPolicy: "allowlist", i mittenti non presenti nell’allowlist restano bloccati anche se rispondono al messaggio di un utente presente nell’allowlist

Comando di attivazione a livello di sessione:

/activation mention
/activation always

activation aggiorna lo stato della sessione (non la configurazione globale). È protetto dal proprietario.

Numero personale e comportamento della chat con sé stessi

Quando il numero proprio collegato è presente anche in allowFrom, si attivano le salvaguardie della chat con sé stessi di WhatsApp:

salta le conferme di lettura per i turni di chat con sé stessi
ignora il comportamento di attivazione automatica mention-JID che altrimenti farebbe ping a te stesso
se messages.responsePrefix non è impostato, le risposte della chat con sé stessi usano per impostazione predefinita [{identity.name}] o [openclaw]

Normalizzazione dei messaggi e contesto

Envelope in ingresso + contesto della risposta

I messaggi WhatsApp in arrivo vengono racchiusi nell’envelope condiviso in ingresso.Se esiste una risposta citata, il contesto viene aggiunto in questa forma:

[Replying to <sender> id:<stanzaId>]
<quoted body or media placeholder>
[/Replying]

Anche i campi dei metadati della risposta vengono popolati quando disponibili (ReplyToId, ReplyToBody, ReplyToSender, sender JID/E.164).

Placeholder multimediali ed estrazione di posizione/contatto

I messaggi in ingresso contenenti solo media vengono normalizzati con placeholder come:

<media:image>
<media:video>
<media:audio>
<media:document>
<media:sticker>

I payload di posizione e contatto vengono normalizzati in contesto testuale prima dell’instradamento.

Iniezione della cronologia di gruppo in sospeso

Per i gruppi, i messaggi non elaborati possono essere messi in buffer e iniettati come contesto quando il bot viene infine attivato.

limite predefinito: 50
configurazione: channels.whatsapp.historyLimit
fallback: messages.groupChat.historyLimit
0 disabilita

Marcatori di iniezione:

[Chat messages since your last reply - for context]
[Current message - respond to this]

Conferme di lettura

Le conferme di lettura sono abilitate per impostazione predefinita per i messaggi WhatsApp in ingresso accettati.Disabilita globalmente:

{
  channels: {
    whatsapp: {
      sendReadReceipts: false,
    },
  },
}

Override per account:

{
  channels: {
    whatsapp: {
      accounts: {
        work: {
          sendReadReceipts: false,
        },
      },
    },
  },
}

I turni di chat con sé stessi saltano le conferme di lettura anche quando sono abilitate globalmente.

Consegna, suddivisione e media

Suddivisione del testo

limite predefinito dei blocchi: channels.whatsapp.textChunkLimit = 4000
channels.whatsapp.chunkMode = "length" | "newline"
la modalità newline privilegia i confini dei paragrafi (righe vuote), poi usa come fallback una suddivisione sicura per lunghezza

Comportamento dei media in uscita

supporta payload di immagini, video, audio (messaggi vocali PTT) e documenti
audio/ogg viene riscritto in audio/ogg; codecs=opus per compatibilità con i messaggi vocali
la riproduzione di GIF animate è supportata tramite gifPlayback: true negli invii video
le didascalie vengono applicate al primo elemento multimediale quando si inviano payload di risposta con più media
la sorgente dei media può essere HTTP(S), file:// o percorsi locali

Limiti di dimensione dei media e comportamento di fallback

limite di salvataggio dei media in ingresso: channels.whatsapp.mediaMaxMb (predefinito 50)
limite di invio dei media in uscita: channels.whatsapp.mediaMaxMb (predefinito 50)
gli override per account usano channels.whatsapp.accounts.<accountId>.mediaMaxMb
le immagini vengono ottimizzate automaticamente (ridimensionamento/scansione qualità) per rientrare nei limiti
in caso di errore nell’invio dei media, il fallback sul primo elemento invia un avviso testuale invece di scartare silenziosamente la risposta

Livello di reazione

channels.whatsapp.reactionLevel controlla quanto ampiamente l’agente usa le reazioni emoji su WhatsApp:

Livello	Reazioni ack	Reazioni avviate dall’agente	Descrizione
`"off"`	No	No	Nessuna reazione
`"ack"`	Sì	No	Solo reazioni ack (ricezione pre-risposta)
`"minimal"`	Sì	Sì (conservative)	Ack + reazioni dell’agente con guida prudente
`"extensive"`	Sì	Sì (encouraged)	Ack + reazioni dell’agente con guida incoraggiante

Predefinito: "minimal". Gli override per account usano channels.whatsapp.accounts.<id>.reactionLevel.

{
  channels: {
    whatsapp: {
      reactionLevel: "ack",
    },
  },
}

Reazioni di conferma

WhatsApp supporta reazioni ack immediate alla ricezione in ingresso tramite channels.whatsapp.ackReaction. Le reazioni ack sono controllate da reactionLevel: vengono soppresse quando reactionLevel è "off".

{
  channels: {
    whatsapp: {
      ackReaction: {
        emoji: "👀",
        direct: true,
        group: "mentions", // always | mentions | never
      },
    },
  },
}

Note sul comportamento:

inviate immediatamente dopo l’accettazione dell’evento in ingresso (pre-risposta)
gli errori vengono registrati nei log ma non bloccano la normale consegna della risposta
la modalità gruppo mentions reagisce nei turni attivati da menzione; l’attivazione di gruppo always funge da bypass per questo controllo
WhatsApp usa channels.whatsapp.ackReaction (il legacy messages.ackReaction qui non viene usato)

Multi-account e credenziali

Selezione dell'account e valori predefiniti

gli ID account provengono da channels.whatsapp.accounts
selezione dell’account predefinito: default se presente, altrimenti il primo ID account configurato (ordinato)
gli ID account vengono normalizzati internamente per la ricerca

Percorsi delle credenziali e compatibilità legacy

percorso di autenticazione corrente: ~/.openclaw/credentials/whatsapp/<accountId>/creds.json
file di backup: creds.json.bak
l’autenticazione legacy predefinita in ~/.openclaw/credentials/ è ancora riconosciuta/migrata per i flussi dell’account predefinito

Comportamento del logout

openclaw channels logout --channel whatsapp [--account <id>] cancella lo stato di autenticazione WhatsApp per quell’account.Nelle directory di autenticazione legacy, oauth.json viene preservato mentre i file di autenticazione Baileys vengono rimossi.

Strumenti, azioni e scritture di configurazione

Il supporto strumenti dell’agente include l’azione di reazione WhatsApp (react).
Gate delle azioni:
- channels.whatsapp.actions.reactions
- channels.whatsapp.actions.polls
Le scritture di configurazione avviate dal canale sono abilitate per impostazione predefinita (disabilita tramite channels.whatsapp.configWrites=false).

Risoluzione dei problemi

Non collegato (QR richiesto)

Sintomo: lo stato del canale segnala non collegato.Correzione:

openclaw channels login --channel whatsapp
openclaw channels status

Collegato ma disconnesso / ciclo di riconnessione

Sintomo: account collegato con disconnessioni ripetute o tentativi di riconnessione.Correzione:

openclaw doctor
openclaw logs --follow

Se necessario, ricollega con channels login.

Nessun listener attivo durante l'invio

Gli invii in uscita falliscono immediatamente quando non esiste alcun listener gateway attivo per l’account di destinazione.Assicurati che il gateway sia in esecuzione e che l’account sia collegato.

Messaggi di gruppo ignorati in modo imprevisto

Controlla in questo ordine:

groupPolicy
groupAllowFrom / allowFrom
voci dell’allowlist groups
gating della menzione (requireMention + pattern di menzione)
chiavi duplicate in openclaw.json (JSON5): le voci successive sovrascrivono quelle precedenti, quindi mantieni un solo groupPolicy per ambito

Avviso runtime Bun

Il runtime del gateway WhatsApp dovrebbe usare Node. Bun è segnalato come incompatibile per il funzionamento stabile del gateway WhatsApp/Telegram.

Riferimenti alla configurazione

Riferimento principale:

Riferimento configurazione - WhatsApp

Campi WhatsApp ad alto segnale:

accesso: dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups
consegna: textChunkLimit, chunkMode, mediaMaxMb, sendReadReceipts, ackReaction, reactionLevel
multi-account: accounts.<id>.enabled, accounts.<id>.authDir, override a livello account
operazioni: configWrites, debounceMs, web.enabled, web.heartbeatSeconds, web.reconnect.*
comportamento della sessione: session.dmScope, historyLimit, dmHistoryLimit, dms.<id>.historyLimit

Overview

Messaging platforms

Configuration

WhatsApp

WhatsApp (canale Web)

Installazione (su richiesta)

Abbinamento

Risoluzione dei problemi del canale

Configurazione del gateway

Configurazione rapida

Modelli di distribuzione

Modello di runtime

Controllo degli accessi e attivazione

Numero personale e comportamento della chat con sé stessi

Normalizzazione dei messaggi e contesto

Consegna, suddivisione e media

Livello di reazione

Reazioni di conferma

Multi-account e credenziali

Strumenti, azioni e scritture di configurazione

Risoluzione dei problemi

Riferimenti alla configurazione

Correlati

Overview

Messaging platforms

Configuration

​WhatsApp (canale Web)

​Installazione (su richiesta)

Abbinamento

Risoluzione dei problemi del canale

Configurazione del gateway

​Configurazione rapida

​Modelli di distribuzione

​Modello di runtime

​Controllo degli accessi e attivazione

​Numero personale e comportamento della chat con sé stessi

​Normalizzazione dei messaggi e contesto

​Consegna, suddivisione e media

​Livello di reazione

​Reazioni di conferma

​Multi-account e credenziali

​Strumenti, azioni e scritture di configurazione

​Risoluzione dei problemi

​Riferimenti alla configurazione

​Correlati

WhatsApp (canale Web)

Installazione (su richiesta)

Configurazione rapida

Modelli di distribuzione

Modello di runtime

Controllo degli accessi e attivazione

Numero personale e comportamento della chat con sé stessi

Normalizzazione dei messaggi e contesto

Consegna, suddivisione e media

Livello di reazione

Reazioni di conferma

Multi-account e credenziali

Strumenti, azioni e scritture di configurazione

Risoluzione dei problemi

Riferimenti alla configurazione

Correlati