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 viene selezionato; openclaw channels login --channel whatsapp offre lo stesso flusso di installazione se il plugin non è presente. I checkout di sviluppo utilizzano 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 al di fuori del pacchetto npm principale di OpenClaw, quindi le sue dipendenze di runtime rimangono nel plugin esterno. Installazione manuale:

openclaw plugins install clawhub:@openclaw/whatsapp

Utilizzare il pacchetto npm semplice (@openclaw/whatsapp) solo per il ripiego sul registro; fissare 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>

Pattern 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 due segnali in modo indipendente: l'attività di trasporto grezza di WhatsApp Web e l'attività dei messaggi dell'applicazione. Una sessione inattiva ma connessa non viene riavviata solo perché non sono arrivati messaggi di recente; la riconnessione viene forzata esclusivamente quando i frame di trasporto non arrivano più per un intervallo interno fisso (non configurabile dall'utente) o i messaggi dell'applicazione rimangono assenti oltre 4 volte il normale timeout dei messaggi. Subito dopo una riconnessione di una sessione attiva di recente, il primo intervallo utilizza il normale timeout dei messaggi, più breve, anziché l'intervallo quadruplicato. OpenClaw può rispondere automaticamente ai messaggi offline consegnati in anticipo da Baileys durante tale riconnessione, entro la durata di deduplicazione degli ID dei messaggi in entrata; l'avvio iniziale mantiene la breve protezione contro la cronologia obsoleta.
• Le tempistiche del socket Baileys sono definite esplicitamente in web.whatsapp.*: keepAliveIntervalMs (intervallo di ping dell'applicazione), connectTimeoutMs (timeout dell'handshake di apertura), defaultQueryTimeoutMs (attese delle query Baileys, oltre ai timeout di OpenClaw per l'invio in uscita, la presenza e le conferme di lettura in entrata).
• Gli invii in uscita richiedono un listener WhatsApp attivo per l'account di destinazione; in caso contrario, l'invio non riesce immediatamente.
• Gli invii ai gruppi includono metadati nativi delle menzioni per i token @+<digits> e @<digits> (nel testo e nelle didascalie dei contenuti 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 utilizzano le regole di sessione dei messaggi diretti (session.dmScope; il valore predefinito main accorpa i messaggi diretti nella sessione principale dell'agente). Le sessioni dei gruppi 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, utilizzando i metadati di sessione del canale (agent:<agentId>:whatsapp:channel:<jid>) anziché la semantica dei messaggi diretti.
• Il trasporto WhatsApp Web rispetta le variabili di 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 specifiche del canale.
• Con messages.removeAckAfterReply abilitato, OpenClaw rimuove la reazione di conferma quando viene recapitata una risposta visibile.

Chiamare il richiedente corrente con MeowCaller (sperimentale)

Il plugin può esporre whatsapp_call nelle interazioni dell'agente provenienti da WhatsApp. Utilizza 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, pertanto 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 o chat con sé stessi, audio sintetizzato limitato a 60 secondi, nessuna conferma di udibilità sul dispositivo oltre al completamento di risposta, riproduzione e riaggancio di MeowCaller; OpenClaw arresta inoltre il processo complementare dopo un intervallo limitato 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 di esecuzione e del plugin come reazioni 👍/👎, controllate dalla configurazione di inoltro delle 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; l'abilitazione di 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 tale canale. La modalità sessione recapita approvazioni tramite emoji native solo per le approvazioni originate da WhatsApp. La modalità destinazione utilizza la pipeline di inoltro condivisa per le destinazioni esplicite e non crea una distribuzione separata di messaggi diretti agli approvatori.

Le reazioni di approvazione di WhatsApp richiedono approvatori espliciti in allowFrom (o "*"). 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 entrata possono contenere contenuti personali, numeri di telefono, identificatori di gruppi, nomi dei mittenti e campi di correlazione delle sessioni. WhatsApp non trasmette ai plugin i payload degli hook message_received in entrata, a meno che non venga fornito il consenso esplicito:

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

Limitare il consenso a un singolo account in channels.whatsapp.accounts.<id>.pluginHooks.messageReceived. Abilitare questa opzione solo per i plugin ritenuti affidabili per la gestione dei contenuti e degli identificatori WhatsApp in entrata.

Controllo degli accessi e attivazione

Associazioni ACP configurate

WhatsApp supporta associazioni ACP persistenti tramite 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 ai numeri E.164; i gruppi corrispondono ai JID dei gruppi WhatsApp. Gli elenchi di autorizzazione dei gruppi, il criterio per i mittenti e i requisiti di menzione/attivazione vengono applicati prima che OpenClaw garantisca 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 proprio numero collegato è presente anche in allowFrom, si attivano le protezioni per la chat con sé stessi: vengono omesse le conferme di lettura per i turni della chat con sé stessi, viene ignorato il comportamento di attivazione automatica tramite JID di menzione che causerebbe una notifica a sé stessi e le risposte vengono indirizzate per impostazione predefinita a [{identity.name}] (o [openclaw]) quando messages.responsePrefix non è impostato.

Normalizzazione dei messaggi e contesto

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

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

Consegna, suddivisione 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):

Sostituzione 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:

Sostituzione 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, soggetta 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, ricorrendo a "👀" come fallback (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 del gruppo always ignora tale controllo; WhatsApp usa soltanto channels.whatsapp.ackReaction (messages.ackReaction legacy 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 attraverso stati quali in coda, elaborazione, attività degli strumenti, Compaction, completamento 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 messaggio, pertanto gli aggiornamenti del ciclo di vita sostituiscono sul posto la reazione corrente; messages.removeAckAfterReply: true rimuove la reazione di stato finale dopo il periodo di permanenza configurato per completamento/errore; le categorie di emoji degli strumenti includono tool, coding, web, deploy, build e concierge.

Account multipli 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 (senza unione profonda). La ricerca del prompt viene quindi eseguita su questa singola 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 ("") sopprime il 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 sopprime groups radice per ogni account in una configurazione multi-account (anche per gli account senza un proprio groups) per impedire che un bot riceva messaggi da gruppi a cui non appartiene. WhatsApp non applica questa protezione: groups/direct radice vengono ereditati da qualsiasi account privo di una propria sostituzione, indipendentemente dal numero di account. In una configurazione WhatsApp multi-account, definire esplicitamente la mappa completa in ogni account se si desiderano prompt specifici per account.

Comportamento importante:

• channels.whatsapp.groups è sia una mappa di configurazione per gruppo sia l'elenco consentiti dei gruppi a livello di chat. Nell'ambito radice o dell'account, groups["*"] significa "sono ammessi tutti i gruppi" per tale ambito.
• Aggiungere un carattere jolly systemPrompt solo quando si desidera già che tale ambito ammetta tutti i gruppi. Per mantenere idoneo solo un insieme fisso di ID gruppo, ripetere il prompt in ogni voce esplicitamente consentita anziché utilizzare groups["*"].
• L'ammissione del gruppo e l'autorizzazione del mittente sono controlli separati. groups["*"] amplia l'insieme dei gruppi che raggiungono la gestione dei gruppi; non autorizza ogni mittente in 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 più allowFrom o dalle regole dell'archivio di associazione.

Esempio:

{  channels: {    whatsapp: {      groups: {        // Utilizzare solo se tutti i gruppi devono essere ammessi nell'ambito radice.        // Si applica a tutti gli account che non definiscono una propria mappa groups.        "*": { systemPrompt: "Prompt predefinito per tutti i gruppi." },      },      direct: {        // Si applica a tutti gli account che non definiscono una propria mappa direct.        "*": { 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, definire esplicitamente "*" anche qui.            "120363406415684625@g.us": {              requireMention: false,              systemPrompt: "Concentrarsi sulla gestione dei progetti.",            },            // Utilizzare solo se tutti i gruppi devono essere ammessi in questo account.            "*": { systemPrompt: "Prompt predefinito per i gruppi di lavoro." },          },          direct: {            // Questo account definisce una propria mappa direct, quindi le voci direct radice            // vengono sostituite completamente. Per mantenere un carattere jolly, definire esplicitamente "*" anche qui.            "+15551234567": { systemPrompt: "Prompt per una specifica chat diretta di lavoro." },            "*": { systemPrompt: "Prompt predefinito per le chat dirette di lavoro." },          },        },      },    },  },}

Riferimenti alla configurazione

Riferimento principale: Riferimento alla configurazione - WhatsApp

Argomenti correlati

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