WhatsApp

​

Installazione

openclaw plugins install clawhub:@openclaw/whatsapp

​

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 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)

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

git clone --branch feat/send-only-notify https://github.com/steipete/meowcaller.git
cd meowcaller
git checkout 752050471fc2bf7a8cdfbf7dbd3cd4e865d85d3f
mkdir -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"

​

Richieste di approvazione

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

​

Hook dei plugin e privacy

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

​

Controllo degli accessi e attivazione

​

Associazioni ACP configurate

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

​

Comportamento del numero personale e della chat con sé stessi

​

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: "first" } } }

​

Livello delle reazioni

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

​

Reazioni di conferma

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

​

Reazioni allo stato del ciclo di vita

{
  messages: {
    statusReactions: {
      enabled: true,
      emojis: {
        deploy: "🛫",
        build: "🏗️",
        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 whatsapp
openclaw channels status

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

openclaw channels status --probe
openclaw doctor
openclaw logs --follow
openclaw gateway status

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

​

Prompt di sistema

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.

• 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.

{
  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

​

Argomenti correlati

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