OpenClaw su WhatsApp senza rischiare il tuo numero

Il canale WhatsApp di OpenClaw collega il tuo gateway a un account WhatsApp come dispositivo collegato, usando la libreria Baileys e un QR code. L’account è tuo, quindi anche un ban è tuo. La documentazione di OpenClaw consiglia un secondo numero dedicato: una SIM, una eSIM o una linea prepagata. Se preferisci non possedere quel numero, un numero gestito può collegarsi via HTTP con un breve bridge.

Come funziona il canale WhatsApp di OpenClaw?

OpenClaw è un gateway self-hosted open source (MIT) che collega le app di chat agli agenti AI. Il suo canale WhatsApp è «production-ready via WhatsApp Web (Baileys)», nelle parole della documentazione, e il gateway possiede la sessione collegata e il suo ciclo di riconnessione. La documentazione afferma che non esiste un canale WhatsApp Twilio separato. I fatti di questo articolo vengono dalla documentazione e dal repository di OpenClaw letti il 19 ottobre 2026.

La configurazione è breve:

1. Installa il plugin: openclaw plugins install @openclaw/whatsapp.
2. Collega l’account: openclaw channels login --channel whatsapp. Il login è solo con QR, quindi su un server headless ti serve un modo affidabile per portare il QR in tempo reale sul tuo telefono.
3. Avvia il gateway con openclaw gateway.

La dmPolicy predefinita è pairing. Un mittente sconosciuto riceve una richiesta di pairing, e la approvi con openclaw pairing approve whatsapp <CODE>. Le richieste scadono dopo un’ora e ogni account ne può contenere al massimo tre. Le altre policy sono allowlist (solo i numeri in allowFrom), open e disabled. Il canale gestisce chat dirette, gruppi, immagini, video, audio e documenti, e mentre lavora invia lo stato «sta scrivendo» e, per impostazione predefinita, le conferme di lettura.

Il collegamento avviene scansionando da un telefono, quindi il numero vive su un telefono e OpenClaw viaggia come dispositivo collegato. Questo dettaglio spiega gran parte di ciò che segue.

Perché OpenClaw vuole un secondo numero?

La documentazione di OpenClaw consiglia un numero dedicato per ragioni di controllo degli accessi, e le pagine di WhatsApp descrivono un rischio che le pagine di OpenClaw su WhatsApp e sul setup non discutono.

La pagina di WhatsApp definisce le app non ufficiali come app WhatsApp false e siti web creati da terze parti, e non nomina né OpenClaw né Baileys. OpenClaw è un client di terze parti che si collega come dispositivo, quindi parti dal presupposto che l’avvertimento valga anche per te. Un secondo numero limita i danni: se WhatsApp banna l’account, è il numero dell’assistente e non quello che usano la tua famiglia e i tuoi clienti.

La modalità con numero personale è un ripiego supportato. L’onboarding scrive allora dmPolicy: "allowlist", il tuo numero in allowFrom e selfChatMode: true, e la documentazione avverte che un controllo di liveness inviato al tuo stesso numero può diventare input dell’agente, a meno che tu non imposti selfChatMode: false.

Come ottieni il secondo numero?

La regola dei 14 giorni viene dalla pagina di WhatsApp sui dispositivi collegati, che dice anche che i dispositivi collegati funzionano senza il telefono online e si disconnettono dopo 30 giorni di inattività. Se usi già OpenClaw con il tuo numero personale, aggiungi l’assistente come account con nome invece di reinstallare: openclaw channels login --channel whatsapp --account assistant. Gli account stanno sotto channels.whatsapp.accounts.<id>, e ognuno conserva le proprie credenziali.

Come non farsi bannare usando OpenClaw?

Nessuna impostazione è documentata come a prova di ban, e a decidere è WhatsApp. Queste abitudini sono coerenti con ciò che dicono la documentazione e WhatsApp:

• Usa una allowlist. Imposta dmPolicy: "allowlist" e metti in allowFrom le persone che devono poter raggiungere l’agente. La modalità pairing predefinita ti fa già approvare i mittenti sconosciuti.
• Tieni stretta la tool policy. La guida di OpenClaw dice che un agente collegato può, a seconda della policy, eseguire comandi, usare file e scrivere alle persone a tuo nome. Un agente che scrive a persone che non gli hanno mai scritto è outreach a freddo dal tuo numero, uno dei segnali trattati in Perché WhatsApp banna i numeri.
• Fai un backup prima di ricollegare. Copia ~/.openclaw/credentials/whatsapp/<accountId>, poi esegui openclaw channels logout e openclaw channels login, come descrive la documentazione sulla risoluzione dei problemi.
• Riscalda prima il numero. Come fare il riscaldamento (warm-up) di un nuovo numero WhatsApp separa ciò che è noto dalla pratica della community.

OpenClaw può usare un numero gestito come whasp?

Non tramite il canale WhatsApp. Quel canale è WhatsApp Web tramite Baileys, e la documentazione di OpenClaw non elenca nessun altro trasporto WhatsApp. whasp è un’API HTTP: i messaggi in arrivo raggiungono il tuo webhook e una chiamata API risponde. Quindi OpenClaw non ha un modo integrato per usare whasp come suo WhatsApp. Ha però due porte documentate.

L’endpoint compatibile con OpenAI del Gateway. Il /v1/chat/completions di OpenClaw è disattivato per impostazione predefinita ed esegue un normale turno dell’agente. Il campo model indica un agente (openclaw/<agentId>), e una stringa user di OpenAI dà una sessione stabile, così chiamate ripetute proseguono una sola conversazione. Un bridge collega i due lati:

import { createServer } from "node:http";
import { Webhook } from "standardwebhooks";

const wh = new Webhook(process.env.WHASP_WEBHOOK_SECRET); // whsec_... da whasp
const seen = new Set(); // deduplica sull'id evento (in produzione usa un archivio vero)

async function askOpenClaw(user, text) {
  const res = await fetch(`${process.env.OPENCLAW_URL}/v1/chat/completions`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.OPENCLAW_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: process.env.OPENCLAW_AGENT ?? "openclaw/default",
      user, // stesso valore per conversazione = stessa sessione OpenClaw
      messages: [{ role: "user", content: text }],
    }),
  });
  if (!res.ok) throw new Error(`OpenClaw answered ${res.status}`);
  const data = await res.json();
  return data.choices?.[0]?.message?.content ?? "";
}

async function sendToWhasp(to, text, eventId) {
  const res = await fetch("https://api.whasp.ai/v1/messages", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.WHASP_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": eventId,
    },
    body: JSON.stringify({ to, text: text.slice(0, 4096) }),
  });
  if (!res.ok) throw new Error(`whasp answered ${res.status}`);
}

createServer(async (req, res) => {
  if (req.method !== "POST") return res.writeHead(405).end();
  const chunks = [];
  for await (const chunk of req) chunks.push(chunk);
  const body = Buffer.concat(chunks).toString("utf8"); // body grezzo, prima del parsing

  let event;
  try {
    event = wh.verify(body, req.headers);
  } catch {
    return res.writeHead(401).end();
  }
  res.writeHead(204).end(); // conferma subito, lavora dopo

  if (event.type !== "message.received" || seen.has(event.id)) return;
  seen.add(event.id);
  const { number, chat, text } = event.data.message;
  if (!text || /^(STOP|UNSUBSCRIBE|OPTOUT|CANCEL|END|QUIT)$/.test(text.trim())) return; // l'opt-out lo gestisce whasp

  try {
    const answer = await askOpenClaw(`whasp:${number}:${chat}`, text);
    if (answer) await sendToWhasp(chat, answer, event.id);
  } catch (err) {
    console.error(event.id, err.message);
  }
}).listen(8790);

Abbiamo eseguito questo codice contro simulatori di entrambe le API, costruiti dalla documentazione di OpenClaw e di whasp. Non l’abbiamo eseguito contro un gateway OpenClaw vero. Per usarlo, abilita gateway.http.endpoints.chatCompletions.enabled, registra l’URL HTTPS pubblico del bridge con PUT /v1/webhook e imposta WHASP_WEBHOOK_SECRET, WHASP_API_KEY, OPENCLAW_URL (la documentazione usa http://127.0.0.1:18789), OPENCLAW_TOKEN e OPENCLAW_AGENT. Il controllo della firma e la gestione dei duplicati sono spiegati in Webhook WhatsApp: verifica della firma, retry e duplicati.

Tre cose da tenere d’occhio. Primo, la documentazione di OpenClaw definisce questo endpoint come accesso operatore completo al gateway: tienilo su loopback o su una rete privata, così che solo il bridge possa chiamarlo. Secondo, i testi degli sconosciuti sono input non attendibile, quindi punta OPENCLAW_AGENT a un agente dedicato di cui hai ristretto i tool. Il README di OpenClaw dice di trattare i messaggi in arrivo come input non attendibile. Terzo, OpenClaw ora vede un generico client API, non un canale WhatsApp. Pairing, allowlist, gruppi, reazioni, typing e messaggi vocali non si applicano, e whasp ha i suoi limiti: gli utenti scrivono per primi, e non ci sono gruppi, indicatori di digitazione né messaggi vocali in uscita.

Un plugin di canale. La documentazione di OpenClaw dice di costruire un plugin di canale quando integri una rete di messaggistica esterna con una propria consegna via webhook o un proprio trasporto in uscita. Si ottengono routing e controllo degli accessi nativi, al prezzo di scrivere e mantenere TypeScript contro il plugin SDK. Non ne abbiamo costruito uno.

Cosa fare adesso

Scegli la strada in base a chi scriverà all’agente:

• Solo tu. Una SIM prepagata o una eSIM più il canale di OpenClaw è una configurazione ragionevole, purché tu accetti che il numero è il rischio. Tieni dmPolicy su allowlist.
• Poche persone che conosci. La stessa configurazione, con ogni persona in allowFrom o approvata tramite pairing, e una tool policy con cui saresti tranquillo anche se una di loro fosse poco attenta.
• Clienti o sconosciuti. Metti l’account dove un ban non tocca il tuo numero: un numero gestito tramite il bridge qui sopra, o la WhatsApp Business Platform ufficiale se il tuo bot rientra nei requisiti.

WhatsApp API non ufficiale a confronto illustra i compromessi tra le opzioni da gestire in proprio, e Server MCP per WhatsApp mostra un altro modo per dare un numero a un agente.