WhatsApp

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Installazione (su richiesta)

• Onboarding (openclaw onboard) e openclaw channels add --channel whatsapp chiedono 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: usa per impostazione predefinita il percorso del plugin locale.
• Stable/Beta: usa il pacchetto npm @openclaw/whatsapp sul tag di rilascio ufficiale corrente.

openclaw plugins install @openclaw/whatsapp

winget install --id Git.Git -e

​

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-auth
openclaw channels login --channel whatsapp --account work

openclaw gateway

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>

​

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 dei messaggi app in ingresso, quindi una sessione silenziosa di un dispositivo collegato non viene riavviata solo perché nessuno ha inviato messaggi di recente. Un limite più lungo di silenzio dell’applicazione forza comunque una riconnessione se i frame di trasporto continuano ad arrivare ma non vengono gestiti messaggi dell’applicazione durante la finestra del watchdog; dopo una riconnessione transitoria per una sessione attiva di recente, quel controllo del silenzio dell’applicazione usa il timeout normale dei messaggi per la prima finestra di recupero.
• I timing del socket Baileys sono espliciti sotto web.whatsapp.*: keepAliveIntervalMs controlla i ping dell’applicazione WhatsApp Web, connectTimeoutMs controlla il timeout dell’handshake di apertura e defaultQueryTimeoutMs controlla i timeout delle query Baileys.
• Gli invii in uscita richiedono un listener WhatsApp attivo per l’account di destinazione.
• Gli invii ai gruppi allegano metadati di menzione nativi per i token @+<digits> e @<digits> nel testo e nelle didascalie dei media quando il token corrisponde ai metadati correnti dei partecipanti WhatsApp, 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 dei messaggi app in ingresso: le sessioni silenziose dei dispositivi collegati restano attive mentre i frame di trasporto continuano, ma uno stallo del trasporto forza la riconnessione molto prima del percorso successivo di disconnessione remota.
• Le chat dirette usano le regole di sessione DM (session.dmScope; il valore predefinito main collassa i DM nella sessione principale dell’agente).
• Le sessioni di gruppo sono isolate (agent:<agentId>:whatsapp:group:<jid>).
• WhatsApp Channels/Newsletters possono essere destinazioni in uscita esplicite con il loro JID nativo @newsletter. Gli invii in uscita alle newsletter usano i metadati di sessione del canale (agent:<agentId>:whatsapp:channel:<jid>) invece della semantica delle sessioni 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.

​

Hook dei plugin e privacy

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

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

​

Controllo degli accessi e attivazione

​

Comportamento con numero personale e chat con sé stessi

• salta le conferme di lettura per i turni di chat con sé stessi
• ignora il comportamento di attivazione automatica mention-JID che altrimenti ti pingherebbe
• se messages.responsePrefix non è impostato, le risposte nella chat con sé 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

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

​

Livello di reazione

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

​

Reazioni di conferma

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

• inviate immediatamente dopo l’accettazione del messaggio in ingresso (prima della risposta)
• gli errori vengono registrati ma non bloccano la normale consegna della risposta
• la modalità gruppo mentions reagisce ai turni attivati da menzioni; l’attivazione del gruppo always permette di saltare questo controllo
• WhatsApp usa channels.whatsapp.ackReaction (il valore legacy messages.ackReaction non viene usato qui)

​

Multi-account e credenziali

​

Strumenti, azioni e scritture di configurazione

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

openclaw channels login --channel whatsapp
openclaw channels status

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

openclaw doctor
openclaw logs --follow

​

Prompt di sistema

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 carattere jolly viene soppresso e non viene applicato alcun prompt di sistema.
2. Prompt di sistema jolly 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.

1. Prompt di sistema specifico per chat diretta (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 jolly viene soppresso e non viene applicato alcun prompt di sistema.
2. Prompt di sistema jolly per chat diretta (direct["*"].systemPrompt): usato quando la voce del peer specifico è completamente assente dalla mappa, oppure quando esiste ma non definisce alcuna chiave systemPrompt.

• channels.whatsapp.groups è sia una mappa di configurazione per gruppo sia la allowlist dei gruppi a livello di chat. A livello radice o di account, groups["*"] significa “tutti i gruppi sono ammessi” per quell’ambito.
• Aggiungi un systemPrompt di gruppo jolly solo quando vuoi già che quell’ambito ammetta tutti i gruppi. Se vuoi comunque che sia idoneo solo un insieme fisso di ID gruppo, non usare groups["*"] per il valore predefinito del prompt. Ripeti invece il prompt su ogni voce di gruppo esplicitamente inclusa nella allowlist.
• L’ammissione del gruppo e l’autorizzazione del mittente sono controlli separati. groups["*"] amplia l’insieme dei gruppi che possono raggiungere la gestione dei gruppi, ma da solo non autorizza ogni mittente in quei gruppi. L’accesso del mittente è 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 le chat dirette dopo che un DM è già stato ammesso da dmPolicy più allowFrom o dalle regole dell’archivio di associazione.

{
  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." },
          },
        },
      },
    },
  },
}

​

Puntatori di riferimento per la configurazione

• Riferimento della configurazione - WhatsApp

• accesso: dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups
• recapito: textChunkLimit, chunkMode, mediaMaxMb, sendReadReceipts, ackReaction, reactionLevel
• più 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

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