Guia Completo de Integracao do OpenClaw com WhatsApp

Visao Geral

A integracao com o WhatsApp permite que voce converse com seu assistente de IA OpenClaw diretamente pelo WhatsApp. O OpenClaw usa o WhatsApp Web via Baileys — o gateway gerencia a(s) sessao(oes) e toda a comunicacao. Voce vinculara sua conta do WhatsApp de forma semelhante a como vincularia o WhatsApp Web em um navegador.

Pre-requisitos

Antes de comecar, certifique-se de ter:

• OpenClaw instalado e o gateway em execucao
• Uma conta do WhatsApp com um numero de celular real (numeros VoIP e virtuais geralmente sao bloqueados pelo WhatsApp)
• Runtime Node.js (Bun nao e recomendado — WhatsApp/Baileys e instavel no Bun)

Obtendo um Numero de Telefone

O WhatsApp requer um numero de celular real para verificacao. Existem dois modos suportados:

Numero Dedicado (Recomendado)

Use um numero de telefone separado para o OpenClaw. Isso proporciona a melhor experiencia de usuario com roteamento limpo e sem peculiaridades do self-chat. A configuracao ideal e um celular Android antigo/reserva + eSIM — deixe-o conectado ao Wi-Fi e carregando, depois vincule via QR.

Dicas para obter um numero:

• eSIM local da operadora do seu pais (mais confiavel)
• SIM pre-pago — barato, so precisa receber um SMS de verificacao
• Evite: TextNow, Google Voice, a maioria dos servicos de "SMS gratis" — o WhatsApp bloqueia esses agressivamente

O numero so precisa receber um SMS de verificacao. Depois disso, as sessoes do WhatsApp Web persistem via creds.json.

Dica: Voce pode usar o WhatsApp Business no mesmo dispositivo com um numero diferente. Otimo para manter seu WhatsApp pessoal separado — instale o WhatsApp Business e registre o numero do OpenClaw nele.

Numero Pessoal (Alternativa)

Alternativa rapida: execute o OpenClaw no seu proprio numero. Envie mensagens para si mesmo (recurso "Mensagem para si mesmo" do WhatsApp) para testes, evitando incomodar seus contatos. Voce deve habilitar o modo self-chat nesse caso.

Passo 1: Configurar o WhatsApp

Edite seu ~/.openclaw/openclaw.json.

Configuracao com Numero Dedicado

{
  channels: {
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15551234567"],
    },
  },
}

Substitua +15551234567 pelo(s) numero(s) de telefone que voce deseja permitir que conversem com o assistente (formato E.164).

Configuracao com Numero Pessoal (Modo Self-Chat)

{
  "whatsapp": {
    "selfChatMode": true,
    "dmPolicy": "allowlist",
    "allowFrom": ["+15551234567"]
  }
}

Ao usar o modo self-chat, insira o numero de telefone de onde voce envia as mensagens (o proprietario/remetente), nao o numero do assistente. As respostas no self-chat usam [{identity.name}] como prefixo por padrao (ou [openclaw] se nao definido). Voce pode personalizar isso via messages.responsePrefix ou definir como "" para remove-lo.

Passo 2: Vincular Sua Conta do WhatsApp

Execute o comando de login:

openclaw channels login

Isso exibira um codigo QR no seu terminal. No seu telefone:

1. Abra o WhatsApp
2. Va em Configuracoes > Dispositivos Conectados
3. Toque em Conectar Dispositivo
4. Escaneie o codigo QR exibido no seu terminal

Para configuracoes com multiplas contas, especifique a conta:

openclaw channels login --account <accountId>

A conta padrao (quando --account e omitido) e default se presente, caso contrario o primeiro ID de conta configurado (ordenado).

Passo 3: Iniciar o Gateway

Inicie o gateway do OpenClaw para comecar a receber mensagens. O gateway gerencia o socket Baileys e o loop da caixa de entrada — o CLI e o app macOS se comunicam com o gateway, sem uso direto do Baileys.

Importante: Um listener ativo e necessario para envios de saida; caso contrario, os envios falharao imediatamente.

Controle de Acesso de DMs

O OpenClaw oferece tres modos de politica de DM via channels.whatsapp.dmPolicy:

Modo Pairing (Padrao)

Remetentes desconhecidos recebem um codigo de pareamento com tempo limitado. A mensagem deles nao e processada ate ser aprovada.

# Aprovar uma solicitacao de pareamento
openclaw pairing approve whatsapp <code>

# Listar solicitacoes de pareamento pendentes
openclaw pairing list whatsapp

Os codigos de pareamento expiram apos 1 hora, e as solicitacoes pendentes sao limitadas a 3 por canal.

Modo Allowlist

Apenas numeros de telefone listados em channels.whatsapp.allowFrom podem iniciar conversas.

{
  channels: {
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15551234567", "+15559876543"],
    },
  },
}

Modo Open

Requer que channels.whatsapp.allowFrom inclua "*".

Nota: Seu numero vinculado do WhatsApp e implicitamente confiavel — mensagens proprias ignoram as verificacoes de dmPolicy e allowFrom.

Confirmacoes de Leitura

Por padrao, o gateway marca as mensagens recebidas do WhatsApp como lidas (ticks azuis) apos serem aceitas.

Desativar globalmente:

{
  channels: { whatsapp: { sendReadReceipts: false } },
}

Desativar por conta:

{
  channels: {
    whatsapp: {
      accounts: {
        personal: { sendReadReceipts: false },
      },
    },
  },
}

O modo self-chat sempre ignora confirmacoes de leitura.

Suporte a Chat em Grupo

Grupos sao mapeados para sessoes dedicadas. Configure o comportamento de grupo com:

• Politica de grupo: channels.whatsapp.groupPolicy — open, disabled ou allowlist (padrao: allowlist)
• Modos de ativacao:
  • mention (padrao): requer @mencao ou correspondencia de regex
  • always: sempre aciona uma resposta

Alterne a ativacao com um comando exclusivo do proprietario (deve ser uma mensagem isolada):

/activation mention
/activation always

O proprietario e determinado por channels.whatsapp.allowFrom (ou seu E.164 proprio se nao definido).

Contexto do Historico do Grupo

Mensagens recentes nao processadas (padrao 50) sao automaticamente injetadas como contexto:

[Chat messages since your last reply - for context]
...
[Current message - respond to this]

Cada mensagem inclui um sufixo de remetente: [from: Name (+E164)].

Os metadados do grupo (assunto + participantes) sao armazenados em cache por 5 minutos.

Reacoes de Confirmacao

O WhatsApp pode enviar automaticamente reacoes com emoji para mensagens recebidas ao recebe-las, fornecendo feedback instantaneo antes do bot gerar uma resposta.

{
  "whatsapp": {
    "ackReaction": {
      "emoji": "👀",
      "direct": true,
      "group": "mentions"
    }
  }
}

Opcoes:

• emoji: Emoji para reagir (ex.: "👀", "✅"). Vazio ou omitido desativa o recurso.
• direct (padrao: true): Enviar reacoes em chats diretos.
• group (padrao: "mentions"):
  • "always": Reagir a todas as mensagens do grupo
  • "mentions": Reagir apenas quando o bot e @mencionado
  • "never": Nunca reagir em grupos

Substituicao por conta:

{
  "whatsapp": {
    "accounts": {
      "work": {
        "ackReaction": {
          "emoji": "✅",
          "direct": false,
          "group": "always"
        }
      }
    }
  }
}

As reacoes sao enviadas imediatamente ao receber a mensagem, antes dos indicadores de digitacao ou respostas do bot. Falhas sao registradas nos logs, mas nao impedem o bot de responder.

Tratamento de Mensagens

Mensagens Recebidas

• As mensagens chegam via eventos messages.upsert do Baileys
• Chats de status/broadcast sao ignorados
• Chats diretos usam formato E.164; grupos usam group JID
• O contexto de resposta citada e sempre anexado para fornecer contexto da conversa
• Mensagens apenas com midia usam placeholders: <media:image|video|audio|document|sticker>

Mensagens Enviadas

• O texto e dividido em blocos de 4.000 caracteres por padrao (configuravel via channels.whatsapp.textChunkLimit)
• Divisao opcional por quebra de linha: defina channels.whatsapp.chunkMode="newline" para dividir nos limites de paragrafo antes da divisao por tamanho
• Tipos de midia suportados: imagem, video, audio, documento
• O audio e enviado como notas de voz (PTT). Melhores resultados com formato OGG/Opus
• Legenda apenas no primeiro item de midia
• GIFs animados: o WhatsApp espera MP4 com gifPlayback: true para reproducao em loop inline

Limites de Midia

• Limite de midia recebida: 50 MB (configuravel via channels.whatsapp.mediaMaxMb)
• Limite de midia enviada: 5 MB por item (configuravel via agents.defaults.mediaMaxMb)
• Imagens sao auto-otimizadas para JPEG quando abaixo do limite (redimensionamento + varredura de qualidade)
• Midia acima do limite resulta em erro; a resposta com midia recorre a um aviso em texto

Credenciais e Armazenamento

• Credenciais armazenadas em: ~/.openclaw/credentials/whatsapp/<accountId>/creds.json
• Backup automatico em creds.json.bak (restaurado em caso de corrupcao)
• Logout: openclaw channels logout (ou --account <id>) exclui o estado de autenticacao do WhatsApp, mas mantem o oauth.json compartilhado

Suporte a Multiplas Contas

Multiplas contas do WhatsApp podem ser executadas em um unico processo do Gateway. Use identificadores de conta na configuracao:

{
  channels: {
    whatsapp: {
      accounts: {
        personal: { /* configuracoes por conta */ },
        work: { /* configuracoes por conta */ },
      },
    },
  },
}

As configuracoes por conta suportam substituicoes para sendReadReceipts, ackReaction, mediaMaxMb, historyLimit e mais.

Por Que Nao Twilio / WhatsApp Business API?

As versoes iniciais do OpenClaw suportavam a integracao do WhatsApp Business via Twilio, mas ela foi removida porque:

• Numeros do WhatsApp Business nao sao adequados para um assistente pessoal
• A Meta impoe uma janela de resposta de 24 horas — se voce nao respondeu nas ultimas 24 horas, o numero comercial nao pode iniciar novas mensagens
• Uso de alto volume ou "conversacional" aciona bloqueios agressivos, porque contas comerciais nao foram projetadas para mensagens no estilo de assistente pessoal
• Resultado: entrega nao confiavel e bloqueios frequentes

Referencia Rapida de Configuracao

| Chave de Configuracao | Descricao | |---|---| | channels.whatsapp.dmPolicy | Politica de DM: pairing / allowlist / open / disabled | | channels.whatsapp.selfChatMode | Habilitar para configuracao com numero pessoal | | channels.whatsapp.allowFrom | Lista de permissoes de DM (numeros de telefone E.164) | | channels.whatsapp.sendReadReceipts | Confirmacoes de leitura automaticas (padrao: true) | | channels.whatsapp.ackReaction | Reacao automatica ao receber mensagem | | channels.whatsapp.groupPolicy | Politica de grupo: open / disabled / allowlist | | channels.whatsapp.textChunkLimit | Tamanho do bloco de texto de saida (padrao: 4000) | | channels.whatsapp.mediaMaxMb | Limite de midia recebida (padrao: 50 MB) | | channels.whatsapp.configWrites | Permitir gravacoes de configuracao via comando /config | | agents.defaults.mediaMaxMb | Limite de midia enviada (padrao: 5 MB) |

Solucao de Problemas

Nao Vinculado / Login QR Necessario

Sintoma: channels status mostra linked: false ou avisa "Not linked".

Solucao: Execute openclaw channels login no host do gateway e escaneie o codigo QR (WhatsApp > Configuracoes > Dispositivos Conectados).

Vinculado mas Desconectado / Loop de Reconexao

Sintoma: channels status mostra running, disconnected ou avisa "Linked but disconnected".

Solucao: Execute openclaw doctor ou reinicie o gateway. Se persistir, revincule via openclaw channels login e inspecione openclaw logs --follow.

Problemas com Runtime Bun

O Bun nao e recomendado. WhatsApp (Baileys) e Telegram sao instaveis no Bun. Execute o gateway com Node.js.

Comportamento de Reconexao

O gateway usa uma politica de backoff (web.reconnect) com initialMs, maxMs, factor, jitter e maxAttempts configuraveis. Se o numero maximo de tentativas for atingido, o monitoramento web para (modo degradado). Um socket desconectado para e requer re-vinculacao.

Proximos Passos

• Guia de integracao com Telegram
• Guia de integracao com Discord
• Documentacao oficial do WhatsApp