WhatsApp

Stato: pronto per la produzione tramite WhatsApp Web (Baileys). Il Gateway gestisce le sessioni collegate; non esiste un canale WhatsApp Twilio separato.

Installazione

openclaw onboard e openclaw channels add --channel whatsapp richiedono di installare il Plugin la prima volta che lo si seleziona; se il Plugin non è presente, openclaw channels login --channel whatsapp offre lo stesso flusso di installazione. I checkout di sviluppo usano il percorso locale del Plugin; le installazioni stable/beta installano prima @openclaw/whatsapp da ClawHub, con ripiego su npm. Il runtime di WhatsApp viene distribuito separatamente dal pacchetto npm principale di OpenClaw, quindi le sue dipendenze di runtime rimangono associate al Plugin esterno. Installazione manuale:

openclaw plugins install clawhub:@openclaw/whatsapp

Usare il pacchetto npm semplice (@openclaw/whatsapp) solo come ripiego per il registro; bloccare una versione esatta solo per 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>

Schemi di distribuzione

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

Modello di runtime

• Il Gateway gestisce il socket WhatsApp e il ciclo di riconnessione.
• Un watchdog monitora indipendentemente due segnali: l'attività del trasporto WhatsApp Web non elaborata e l'attività dei messaggi dell'applicazione. Una sessione silenziosa ma connessa non viene riavviata solo perché non sono arrivati messaggi di recente; la riconnessione viene forzata soltanto quando i frame di trasporto non arrivano più per una finestra interna fissa, non configurabile dall'utente, oppure quando i messaggi dell'applicazione rimangono assenti per oltre 4 volte il normale timeout dei messaggi. Subito dopo la riconnessione di una sessione attiva di recente, la prima finestra usa il normale timeout dei messaggi, più breve, anziché la finestra quadruplicata. OpenClaw può rispondere automaticamente ai messaggi offline che Baileys consegna nelle prime fasi della riconnessione, entro la durata della deduplicazione degli ID dei messaggi in ingresso; l'avvio iniziale mantiene la breve protezione contro la cronologia obsoleta.
• Le tempistiche del socket Baileys sono esplicite in web.whatsapp.*: keepAliveIntervalMs (intervallo dei ping dell'applicazione), connectTimeoutMs (timeout dell'handshake di apertura), defaultQueryTimeoutMs (attese delle query Baileys, oltre ai timeout di OpenClaw per invio e presenza in uscita e conferme di lettura in ingresso).
• Gli invii in uscita richiedono un listener WhatsApp attivo per l'account di destinazione; in caso contrario, non riescono immediatamente.
• Gli invii ai gruppi allegano metadati nativi delle menzioni per i token @+<digits> e @<digits> presenti nel testo e nelle didascalie multimediali, quando il token corrisponde ai metadati correnti di un partecipante, inclusi i gruppi basati su LID.
• Le chat di stato e broadcast (@status, @broadcast) vengono ignorate.
• Le chat dirette usano le regole di sessione dei messaggi diretti (session.dmScope; il valore predefinito main raggruppa i messaggi diretti nella sessione principale dell'agente). Le sessioni di gruppo sono isolate per JID (agent:<agentId>:whatsapp:group:<jid>).
• I canali e le newsletter di WhatsApp possono essere destinazioni esplicite in uscita tramite il relativo JID nativo @newsletter, usando i metadati di sessione del canale (agent:<agentId>:whatsapp:channel:<jid>) anziché la semantica dei messaggi diretti.
• Il trasporto WhatsApp Web rispetta le variabili d'ambiente proxy standard sull'host del Gateway (HTTPS_PROXY, HTTP_PROXY, NO_PROXY e le varianti in minuscolo). Preferire la configurazione proxy a livello di host rispetto alle impostazioni per singolo canale.
• Quando messages.removeAckAfterReply è abilitato, OpenClaw rimuove la reazione di conferma dopo la consegna di una risposta visibile.

Chiamare il richiedente corrente con MeowCaller (sperimentale)

Il Plugin può rendere disponibile whatsapp_call nei turni dell'agente originati da WhatsApp. Usa MeowCaller per effettuare una chiamata vocale WhatsApp al richiedente autorizzato corrente e riprodurre un messaggio TTS di OpenClaw dopo la risposta. Lo strumento non dispone di un parametro per il numero di destinazione, quindi un prompt non può reindirizzare la chiamata. È disabilitato 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: solo chiamate audio in uscita individuali, nessun numero di destinazione arbitrario, nessuna autenticazione condivisa con la connessione della chat, nessuna chiamata a sé stessi dalla modalità con numero personale e chat con sé stessi, audio sintetizzato limitato a 60 secondi, nessuna conferma di udibilità sul telefono oltre al completamento di risposta, riproduzione e riaggancio di MeowCaller; OpenClaw arresta inoltre il processo ausiliario dopo una finestra limitata di 115-175 secondi, che comprende le fasi di connessione, risposta, riproduzione e arresto di MeowCaller.

Richieste di approvazione

WhatsApp può visualizzare le richieste di approvazione dell'esecuzione e dei Plugin come reazioni 👍/👎, controllate dalla configurazione di inoltro delle approvazioni di primo livello:

{  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 soltanto il trasporto e non invia nulla, a meno che la famiglia di approvazioni corrispondente non sia abilitata e instradata verso quel canale. La modalità di sessione invia approvazioni emoji native solo per le approvazioni originate da WhatsApp. La modalità di destinazione usa la pipeline di inoltro condivisa per le destinazioni esplicite e non crea una distribuzione separata dei messaggi diretti agli approvatori.

Le reazioni di approvazione di WhatsApp richiedono approvatori espliciti in allowFrom oppure "*". defaultTo imposta le normali destinazioni predefinite dei messaggi, non un elenco di approvatori. I comandi manuali /approve seguono comunque il normale percorso di autorizzazione del mittente WhatsApp prima della risoluzione dell'approvazione.

Hook dei Plugin e privacy

I messaggi WhatsApp in ingresso possono contenere dati personali, numeri di telefono, identificatori di gruppo, nomi dei mittenti e campi di correlazione delle sessioni. WhatsApp non trasmette ai Plugin i payload dell'hook message_received in ingresso, a meno che non si abiliti esplicitamente questa funzione:

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

Limitare l'abilitazione a un singolo account tramite channels.whatsapp.accounts.<id>.pluginHooks.messageReceived. Abilitare questa opzione solo per i Plugin a cui si affidano i contenuti e gli identificatori WhatsApp in ingresso.

Controllo degli accessi e attivazione

Associazioni ACP configurate

WhatsApp supporta associazioni ACP persistenti tramite bindings[] al livello principale:

{  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 ai numeri E.164; i gruppi corrispondono ai JID di gruppo WhatsApp. Gli elenchi di autorizzazioni dei gruppi, i criteri per i mittenti e il requisito di attivazione tramite menzione vengono applicati prima che OpenClaw verifichi l'esistenza della sessione ACP associata. Un'associazione corrispondente assume il controllo dell'instradamento: i gruppi di trasmissione non distribuiscono quel turno alle normali sessioni WhatsApp.

Comportamento del numero personale e della chat con sé stessi

Quando il numero personale collegato è presente anche in allowFrom, si attivano le protezioni per le chat con sé stessi: le conferme di lettura vengono omesse per i turni di queste chat, viene ignorato il comportamento di attivazione automatica tramite JID di menzione che invierebbe una notifica a sé stessi e, quando messages.responsePrefix non è impostato, le risposte 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 } } }

Consegna, suddivisione in blocchi e contenuti multimediali

Citazione nelle risposte

channels.whatsapp.replyToMode controlla la citazione nativa nelle risposte (le risposte in uscita citano visibilmente il messaggio in entrata):

Impostazione sostitutiva per account: channels.whatsapp.accounts.<id>.replyToMode.

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

Livello delle reazioni

channels.whatsapp.reactionLevel controlla l'ampiezza con cui l'agente usa le reazioni emoji:

Impostazione sostitutiva per account: channels.whatsapp.accounts.<id>.reactionLevel.

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

Reazioni di conferma

channels.whatsapp.ackReaction invia una reazione immediata alla ricezione di un messaggio in entrata, subordinata a reactionLevel (soppressa quando è "off"):

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

Note: viene inviata immediatamente dopo l'accettazione del messaggio in entrata (prima della risposta); se ackReaction è presente senza emoji, WhatsApp usa l'emoji dell'identità dell'agente instradato, con "👀" come ripiego (omettere ackReaction o impostare emoji: "" per non inviare alcuna conferma); gli errori vengono registrati ma non bloccano la consegna della risposta; la modalità di gruppo mentions reagisce soltanto ai turni attivati da una menzione, mentre l'attivazione di gruppo always ignora questo controllo; WhatsApp usa esclusivamente channels.whatsapp.ackReaction (il precedente messages.ackReaction non si applica qui).

Reazioni allo stato del ciclo di vita

Impostare messages.statusReactions.enabled: true per consentire a WhatsApp di sostituire la reazione di conferma durante un turno anziché lasciare un'emoji di ricezione statica, passando ciclicamente tra stati quali in coda, elaborazione, attività degli strumenti, Compaction, completato ed errore:

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

Note: channels.whatsapp.ackReaction continua a controllare l'idoneità per i messaggi diretti e i gruppi; lo stato in coda usa la stessa emoji effettiva delle normali reazioni di conferma; WhatsApp dispone di un solo spazio per la reazione del bot per ogni messaggio, quindi gli aggiornamenti del ciclo di vita sostituiscono sul posto la reazione corrente; messages.removeAckAfterReply: true rimuove la reazione di stato finale dopo il periodo configurato di mantenimento dello stato completato/errore; le categorie di emoji degli strumenti includono tool, coding, web, deploy, build e concierge.

Più account e credenziali

Strumenti, azioni e scritture della configurazione

• Il supporto degli strumenti dell'agente include l'azione di reazione di WhatsApp (react).
• Controlli delle azioni: channels.whatsapp.actions.reactions, channels.whatsapp.actions.polls (le azioni esistenti hanno come valore predefinito true), channels.whatsapp.actions.calls (valore predefinito false, vedere MeowCaller sopra).
• Le scritture della configurazione avviate dal canale sono abilitate per impostazione predefinita; disabilitarle 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.

Risoluzione per i messaggi di gruppo: viene determinata innanzitutto la mappa groups effettiva — se l'account definisce una propria chiave groups, questa sostituisce completamente la mappa groups radice (nessuna unione profonda). La ricerca del prompt viene quindi eseguita su quell'unica mappa risultante:

1. Prompt specifico del gruppo (groups["<groupId>"].systemPrompt): utilizzato quando la voce del gruppo esiste e la relativa chiave systemPrompt è definita. Una stringa vuota ("") impedisce l'uso del carattere jolly e non applica alcun prompt.
2. Prompt con carattere jolly per i gruppi (groups["*"].systemPrompt): utilizzato quando la voce specifica del gruppo è assente oppure esiste senza una chiave systemPrompt.

La risoluzione per i messaggi diretti segue lo stesso schema con la mappa direct e direct["*"].

Differenza rispetto a Telegram: Telegram ignora groups alla radice per ogni account in una configurazione con più account (anche per gli account privi di una propria chiave groups) per impedire che un bot riceva messaggi da gruppi ai quali non appartiene. WhatsApp non applica questa protezione — groups/direct alla radice vengono ereditati da qualsiasi account che non abbia una propria sostituzione, indipendentemente dal numero di account. In una configurazione WhatsApp con più account, definire esplicitamente la mappa completa sotto ogni account se si desiderano prompt specifici per account.

Comportamento importante:

• channels.whatsapp.groups è sia una mappa di configurazione per gruppo sia l'elenco consentito dei gruppi a livello di chat. Sia nell'ambito radice sia nell'ambito dell'account, groups["*"] significa "tutti i gruppi sono ammessi" per tale ambito.
• Aggiungere un systemPrompt con carattere jolly solo se si desidera già che tale ambito ammetta tutti i gruppi. Per mantenere idoneo soltanto un insieme fisso di ID di gruppo, ripetere il prompt in ogni voce esplicitamente inclusa nell'elenco consentito anziché utilizzare groups["*"].
• L'ammissione del gruppo e l'autorizzazione del mittente sono controlli separati. groups["*"] amplia i gruppi che raggiungono la gestione dei gruppi; non autorizza tutti i mittenti di tali gruppi — questo rimane sotto il controllo di groupPolicy/groupAllowFrom.
• channels.whatsapp.direct non ha un effetto collaterale equivalente per i messaggi diretti: direct["*"] fornisce soltanto una configurazione predefinita dopo che un messaggio diretto è già stato ammesso da dmPolicy insieme ad allowFrom o alle regole dell'archivio degli abbinamenti.

Esempio:

{  channels: {    whatsapp: {      groups: {        // Use only if all groups should be admitted at the root scope.        // Applies to all accounts that do not define their own groups map.        "*": { systemPrompt: "Default prompt for all groups." },      },      direct: {        // Applies to all accounts that do not define their own direct map.        "*": { systemPrompt: "Default prompt for all direct chats." },      },      accounts: {        work: {          groups: {            // This account defines its own groups, so root groups are fully            // replaced. To keep a wildcard, define "*" explicitly here too.            "120363406415684625@g.us": {              requireMention: false,              systemPrompt: "Focus on project management.",            },            // Use only if all groups should be admitted in this account.            "*": { systemPrompt: "Default prompt for work groups." },          },          direct: {            // This account defines its own direct map, so root direct entries are            // fully replaced. To keep a wildcard, define "*" explicitly here too.            "+15551234567": { systemPrompt: "Prompt for a specific work direct chat." },            "*": { systemPrompt: "Default prompt for work direct chats." },          },        },      },    },  },}

Riferimenti alla configurazione

Riferimento principale: Riferimento della configurazione - WhatsApp

Contenuti correlati

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