Pular para o conteúdo principal

​
WhatsApp (canal Web)

Status: pronto para produção via WhatsApp Web (Baileys). O Gateway gerencia a(s) sessão(ões) vinculada(s).

​
Instalação (sob demanda)

  • O onboarding (openclaw onboard) e openclaw channels add --channel whatsapp solicitam a instalação do plugin WhatsApp na primeira vez que você o seleciona.
  • openclaw channels login --channel whatsapp também oferece o fluxo de instalação quando o plugin ainda não está presente.
  • Canal dev + checkout git: usa por padrão o caminho do plugin local.
  • Stable/Beta: usa por padrão o pacote npm @openclaw/whatsapp.
A instalação manual continua disponível: 
openclaw plugins install @openclaw/whatsapp

Pairing

A política padrão de DM é pareamento para remetentes desconhecidos.

Channel troubleshooting

Diagnósticos entre canais e guias de reparo.

Gateway configuration

Padrões e exemplos completos de configuração de canal.

​
Configuração rápida

1

Configurar política de acesso do WhatsApp

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing",
      allowFrom: ["+15551234567"],
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
    },
  },
}
2

Vincular WhatsApp (QR)

openclaw channels login --channel whatsapp
Para uma conta específica:
openclaw channels login --channel whatsapp --account work
3

Iniciar o gateway

openclaw gateway
4

Aprovar a primeira solicitação de pareamento (se estiver usando o modo de pareamento)

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>
As solicitações de pareamento expiram após 1 hora. As solicitações pendentes são limitadas a 3 por canal.
O OpenClaw recomenda executar o WhatsApp em um número separado sempre que possível. (Os metadados do canal e o fluxo de configuração são otimizados para essa configuração, mas configurações com número pessoal também são compatíveis.)

​
Padrões de implantação

Este é o modo operacional mais limpo:
  • identidade do WhatsApp separada para o OpenClaw
  • allowlists de DM e limites de roteamento mais claros
  • menor chance de confusão com chat consigo mesmo
Padrão mínimo de política:
{
  channels: {
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15551234567"],
    },
  },
}
O onboarding oferece suporte ao modo com número pessoal e grava uma linha de base compatível com chat consigo mesmo:
  • dmPolicy: "allowlist"
  • allowFrom inclui seu número pessoal
  • selfChatMode: true
Em runtime, as proteções de chat consigo mesmo usam o número próprio vinculado e allowFrom.
O canal da plataforma de mensagens é baseado em WhatsApp Web (Baileys) na arquitetura atual de canais do OpenClaw.Não há um canal separado de mensagens WhatsApp via Twilio no registro integrado de canais de chat.

​
Modelo de runtime

  • O Gateway gerencia o socket do WhatsApp e o loop de reconexão.
  • Envios de saída exigem um listener ativo do WhatsApp para a conta de destino.
  • Chats de status e broadcast são ignorados (@status, @broadcast).
  • Chats diretos usam regras de sessão de DM (session.dmScope; o padrão main recolhe DMs na sessão principal do agente).
  • Sessões de grupo são isoladas (agent:<agentId>:whatsapp:group:<jid>).

​
Controle de acesso e ativação

channels.whatsapp.dmPolicy controla o acesso a chats diretos:
  • pairing (padrão)
  • allowlist
  • open (requer que allowFrom inclua "*")
  • disabled
allowFrom aceita números no estilo E.164 (normalizados internamente).Substituição para múltiplas contas: channels.whatsapp.accounts.<id>.dmPolicy (e allowFrom) têm precedência sobre os padrões no nível do canal para essa conta.Detalhes do comportamento em runtime:
  • os pareamentos são persistidos no armazenamento de allowlist do canal e mesclados com allowFrom configurado
  • se nenhuma allowlist for configurada, o número próprio vinculado é permitido por padrão
  • DMs de saída fromMe nunca são pareadas automaticamente

​
Comportamento com número pessoal e chat consigo mesmo

Quando o número próprio vinculado também está presente em allowFrom, as proteções de chat consigo mesmo do WhatsApp são ativadas:
  • ignora confirmações de leitura em interações de chat consigo mesmo
  • ignora o comportamento de acionamento automático por mention-JID que, de outra forma, faria você receber ping
  • se messages.responsePrefix não estiver definido, as respostas de chat consigo mesmo usam por padrão [{identity.name}] ou [openclaw]

​
Normalização de mensagens e contexto

As mensagens recebidas do WhatsApp são encapsuladas no envelope compartilhado de entrada.Se houver uma resposta citada, o contexto será acrescentado nesta forma:
[Replying to <sender> id:<stanzaId>]
<quoted body or media placeholder>
[/Replying]
Campos de metadados de resposta também são preenchidos quando disponíveis (ReplyToId, ReplyToBody, ReplyToSender, sender JID/E.164).
Mensagens de entrada somente com mídia são normalizadas com placeholders como:
  • <media:image>
  • <media:video>
  • <media:audio>
  • <media:document>
  • <media:sticker>
Cargas de localização e contato são normalizadas em contexto textual antes do roteamento.
Para grupos, mensagens não processadas podem ser armazenadas em buffer e injetadas como contexto quando o bot finalmente é acionado.
  • limite padrão: 50
  • configuração: channels.whatsapp.historyLimit
  • fallback: messages.groupChat.historyLimit
  • 0 desabilita
Marcadores de injeção:
  • [Chat messages since your last reply - for context]
  • [Current message - respond to this]
As confirmações de leitura são habilitadas por padrão para mensagens de entrada do WhatsApp aceitas.Desabilite globalmente:
{
  channels: {
    whatsapp: {
      sendReadReceipts: false,
    },
  },
}
Substituição por conta:
{
  channels: {
    whatsapp: {
      accounts: {
        work: {
          sendReadReceipts: false,
        },
      },
    },
  },
}
Interações de chat consigo mesmo ignoram confirmações de leitura mesmo quando habilitadas globalmente.

​
Entrega, divisão em blocos e mídia

  • limite padrão de bloco: channels.whatsapp.textChunkLimit = 4000
  • channels.whatsapp.chunkMode = "length" | "newline"
  • o modo newline prefere limites de parágrafo (linhas em branco) e depois usa divisão segura por comprimento como fallback
  • oferece suporte a cargas de imagem, vídeo, áudio (nota de voz PTT) e documento
  • audio/ogg é reescrito para audio/ogg; codecs=opus para compatibilidade com notas de voz
  • a reprodução de GIF animado é compatível por meio de gifPlayback: true em envios de vídeo
  • legendas são aplicadas ao primeiro item de mídia ao enviar cargas de resposta com múltiplas mídias
  • a origem da mídia pode ser HTTP(S), file:// ou caminhos locais
  • limite de salvamento de mídia de entrada: channels.whatsapp.mediaMaxMb (padrão 50)
  • limite de envio de mídia de saída: channels.whatsapp.mediaMaxMb (padrão 50)
  • substituições por conta usam channels.whatsapp.accounts.<accountId>.mediaMaxMb
  • imagens são otimizadas automaticamente (varredura de redimensionamento/qualidade) para caber nos limites
  • em falha de envio de mídia, o fallback do primeiro item envia um aviso em texto em vez de descartar a resposta silenciosamente

​
Nível de reação

channels.whatsapp.reactionLevel controla com que amplitude o agente usa reações com emoji no WhatsApp:
NívelReações de ackReações iniciadas pelo agenteDescrição
"off"NãoNãoNenhuma reação
"ack"SimNãoApenas reações de ack (confirmação pré-resposta)
"minimal"SimSim (conservadoras)Ack + reações do agente com orientação conservadora
"extensive"SimSim (incentivadas)Ack + reações do agente com orientação incentivada
Padrão: "minimal". Substituições por conta usam channels.whatsapp.accounts.<id>.reactionLevel. 
{
  channels: {
    whatsapp: {
      reactionLevel: "ack",
    },
  },
}

​
Reações de confirmação

O WhatsApp oferece suporte a reações imediatas de ack no recebimento de entrada via channels.whatsapp.ackReaction. As reações de ack são controladas por reactionLevel — elas são suprimidas quando reactionLevel é "off". 
{
  channels: {
    whatsapp: {
      ackReaction: {
        emoji: "👀",
        direct: true,
        group: "mentions", // always | mentions | never
      },
    },
  },
}
Observações de comportamento:
  • enviadas imediatamente após a entrada ser aceita (antes da resposta)
  • falhas são registradas em log, mas não bloqueiam a entrega normal da resposta
  • no modo de grupo mentions, reage em interações acionadas por menção; a ativação de grupo always funciona como bypass para essa verificação
  • o WhatsApp usa channels.whatsapp.ackReaction (o legado messages.ackReaction não é usado aqui)

​
Múltiplas contas e credenciais

  • ids de conta vêm de channels.whatsapp.accounts
  • seleção da conta padrão: default se estiver presente; caso contrário, o primeiro id de conta configurado (ordenado)
  • ids de conta são normalizados internamente para consulta
  • caminho de autenticação atual: ~/.openclaw/credentials/whatsapp/<accountId>/creds.json
  • arquivo de backup: creds.json.bak
  • a autenticação legada padrão em ~/.openclaw/credentials/ ainda é reconhecida/migrada para fluxos de conta padrão
openclaw channels logout --channel whatsapp [--account <id>] limpa o estado de autenticação do WhatsApp para essa conta.Em diretórios de autenticação legados, oauth.json é preservado enquanto arquivos de autenticação do Baileys são removidos.

​
Ferramentas, ações e escritas de configuração

  • O suporte a ferramentas do agente inclui a ação de reação do WhatsApp (react).
  • Portas de ação:
    • channels.whatsapp.actions.reactions
    • channels.whatsapp.actions.polls
  • Escritas de configuração iniciadas pelo canal são habilitadas por padrão (desabilite com channels.whatsapp.configWrites=false).

​
Solução de problemas

Sintoma: o status do canal informa que não está vinculado.Correção:
openclaw channels login --channel whatsapp
openclaw channels status
Sintoma: conta vinculada com desconexões repetidas ou tentativas de reconexão.Correção:
openclaw doctor
openclaw logs --follow
Se necessário, vincule novamente com channels login.
Envios de saída falham rapidamente quando não existe um listener ativo do gateway para a conta de destino.Certifique-se de que o gateway está em execução e a conta está vinculada.
Verifique nesta ordem:
  • groupPolicy
  • groupAllowFrom / allowFrom
  • entradas da allowlist groups
  • controle por menção (requireMention + padrões de menção)
  • chaves duplicadas em openclaw.json (JSON5): entradas posteriores sobrescrevem as anteriores, então mantenha um único groupPolicy por escopo
O runtime do gateway do WhatsApp deve usar Node. Bun é marcado como incompatível para operação estável do gateway WhatsApp/Telegram.

​
Ponteiros para referência de configuração

Referência principal: Campos importantes do WhatsApp:
  • acesso: dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups
  • entrega: textChunkLimit, chunkMode, mediaMaxMb, sendReadReceipts, ackReaction, reactionLevel
  • múltiplas contas: accounts.<id>.enabled, accounts.<id>.authDir, substituições no nível da conta
  • operações: configWrites, debounceMs, web.enabled, web.heartbeatSeconds, web.reconnect.*
  • comportamento de sessão: session.dmScope, historyLimit, dmHistoryLimit, dms.<id>.historyLimit

​
Relacionado