Vai al contenuto principale

​
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 propongono di installare il plugin WhatsApp la prima volta che lo selezioni.
  • Anche openclaw channels login --channel whatsapp offre il flusso di installazione quando il plugin non è ancora presente.
  • Canale dev + checkout git: per impostazione predefinita usa il percorso locale del plugin.
  • Stable/Beta: per impostazione predefinita usa il pacchetto npm @openclaw/whatsapp.
L’installazione manuale resta disponibile: 
openclaw plugins install @openclaw/whatsapp

Associazione

La policy DM predefinita è l’associazione per i mittenti sconosciuti.

Risoluzione dei problemi dei canali

Diagnostica cross-channel e procedure di riparazione.

Configurazione del gateway

Modelli ed esempi completi di configurazione del canale.

​
Configurazione rapida

1

Configura la policy di accesso WhatsApp

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

Collega WhatsApp (QR)

openclaw channels login --channel whatsapp
Per un account specifico:
openclaw channels login --channel whatsapp --account work
3

Avvia il gateway

openclaw gateway
4

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

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>
Le richieste di associazione 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 le configurazioni con numero personale.)

​
Modelli di distribuzione

Questa è la modalità operativa più pulita:
  • identità WhatsApp separata per OpenClaw
  • allowlist DM e confini di instradamento più chiari
  • minore probabilità di confusione con le chat a sé stessi
Modello di policy minimo:
{
  channels: {
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15551234567"],
    },
  },
}
L’onboarding supporta la modalità numero personale e scrive una baseline adatta alle chat con sé stessi:
  • dmPolicy: "allowlist"
  • allowFrom include il tuo numero personale
  • selfChatMode: true
A runtime, le protezioni per le chat con sé stessi si basano sul numero personale collegato e su allowFrom.
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; per impostazione predefinita main comprime i DM nella sessione principale dell’agente).
  • Le sessioni di gruppo sono isolate (agent:<agentId>:whatsapp:group:<jid>).

​
Controllo dell’accesso e attivazione

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 precedenza sui valori predefiniti a livello di canale per quell’account.Dettagli del comportamento a runtime:
  • le associazioni vengono mantenute nell’allow-store del canale e unite a allowFrom configurato
  • se non è configurata alcuna allowlist, il numero personale collegato è consentito per impostazione predefinita
  • i DM in uscita fromMe non vengono mai associati automaticamente

​
Comportamento con numero personale e chat con sé stessi

Quando il numero personale collegato è presente anche in allowFrom, si attivano le protezioni per le chat con sé stessi su WhatsApp:
  • salta le conferme di lettura per i turni di chat con sé stessi
  • ignora il comportamento di attivazione automatica tramite mention-JID che altrimenti invierebbe una menzione a te stesso
  • se messages.responsePrefix non è impostato, per impostazione predefinita le risposte alle chat con sé stessi usano [{identity.name}] o [openclaw]

​
Normalizzazione dei messaggi e contesto

I messaggi WhatsApp in ingresso sono racchiusi nell’envelope condivisa dei messaggi 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, JID/E.164 del mittente).
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.
Per i gruppi, i messaggi non elaborati possono essere bufferizzati e iniettati come contesto quando il bot viene infine attivato.
  • limite predefinito: 50
  • config: 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]
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

  • limite predefinito dei blocchi: channels.whatsapp.textChunkLimit = 4000
  • channels.whatsapp.chunkMode = "length" | "newline"
  • la modalità newline preferisce i confini dei paragrafi (righe vuote), poi ricade sulla suddivisione sicura per lunghezza
  • supporta payload di immagine, video, audio (messaggio vocale PTT) e documento
  • 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
  • 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 di media, il fallback del primo elemento invia un avviso testuale invece di eliminare silenziosamente la risposta

​
Livello di reazione

channels.whatsapp.reactionLevel controlla quanto ampiamente l’agente usa le reazioni emoji su WhatsApp:
LivelloReazioni di ackReazioni avviate dall’agenteDescrizione
"off"NoNoNessuna reazione
"ack"SìNoSolo reazioni di ack (ricevuta pre-risposta)
"minimal"SìSì (conservative)Ack + reazioni dell’agente con guida conservativa
"extensive"SìSì (encouraged)Ack + reazioni dell’agente con guida incoraggiata
Predefinito: "minimal". Gli override per account usano channels.whatsapp.accounts.<id>.reactionLevel. 
{
  channels: {
    whatsapp: {
      reactionLevel: "ack",
    },
  },
}

​
Reazioni di acknowledgment

WhatsApp supporta reazioni di ack immediate alla ricezione in ingresso tramite channels.whatsapp.ackReaction. Le reazioni di ack sono regolate da reactionLevel — vengono soppresse quando reactionLevel è "off". 
{
  channels: {
    whatsapp: {
      ackReaction: {
        emoji: "👀",
        direct: true,
        group: "mentions", // always | mentions | never
      },
    },
  },
}
Note sul comportamento:
  • inviate immediatamente dopo che il messaggio in ingresso è stato accettato (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 agisce come bypass per questo controllo
  • WhatsApp usa channels.whatsapp.ackReaction (qui non viene usato il legacy messages.ackReaction)

​
Multi-account e credenziali

  • 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 il lookup
  • percorso auth attuale: ~/.openclaw/credentials/whatsapp/<accountId>/creds.json
  • file di backup: creds.json.bak
  • l’auth legacy predefinita in ~/.openclaw/credentials/ è ancora riconosciuta/migrata per i flussi dell’account predefinito
openclaw channels logout --channel whatsapp [--account <id>] cancella lo stato auth di WhatsApp per quell’account.Nelle directory auth legacy, oauth.json viene preservato mentre i file auth di Baileys vengono rimossi.

​
Strumenti, azioni e scritture di configurazione

  • Il supporto degli 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

Sintomo: lo stato del canale segnala che non è collegato.Correzione:
openclaw channels login --channel whatsapp
openclaw channels status
Sintomo: account collegato con disconnessioni ripetute o tentativi di riconnessione.Correzione:
openclaw doctor
openclaw logs --follow
Se necessario, ricollega con channels login.
Gli invii in uscita falliscono rapidamente 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.
Controlla in questo ordine:
  • groupPolicy
  • groupAllowFrom / allowFrom
  • voci della allowlist groups
  • gating delle menzioni (requireMention + pattern di menzione)
  • chiavi duplicate in openclaw.json (JSON5): le voci successive sovrascrivono quelle precedenti, quindi mantieni un solo groupPolicy per ambito
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: 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 di account
  • operazioni: configWrites, debounceMs, web.enabled, web.heartbeatSeconds, web.reconnect.*
  • comportamento della sessione: session.dmScope, historyLimit, dmHistoryLimit, dms.<id>.historyLimit

​
Correlati