OpenClaw no WhatsApp sem arriscar o seu próprio número

O canal de WhatsApp do OpenClaw liga o seu gateway a uma conta de WhatsApp como dispositivo vinculado, usando a biblioteca Baileys e um QR code. A conta é sua, então um banimento também é seu. A documentação do OpenClaw recomenda um segundo número dedicado: um chip, um eSIM ou uma linha pré-paga. Se você prefere não ser dono desse número, um número gerenciado pode se conectar por HTTP com uma ponte curta.

Como funciona o canal de WhatsApp do OpenClaw?

O OpenClaw é um gateway auto-hospedado de código aberto (MIT) que conecta apps de chat a agentes de IA. O canal de WhatsApp dele é “production-ready via WhatsApp Web (Baileys)”, nas palavras da documentação, e o gateway é dono da sessão vinculada e do loop de reconexão. A documentação afirma que não existe um canal separado de WhatsApp pela Twilio. Os fatos deste artigo vêm da documentação e do repositório do OpenClaw lidos em 19 de outubro de 2026.

A configuração é curta:

1. Instale o plugin: openclaw plugins install @openclaw/whatsapp.
2. Vincule a conta: openclaw channels login --channel whatsapp. O login é só por QR, então em um servidor sem tela você precisa de um jeito confiável de levar o QR ao vivo até o seu celular.
3. Inicie o gateway com openclaw gateway.

O dmPolicy padrão é pairing. Um remetente desconhecido recebe um pedido de pareamento, e você o aprova com openclaw pairing approve whatsapp <CODE>. Os pedidos expiram depois de uma hora e cada conta comporta no máximo três. As outras políticas são allowlist (só os números em allowFrom), open e disabled. O canal trata chats diretos, grupos, imagens, vídeo, áudio e documentos, e envia presença de digitação enquanto trabalha e confirmações de leitura por padrão.

A vinculação acontece escaneando com um celular, então o número mora em um celular, e o OpenClaw vai junto como dispositivo vinculado. Esse detalhe explica a maior parte do que vem a seguir.

Por que o OpenClaw quer um segundo número?

A documentação do OpenClaw recomenda um número dedicado por motivos de controle de acesso, e as páginas do próprio WhatsApp descrevem um risco que as páginas de WhatsApp e de configuração do OpenClaw não discutem.

A página do WhatsApp define apps não oficiais como apps e sites falsos do WhatsApp feitos por terceiros, e não cita nem o OpenClaw nem o Baileys. O OpenClaw é um cliente de terceiros que se vincula como dispositivo, então parta do princípio de que o aviso vale para você. Um segundo número limita o estrago: se o WhatsApp banir a conta, ela é o número do assistente, e não aquele que a sua família e os seus clientes usam.

O modo com número pessoal é uma alternativa suportada. O onboarding então grava dmPolicy: "allowlist", o seu próprio número em allowFrom e selfChatMode: true, e a documentação avisa que uma checagem de funcionamento enviada ao seu próprio número pode virar entrada do agente, a menos que você defina selfChatMode: false.

Como conseguir o segundo número?

A regra dos 14 dias vem da página de dispositivos vinculados do WhatsApp, que também diz que os dispositivos vinculados funcionam sem o celular online e são desconectados depois de 30 dias de inatividade. Se você já roda o OpenClaw no seu número pessoal, adicione o assistente como uma conta nomeada em vez de reinstalar: openclaw channels login --channel whatsapp --account assistant. As contas ficam em channels.whatsapp.accounts.<id>, e cada uma guarda as próprias credenciais.

Como não ser banido usando o OpenClaw?

Nenhuma configuração está documentada como à prova de banimento, e quem decide é o WhatsApp. Estes hábitos combinam com o que a documentação e o WhatsApp dizem:

• Use uma allowlist. Defina dmPolicy: "allowlist" e allowFrom com as pessoas que devem chegar ao agente. O modo pairing padrão já faz você aprovar remetentes desconhecidos.
• Mantenha a política de ferramentas restrita. O guia do OpenClaw diz que um agente conectado pode, dependendo da política, rodar comandos, usar arquivos e mandar mensagens para pessoas em seu nome. Um agente que escreve para quem nunca escreveu para ele é abordagem fria a partir do seu número, um dos sinais que Motivos de banimento no WhatsApp: por que ele bane números cobre.
• Faça backup antes de vincular de novo. Copie ~/.openclaw/credentials/whatsapp/<accountId>, depois rode openclaw channels logout e openclaw channels login, como descreve a documentação de solução de problemas.
• Aqueça o número primeiro. Como aquecer um número novo de WhatsApp separa o que é sabido da prática da comunidade.

O OpenClaw pode usar um número gerenciado como a whasp?

Não pelo canal de WhatsApp. Esse canal é o WhatsApp Web pelo Baileys, e a documentação do OpenClaw não lista nenhum outro transporte de WhatsApp. A whasp é uma API HTTP: as mensagens recebidas chegam ao seu webhook e uma chamada de API responde. Então o OpenClaw não tem um jeito nativo de usar a whasp como o seu WhatsApp. Ele tem duas portas documentadas.

O endpoint compatível com a OpenAI do Gateway. O /v1/chat/completions do OpenClaw vem desativado por padrão e roda um turno normal de agente. O campo model nomeia um agente (openclaw/<agentId>), e uma string user da OpenAI dá uma sessão estável, então chamadas repetidas continuam uma única conversa. Uma ponte liga os dois lados:

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 pelo id do evento (use um armazenamento de verdade em produção)

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, // mesmo valor por conversa = mesma sessão do 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"); // corpo bruto, antes do parse

  let event;
  try {
    event = wh.verify(body, req.headers);
  } catch {
    return res.writeHead(401).end();
  }
  res.writeHead(204).end(); // confirma agora, trabalha depois

  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; // a whasp trata o opt-out

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

Rodamos este código contra simulações das duas APIs (stubs), montadas a partir da documentação do OpenClaw e da whasp. Não rodamos contra um gateway OpenClaw de verdade. Para usar, ative gateway.http.endpoints.chatCompletions.enabled, registre a URL HTTPS pública da ponte com PUT /v1/webhook e defina WHASP_WEBHOOK_SECRET, WHASP_API_KEY, OPENCLAW_URL (a documentação usa http://127.0.0.1:18789), OPENCLAW_TOKEN e OPENCLAW_AGENT. A checagem da assinatura e o tratamento de duplicatas estão explicados em Webhook do WhatsApp: assinatura, novas tentativas e duplicatas.

Três pontos de atenção. Primeiro, a documentação do OpenClaw chama este endpoint de acesso total de operador ao gateway: mantenha-o em loopback ou em uma rede privada, para que só a ponte consiga chamá-lo. Segundo, textos de desconhecidos são entrada não confiável, então aponte OPENCLAW_AGENT para um agente dedicado, com ferramentas restritas por você. O README do OpenClaw manda tratar as mensagens recebidas como entrada não confiável. Terceiro, o OpenClaw agora enxerga um cliente de API genérico, não um canal de WhatsApp. O pareamento, as allowlists, os grupos, as reações, a digitação e as mensagens de voz dele não se aplicam, e a whasp tem seus próprios limites: os usuários escrevem primeiro, e não há grupos, indicadores de digitação nem mensagens de voz de saída.

Um plugin de canal. A documentação do OpenClaw diz para criar um plugin de canal quando você integra uma rede de mensagens externa com entrega por webhook ou transporte de saída próprios. Isso dá roteamento e controle de acesso nativos, ao preço de escrever e manter TypeScript contra o SDK de plugins. Não construímos um.

O que fazer agora

Escolha o caminho por quem vai mandar mensagem ao agente:

• Só você. Um chip pré-pago ou um eSIM com o canal próprio do OpenClaw é uma configuração razoável, desde que você aceite que o número é o risco. Mantenha o dmPolicy em allowlist.
• Algumas pessoas que você conhece. A mesma configuração, com cada pessoa em allowFrom ou aprovada pelo pareamento, e uma política de ferramentas com a qual você ficaria tranquilo se uma delas fosse descuidada.
• Clientes ou desconhecidos. Ponha a conta onde um banimento não alcance o seu próprio número: um número gerenciado pela ponte acima, ou a WhatsApp Business Platform oficial, se o seu bot se qualificar.

API não oficial do WhatsApp: Baileys, WAHA e Evolution comparados mostra as contrapartidas entre as opções que você mesmo opera, e Servidor MCP para WhatsApp mostra outro jeito de dar um número a um agente.