WhatsApp

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: usa per impostazione predefinita il percorso del Plugin locale.
• Stable/Beta: installa prima il Plugin ufficiale @openclaw/whatsapp da ClawHub, con npm come fallback.
• Il runtime WhatsApp è distribuito al di fuori del pacchetto npm core di OpenClaw, così le dipendenze di runtime specifiche di WhatsApp restano nel Plugin esterno.

L'installazione manuale resta disponibile:

openclaw plugins install clawhub:@openclaw/whatsapp

Usa il pacchetto npm semplice (@openclaw/whatsapp) solo quando hai bisogno del fallback del registro. Fissa una versione esatta solo quando hai bisogno di un'installazione riproducibile.

Configurazione rapida

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

openclaw channels login --channel whatsapp

openclaw channels login --channel whatsapp --account work

openclaw channels add --channel whatsapp --account work --auth-dir /path/to/wa-authopenclaw channels login --channel whatsapp --account work

openclaw gateway

openclaw pairing list whatsappopenclaw pairing approve whatsapp <CODE>

Chiamare il richiedente corrente con MeowCaller (sperimentale)

Il Plugin WhatsApp può esporre whatsapp_call nei turni dell'agente originati da WhatsApp. Lo strumento usa MeowCaller per effettuare una chiamata vocale WhatsApp al richiedente autorizzato corrente e riproduce un messaggio TTS di OpenClaw dopo la risposta. Lo strumento non accetta un numero di destinazione, quindi un prompt non può reindirizzare la chiamata a terzi. Questa funzionalità sperimentale è disabilitata per impostazione predefinita.

{"channels": {"whatsapp": {  "actions": {    "calls": true  }}}}

git clone --branch feat/send-only-notify https://github.com/steipete/meowcaller.gitcd meowcallergit checkout 752050471fc2bf7a8cdfbf7dbd3cd4e865d85d3fmkdir -p "$HOME/.local/bin"go build -o "$HOME/.local/bin/meowcaller" ./cmd/meowcaller

state_dir="$HOME/.openclaw/credentials/whatsapp-calls/default"mkdir -p "$state_dir"chmod 700 "$state_dir"meowcaller pair --store "$state_dir/wa-voip.db"

Limiti attuali:

• solo chiamate audio in uscita uno-a-uno
• nessun numero di destinazione arbitrario
• nessuna autenticazione condivisa con la connessione chat
• nessuna autochiamata dalla modalità numero personale/self-chat
• l'audio sintetizzato è limitato a 60 secondi
• nessuna ricevuta di udibilità lato telefono oltre al completamento di risposta/riproduzione/riaggancio di MeowCaller
• OpenClaw arresta il processo companion dopo una finestra limitata di 115-175 secondi, incluse le fasi di connessione, risposta, riproduzione e arresto di MeowCaller

Pattern di distribuzione

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

Modello runtime

• Il Gateway gestisce il socket WhatsApp e il ciclo di riconnessione.
• Il watchdog di riconnessione usa l'attività del trasporto WhatsApp Web, non solo il volume di messaggi app in ingresso, quindi una sessione di dispositivo collegato silenziosa non viene riavviata solo perché nessuno ha inviato un messaggio di recente. Un limite più lungo di silenzio applicativo forza comunque una riconnessione se i frame di trasporto continuano ad arrivare ma nessun messaggio applicativo viene gestito per la finestra del watchdog; dopo una riconnessione transitoria per una sessione attiva di recente, quel controllo di silenzio applicativo usa il normale timeout dei messaggi per la prima finestra di ripristino.
• I timing del socket Baileys sono espliciti sotto web.whatsapp.*: keepAliveIntervalMs controlla i ping applicativi di WhatsApp Web, connectTimeoutMs controlla il timeout dell'handshake di apertura e defaultQueryTimeoutMs controlla le attese delle query Baileys più i limiti locali di OpenClaw per invio/presenza in uscita e operazioni di conferma di lettura in ingresso.
• Gli invii in uscita richiedono un listener WhatsApp attivo per l'account di destinazione.
• Gli invii di gruppo allegano metadati di menzione nativi per token @+<digits> e @<digits> nel testo e nelle didascalie dei media quando il token corrisponde ai metadati dei partecipanti WhatsApp correnti, inclusi i gruppi basati su LID.
• Le chat di stato e broadcast vengono ignorate (@status, @broadcast).
• Il watchdog di riconnessione segue l'attività del trasporto WhatsApp Web, non solo il volume di messaggi app in ingresso: le sessioni di dispositivo collegato silenziose restano attive mentre i frame di trasporto continuano, ma uno stallo del trasporto forza la riconnessione ben prima del successivo percorso di disconnessione remota.
• Le chat dirette usano le regole di sessione DM (session.dmScope; il valore predefinito main accorpa i DM alla sessione principale dell'agente).
• Le sessioni di gruppo sono isolate (agent:<agentId>:whatsapp:group:<jid>).
• I Canali/Newsletter WhatsApp possono essere destinazioni in uscita esplicite con il loro JID nativo @newsletter. Gli invii di newsletter in uscita usano metadati di sessione del canale (agent:<agentId>:whatsapp:channel:<jid>) invece della semantica di sessione DM.
• Il trasporto WhatsApp Web rispetta le variabili d'ambiente proxy standard sull'host del Gateway (HTTPS_PROXY, HTTP_PROXY, NO_PROXY / varianti minuscole). Preferisci la configurazione proxy a livello host rispetto alle impostazioni proxy WhatsApp specifiche del canale.
• Quando messages.removeAckAfterReply è abilitato, OpenClaw cancella la reazione di ack WhatsApp dopo la consegna di una risposta visibile.

Prompt di approvazione

WhatsApp può renderizzare prompt di approvazione per exec e Plugin con reazioni 👍 / 👎. La consegna è controllata dalla configurazione di inoltro approvazioni di livello superiore:

{  approvals: {    exec: {      enabled: true,      mode: "session",    },    plugin: {      enabled: true,      mode: "targets",      targets: [{ channel: "whatsapp", to: "+15551234567" }],    },  },}

approvals.exec e approvals.plugin sono indipendenti. Abilitare WhatsApp come canale collega solo il trasporto; non invia prompt di approvazione a meno che la famiglia di approvazioni corrispondente sia abilitata e instradi verso WhatsApp. La modalità session consegna approvazioni emoji native solo per approvazioni che hanno origine da WhatsApp. La modalità target usa la pipeline di inoltro condivisa per target WhatsApp espliciti e non crea un fanout separato di DM approvatore.

Le reazioni di approvazione WhatsApp richiedono approvatori WhatsApp espliciti da allowFrom o "*". defaultTo controlla i normali target predefiniti dei messaggi; non è un approvatore di approvazioni. I comandi manuali /approve passano comunque attraverso il normale percorso di autorizzazione del mittente WhatsApp prima della risoluzione dell'approvazione.

Hook del Plugin e privacy

I messaggi in ingresso di WhatsApp possono contenere contenuto personale dei messaggi, numeri di telefono, identificatori di gruppo, nomi dei mittenti e campi di correlazione della sessione. Per questo motivo, WhatsApp non trasmette i payload degli hook message_received in ingresso ai plugin a meno che tu non acconsenta esplicitamente:

{  channels: {    whatsapp: {      pluginHooks: {        messageReceived: true,      },    },  },}

Puoi limitare il consenso a un account:

{  channels: {    whatsapp: {      accounts: {        work: {          pluginHooks: {            messageReceived: true,          },        },      },    },  },}

Abilitalo solo per i plugin che ritieni affidabili per ricevere contenuti e identificatori dei messaggi WhatsApp in ingresso.

Controllo degli accessi e attivazione

Binding ACP configurati

WhatsApp supporta binding ACP persistenti con voci bindings[] di primo livello:

{  bindings: [    {      type: "acp",      agentId: "codex",      match: {        channel: "whatsapp",        accountId: "work",        peer: { kind: "direct", id: "+15555550123" },      },    },    {      type: "acp",      agentId: "codex",      match: {        channel: "whatsapp",        accountId: "work",        peer: { kind: "group", id: "120363424282127706@g.us" },      },    },  ],}

• Le chat dirette corrispondono a numeri E.164 come +15555550123.
• I gruppi corrispondono a JID di gruppi WhatsApp come 120363424282127706@g.us.
• Allowlist dei gruppi, criterio dei mittenti e gating tramite menzione o attivazione vengono eseguiti prima che OpenClaw garantisca l'esistenza della sessione ACP configurata.
• Un binding ACP configurato corrispondente possiede la route. I gruppi broadcast WhatsApp non distribuiscono quel turno alle normali sessioni WhatsApp.

Comportamento del numero personale e della chat con se stessi

Quando il numero personale collegato è presente anche in allowFrom, si attivano le protezioni per la chat con se stessi di WhatsApp:

• salta le conferme di lettura per i turni di chat con se stessi
• ignora il comportamento di attivazione automatica mention-JID che altrimenti ti invierebbe un ping
• se messages.responsePrefix non è impostato, le risposte nella chat con se stessi usano per impostazione predefinita [{identity.name}] o [openclaw]

Normalizzazione dei messaggi e contesto

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

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

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

Consegna, suddivisione in blocchi e media

Citazione nelle risposte

WhatsApp supporta la citazione nativa nelle risposte, in cui le risposte in uscita citano visibilmente il messaggio in ingresso. Controllala con channels.whatsapp.replyToMode.

Il valore predefinito è "off". Gli override per account usano channels.whatsapp.accounts.<id>.replyToMode.

{  channels: {    whatsapp: {      replyToMode: "first",    },  },}

Livello di reazione

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

Predefinito: "minimal".

Gli override per account usano channels.whatsapp.accounts.<id>.reactionLevel.

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

Reazioni di riconoscimento

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

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

Note sul comportamento:

• inviata immediatamente dopo l'accettazione del messaggio in ingresso (prima della risposta)
• se ackReaction è presente senza emoji, WhatsApp usa l'emoji identità dell'agente instradato, ripiegando su "👀"; ometti ackReaction o imposta emoji: "" per non inviare alcuna reazione di conferma
• 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 gruppo always agisce come bypass per questo controllo
• WhatsApp usa channels.whatsapp.ackReaction (il legacy messages.ackReaction non viene usato qui)

Reazioni di stato del ciclo di vita

Imposta messages.statusReactions.enabled: true per consentire a WhatsApp di sostituire la reazione di conferma durante un turno invece di lasciare un'emoji di ricevuta statica. Quando è abilitato, OpenClaw usa lo stesso slot di reazione del messaggio in ingresso per gli stati del ciclo di vita come in coda, ragionamento, attività degli strumenti, Compaction, completato ed errore.

{  messages: {    statusReactions: {      enabled: true,      emojis: {        deploy: "🛫",        build: "🏗️",        concierge: "💁",      },    },  },}

Note sul comportamento:

• channels.whatsapp.ackReaction controlla comunque se le reazioni di stato sono idonee per messaggi diretti e gruppi.
• La reazione di stato in coda usa la stessa emoji di conferma effettiva delle reazioni di conferma semplici.
• WhatsApp ha uno slot di reazione bot per messaggio, quindi gli aggiornamenti del ciclo di vita sostituiscono sul posto la reazione corrente.
• messages.removeAckAfterReply: true cancella la reazione di stato finale dopo il mantenimento completato/errore configurato.
• Le categorie di emoji degli strumenti includono tool, coding, web, deploy, build e concierge.

Multi-account e credenziali

Strumenti, azioni e scritture della 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 della configurazione avviate dal canale sono abilitate per impostazione predefinita (disabilitale tramite channels.whatsapp.configWrites=false).

Risoluzione dei problemi

openclaw channels login --channel whatsappopenclaw channels status

{  web: {    whatsapp: {      keepAliveIntervalMs: 15000,      connectTimeoutMs: 60000,      defaultQueryTimeoutMs: 60000,    },  },}

openclaw channels status --probeopenclaw doctoropenclaw logs --followopenclaw gateway status

cp -a ~/.openclaw/credentials/whatsapp/<accountId> \  ~/.openclaw/credentials/whatsapp/<accountId>.bakopenclaw channels logout --channel whatsapp --account <accountId>openclaw channels login --channel whatsapp --account <accountId>

Prompt di sistema

WhatsApp supporta prompt di sistema in stile Telegram per gruppi e chat dirette tramite le mappe groups e direct.

Gerarchia di risoluzione per i messaggi di gruppo:

La mappa groups effettiva viene determinata per prima: se l'account definisce i propri groups, sostituisce completamente la mappa groups root (nessun deep merge). La ricerca del prompt viene quindi eseguita sulla singola mappa risultante:

1. Prompt di sistema specifico del gruppo (groups["<groupId>"].systemPrompt): usato quando la voce del gruppo specifico esiste nella mappa e la sua chiave systemPrompt è definita. Se systemPrompt è una stringa vuota (""), il wildcard viene soppresso e non viene applicato alcun prompt di sistema.
2. Prompt di sistema wildcard del gruppo (groups["*"].systemPrompt): usato quando la voce del gruppo specifico è del tutto assente dalla mappa, oppure quando esiste ma non definisce alcuna chiave systemPrompt.

Gerarchia di risoluzione per i messaggi diretti:

La mappa direct effettiva viene determinata per prima: se l'account definisce la propria direct, sostituisce completamente la mappa direct root (nessun deep merge). La ricerca del prompt viene quindi eseguita sulla singola mappa risultante:

1. Prompt di sistema specifico del diretto (direct["<peerId>"].systemPrompt): usato quando la voce del peer specifico esiste nella mappa e la sua chiave systemPrompt è definita. Se systemPrompt è una stringa vuota (""), il wildcard viene soppresso e non viene applicato alcun prompt di sistema.
2. Prompt di sistema wildcard del diretto (direct["*"].systemPrompt): usato quando la voce del peer specifico è del tutto assente dalla mappa, oppure quando esiste ma non definisce alcuna chiave systemPrompt.

Differenza rispetto al comportamento multi-account di Telegram: In Telegram, la root groups viene intenzionalmente soppressa per tutti gli account in una configurazione multi-account, anche per gli account che non definiscono propri groups, per impedire a un bot di ricevere messaggi di gruppo per gruppi a cui non appartiene. WhatsApp non applica questa protezione: root groups e root direct vengono sempre ereditati dagli account che non definiscono override a livello account, indipendentemente dal numero di account configurati. In una configurazione WhatsApp multi-account, se vuoi prompt di gruppo o diretti per account, definisci esplicitamente la mappa completa sotto ogni account invece di affidarti ai valori predefiniti a livello root.

Comportamento importante:

• channels.whatsapp.groups è sia una mappa di configurazione per gruppo sia l'allowlist dei gruppi a livello chat. Sia nell'ambito root sia nell'ambito account, groups["*"] significa "tutti i gruppi sono ammessi" per quell'ambito.
• Aggiungi un systemPrompt di gruppo wildcard solo quando vuoi già che quell'ambito ammetta tutti i gruppi. Se vuoi ancora che sia idoneo solo un insieme fisso di ID gruppo, non usare groups["*"] per il prompt predefinito. Ripeti invece il prompt su ogni voce di gruppo esplicitamente allowlistata.
• L'ammissione al gruppo e l'autorizzazione del mittente sono controlli separati. groups["*"] amplia l'insieme di gruppi che può raggiungere la gestione dei gruppi, ma da solo non autorizza ogni mittente in quei gruppi. L'accesso dei mittenti è comunque controllato separatamente da channels.whatsapp.groupPolicy e channels.whatsapp.groupAllowFrom.
• channels.whatsapp.direct non ha lo stesso effetto collaterale per i DM. direct["*"] fornisce solo una configurazione predefinita per chat dirette dopo che un DM è già stato ammesso da dmPolicy più allowFrom o dalle regole del pairing-store.

Esempio:

{  channels: {    whatsapp: {      groups: {        // Usa solo se tutti i gruppi devono essere ammessi nell'ambito radice.        // Si applica a tutti gli account che non definiscono la propria mappa dei gruppi.        "*": { systemPrompt: "Prompt predefinito per tutti i gruppi." },      },      direct: {        // Si applica a tutti gli account che non definiscono la propria mappa diretta.        "*": { systemPrompt: "Prompt predefinito per tutte le chat dirette." },      },      accounts: {        work: {          groups: {            // Questo account definisce i propri gruppi, quindi i gruppi radice vengono            // sostituiti completamente. Per mantenere un carattere jolly, definisci esplicitamente "*" anche qui.            "120363406415684625@g.us": {              requireMention: false,              systemPrompt: "Concentrati sulla gestione del progetto.",            },            // Usa solo se tutti i gruppi devono essere ammessi in questo account.            "*": { systemPrompt: "Prompt predefinito per i gruppi di lavoro." },          },          direct: {            // Questo account definisce la propria mappa diretta, quindi le voci dirette radice            // vengono sostituite completamente. Per mantenere un carattere jolly, definisci esplicitamente "*" anche qui.            "+15551234567": { systemPrompt: "Prompt per una chat diretta di lavoro specifica." },            "*": { systemPrompt: "Prompt predefinito per le chat dirette di lavoro." },          },        },      },    },  },}

Puntatori al riferimento di configurazione

Riferimento principale:

• Riferimento di configurazione - WhatsApp

Campi WhatsApp ad alto valore informativo:

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

Correlati

• Abbinamento
• Gruppi
• Sicurezza
• Instradamento dei canali
• Instradamento multi-agente
• Risoluzione dei problemi