WhatsApp (canal web)

Status: pronto para produção via WhatsApp Web (Baileys). O gateway é responsável pela(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 do WhatsApp na primeira vez em 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 local do plugin.
Stable/Beta: usa por padrão o pacote npm @openclaw/whatsapp.

A instalação manual continua disponível:

openclaw plugins install @openclaw/whatsapp

Pareamento

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

Solução de problemas de canais

Diagnósticos entre canais e guias de correção.

Configuração do gateway

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

Configuração rápida

Configurar a política de acesso do WhatsApp

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

Vincular o WhatsApp (QR)

openclaw channels login --channel whatsapp

Para uma conta específica:

openclaw channels login --channel whatsapp --account work

Iniciar o gateway

openclaw gateway

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

Número dedicado (recomendado)

Este é o modo operacional mais limpo:

identidade do WhatsApp separada para o OpenClaw
allowlists de MD e limites de roteamento mais claros
menor chance de confusão com conversa consigo mesmo

Padrão mínimo de política:

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

Alternativa com número pessoal

O onboarding é compatível com o modo de número pessoal e grava uma base amigável para conversa consigo mesmo:

dmPolicy: "allowlist"
allowFrom inclui o seu número pessoal
selfChatMode: true

Em tempo de execução, as proteções de conversa consigo mesmo se baseiam no próprio número vinculado e em allowFrom.

Escopo do canal somente WhatsApp Web

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 do WhatsApp via Twilio no registro integrado de canais de chat.

Modelo de execução

O gateway controla 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 MD (session.dmScope; por padrão, main recolhe MDs na sessão principal do agente).
Sessões de grupo são isoladas (agent:<agentId>:whatsapp:group:<jid>).
O transporte do WhatsApp Web respeita variáveis de ambiente padrão de proxy no host do gateway (HTTPS_PROXY, HTTP_PROXY, NO_PROXY / variantes em minúsculas). Prefira a configuração de proxy no nível do host em vez de configurações de proxy específicas do canal WhatsApp.

Controle de acesso e ativação

Política de MD
Política de grupo + allowlists
Menções + /activation

channels.whatsapp.dmPolicy controla o acesso ao chat direto:

pairing (padrão)
allowlist
open (exige que allowFrom inclua "*")
disabled

allowFrom aceita números no estilo E.164 (normalizados internamente).Substituição por 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 tempo de execução:

pareamentos são persistidos no armazenamento de permissão do canal e mesclados com allowFrom configurado
se nenhuma allowlist estiver configurada, o próprio número vinculado será permitido por padrão
MDs de saída fromMe nunca são pareadas automaticamente

O acesso a grupos tem duas camadas:

Allowlist de pertencimento ao grupo (channels.whatsapp.groups)
- se groups for omitido, todos os grupos serão elegíveis
- se groups estiver presente, ele atua como uma allowlist de grupos ("*" permitido)
Política de remetente do grupo (channels.whatsapp.groupPolicy + groupAllowFrom)
- open: a allowlist de remetentes é ignorada
- allowlist: o remetente deve corresponder a groupAllowFrom (ou *)
- disabled: bloqueia toda entrada de grupos

Fallback da allowlist de remetentes:

se groupAllowFrom não estiver definido, o tempo de execução usa allowFrom como fallback quando disponível
as allowlists de remetentes são avaliadas antes da ativação por menção/resposta

Observação: se não existir nenhum bloco channels.whatsapp, o fallback da política de grupo em tempo de execução será allowlist (com um log de aviso), mesmo que channels.defaults.groupPolicy esteja definido.

Respostas em grupo exigem menção por padrão.A detecção de menção inclui:

menções explícitas no WhatsApp à identidade do bot
padrões regex de menção configurados (agents.list[].groupChat.mentionPatterns, fallback messages.groupChat.mentionPatterns)
detecção implícita de resposta ao bot (o remetente da resposta corresponde à identidade do bot)

Observação de segurança:

citação/resposta apenas satisfaz o bloqueio de menção; isso não concede autorização ao remetente
com groupPolicy: "allowlist", remetentes fora da allowlist continuam bloqueados mesmo que respondam à mensagem de um usuário incluído na allowlist

Comando de ativação no nível da sessão:

/activation mention
/activation always

activation atualiza o estado da sessão (não a configuração global). É protegido por permissão de proprietário.

Comportamento com número pessoal e conversa consigo mesmo

Quando o próprio número vinculado também está presente em allowFrom, as proteções de conversa consigo mesmo do WhatsApp são ativadas:

ignora confirmações de leitura em interações de conversa consigo mesmo
ignora o comportamento de acionamento automático por menção-JID que, de outra forma, notificaria você mesmo
se messages.responsePrefix não estiver definido, respostas em conversa consigo mesmo usam por padrão [{identity.name}] ou [openclaw]

Normalização de mensagens e contexto

Envelope de entrada + contexto de resposta

As mensagens recebidas do WhatsApp são encapsuladas no envelope compartilhado de entrada.Se existir uma resposta citada, o contexto será acrescentado neste formato:

[Respondendo a <sender> id:<stanzaId>]
<corpo citado ou placeholder de mídia>
[/Respondendo]

Os campos de metadados de resposta também são preenchidos quando disponíveis (ReplyToId, ReplyToBody, ReplyToSender, JID/E.164 do remetente).

Placeholders de mídia e extração de localização/contato

Mensagens recebidas contendo apenas 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.

Injeção de histórico pendente de grupo

Para grupos, mensagens não processadas podem ser armazenadas em buffer e injetadas como contexto quando o bot finalmente for acionado.

limite padrão: 50
configuração: channels.whatsapp.historyLimit
fallback: messages.groupChat.historyLimit
0 desativa

Marcadores de injeção:

[Mensagens do chat desde a sua última resposta - para contexto]
[Mensagem atual - responda a esta]

Confirmações de leitura

As confirmações de leitura ficam ativadas por padrão para mensagens recebidas do WhatsApp aceitas.Desative globalmente:

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

Substituição por conta:

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

Interações de conversa consigo mesmo ignoram confirmações de leitura mesmo quando ativadas globalmente.

Entrega, segmentação e mídia

Segmentação de texto

limite padrão de segmento: channels.whatsapp.textChunkLimit = 4000
channels.whatsapp.chunkMode = "length" | "newline"
o modo newline prefere limites de parágrafo (linhas em branco) e depois recorre à segmentação segura por tamanho

Comportamento de mídia de saída

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 nota de voz
a reprodução de GIF animado é compatível via gifPlayback: true em envios de vídeo
legendas são aplicadas ao primeiro item de mídia ao enviar cargas de resposta com várias mídias
a origem da mídia pode ser HTTP(S), file:// ou caminhos locais

Limites de tamanho de mídia e comportamento de fallback

limite de salvamento de mídia recebida: 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 caso de falha no 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ções

channels.whatsapp.reactionLevel controla quão amplamente o agente usa reações com emoji no WhatsApp:

Nível	Reações de confirmação	Reações iniciadas pelo agente	Descrição
`"off"`	Não	Não	Nenhuma reação
`"ack"`	Sim	Não	Somente reações de confirmação (recibo pré-resposta)
`"minimal"`	Sim	Sim (conservadoras)	Confirmação + reações do agente com orientação conservadora
`"extensive"`	Sim	Sim (incentivadas)	Confirmação + 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 confirmação no recebimento via channels.whatsapp.ackReaction. As reações de confirmação 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 (pré-resposta)
falhas são registradas em log, mas não bloqueiam a entrega normal da resposta
o modo de grupo mentions reage em interações acionadas por menção; a ativação de grupo always funciona como desvio dessa verificação
o WhatsApp usa channels.whatsapp.ackReaction (o legado messages.ackReaction não é usado aqui)

Múltiplas contas e credenciais

Seleção de conta e padrões

os ids de conta vêm de channels.whatsapp.accounts
seleção de conta padrão: default se estiver presente; caso contrário, o primeiro id de conta configurado (ordenado)
os ids de conta são normalizados internamente para consulta

Caminhos de credenciais e compatibilidade legada

caminho de autenticação atual: ~/.openclaw/credentials/whatsapp/<accountId>/creds.json
arquivo de backup: creds.json.bak
a autenticação padrão legada em ~/.openclaw/credentials/ ainda é reconhecida/migrada para fluxos de conta padrão

Comportamento de logout

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 os arquivos de autenticação do Baileys são removidos.

Ferramentas, ações e gravações de configuração

O suporte a ferramentas do agente inclui a ação de reação do WhatsApp (react).
Bloqueios de ação:
- channels.whatsapp.actions.reactions
- channels.whatsapp.actions.polls
Gravações de configuração iniciadas pelo canal ficam ativadas por padrão (desative com channels.whatsapp.configWrites=false).

Solução de problemas

Não vinculado (QR necessário)

Sintoma: o status do canal informa que não está vinculado.Correção:

openclaw channels login --channel whatsapp
openclaw channels status

Vinculado, mas desconectado / loop de reconexão

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.

Nenhum listener ativo ao enviar

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 de que a conta está vinculada.

Mensagens de grupo inesperadamente ignoradas

Verifique nesta ordem:

groupPolicy
groupAllowFrom / allowFrom
entradas da allowlist groups
bloqueio por menção (requireMention + padrões de menção)
chaves duplicadas em openclaw.json (JSON5): entradas posteriores substituem as anteriores, então mantenha um único groupPolicy por escopo

Aviso de runtime do Bun

O runtime do gateway do WhatsApp deve usar Node. O Bun é sinalizado como incompatível para operação estável do gateway do WhatsApp/Telegram.

Ponteiros da referência de configuração

Referência principal:

Referência de configuração - WhatsApp

Campos de WhatsApp de alto sinal:

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 da sessão: session.dmScope, historyLimit, dmHistoryLimit, dms.<id>.historyLimit

Overview

Messaging platforms

Configuration

WhatsApp

WhatsApp (canal web)

Instalação (sob demanda)

Pareamento

Solução de problemas de canais

Configuração do gateway

Configuração rápida

Padrões de implantação

Modelo de execução

Controle de acesso e ativação

Comportamento com número pessoal e conversa consigo mesmo

Normalização de mensagens e contexto

Entrega, segmentação e mídia

Nível de reações

Reações de confirmação

Múltiplas contas e credenciais

Ferramentas, ações e gravações de configuração

Solução de problemas

Ponteiros da referência de configuração

Relacionados

Overview

Messaging platforms

Configuration

​WhatsApp (canal web)

​Instalação (sob demanda)

Pareamento

Solução de problemas de canais

Configuração do gateway

​Configuração rápida

​Padrões de implantação

​Modelo de execução

​Controle de acesso e ativação

​Comportamento com número pessoal e conversa consigo mesmo

​Normalização de mensagens e contexto

​Entrega, segmentação e mídia

​Nível de reações

​Reações de confirmação

​Múltiplas contas e credenciais

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

​Solução de problemas

​Ponteiros da referência de configuração

​Relacionados

WhatsApp (canal web)

Instalação (sob demanda)

Configuração rápida

Padrões de implantação

Modelo de execução

Controle de acesso e ativação

Comportamento com número pessoal e conversa consigo mesmo

Normalização de mensagens e contexto

Entrega, segmentação e mídia

Nível de reações

Reações de confirmação

Múltiplas contas e credenciais

Ferramentas, ações e gravações de configuração

Solução de problemas

Ponteiros da referência de configuração

Relacionados