WhatsApp

Status: pronto para produção via WhatsApp Web (Baileys). O Gateway gerencia as sessões vinculadas; não há um canal separado do Twilio WhatsApp.

Instalação

openclaw onboard e openclaw channels add --channel whatsapp solicitam a instalação do plugin na primeira vez que ele é selecionado; openclaw channels login --channel whatsapp oferece o mesmo fluxo de instalação se o plugin estiver ausente. Checkouts de desenvolvimento usam o caminho local do plugin; instalações stable/beta instalam primeiro o @openclaw/whatsapp pelo ClawHub, com fallback para o npm. O runtime do WhatsApp é distribuído fora do pacote npm principal do OpenClaw, portanto suas dependências de runtime permanecem com o plugin externo. Instalação manual:

openclaw plugins install clawhub:@openclaw/whatsapp

Use o pacote npm sem qualificação (@openclaw/whatsapp) somente para o fallback do registro; fixe uma versão exata somente para uma instalação reproduzível.

Configuração rápida

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

openclaw channels login --channel whatsapp

openclaw channels login --channel whatsapp --account work

openclaw channels add --channel whatsapp --account work --auth-dir /path/to/wa-authopenclaw channels login --channel whatsapp --account work

openclaw gateway

openclaw pairing list whatsappopenclaw pairing approve whatsapp <CODE>

Padrões de implantação

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

Modelo de runtime

• O Gateway gerencia o socket do WhatsApp e o ciclo de reconexão.
• Um watchdog monitora dois sinais independentemente: a atividade bruta do transporte do WhatsApp Web e a atividade de mensagens do aplicativo. Uma sessão silenciosa, mas conectada, não é reiniciada apenas porque nenhuma mensagem chegou recentemente; ele força a reconexão somente quando os frames de transporte deixam de chegar durante uma janela interna fixa (não configurável pelo usuário) ou quando as mensagens do aplicativo permanecem ausentes por mais de 4x o tempo limite normal de mensagens. Logo após uma reconexão de uma sessão recentemente ativa, essa primeira janela usa o tempo limite normal de mensagens, mais curto, em vez da janela de 4x. O OpenClaw pode responder automaticamente às mensagens offline que o Baileys entrega no início dessa reconexão, limitado pelo período de vida da desduplicação de IDs de mensagens de entrada; a inicialização inicial mantém a proteção curta contra histórico obsoleto.
• Os tempos do socket do Baileys são explícitos em web.whatsapp.*: keepAliveIntervalMs (intervalo de ping do aplicativo), connectTimeoutMs (tempo limite do handshake inicial), defaultQueryTimeoutMs (esperas de consultas do Baileys, além dos tempos limite do OpenClaw para envio/presença de saída e confirmação de leitura de entrada).
• Os envios de saída exigem um listener ativo do WhatsApp para a conta de destino; caso contrário, os envios falham imediatamente.
• Os envios para grupos incluem metadados nativos de menção para tokens @+<digits> e @<digits> (no texto e nas legendas de mídia) quando o token corresponde aos metadados atuais de participantes, inclusive em grupos baseados em LID.
• Chats de status e transmissão (@status, @broadcast) são ignorados.
• Chats diretos usam regras de sessão de MD (session.dmScope; o padrão main reúne as MDs na sessão principal do agente). As sessões de grupo são isoladas por JID (agent:<agentId>:whatsapp:group:<jid>).
• Canais/Newsletters do WhatsApp podem ser destinos explícitos de saída por meio de seu JID @newsletter nativo, usando metadados de sessão do canal (agent:<agentId>:whatsapp:channel:<jid>) em vez da semântica de MD.
• O transporte do WhatsApp Web respeita as variáveis de ambiente padrão de proxy no host do Gateway (HTTPS_PROXY, HTTP_PROXY, NO_PROXY, incluindo variantes em minúsculas). Prefira a configuração de proxy no nível do host às configurações por canal.
• Com messages.removeAckAfterReply habilitado, o OpenClaw remove a reação de confirmação depois que uma resposta visível é entregue.

Ligar para o solicitante atual com o MeowCaller (experimental)

O plugin pode disponibilizar whatsapp_call em turnos do agente originados no WhatsApp. Ele usa o MeowCaller para realizar uma chamada de voz pelo WhatsApp para o solicitante autorizado atual e reproduzir uma mensagem TTS do OpenClaw após o atendimento. A ferramenta não tem parâmetro de número de destino, portanto um prompt não pode redirecionar a chamada. Desabilitado por padrão.

{"channels": {"whatsapp": {  "actions": {    "calls": true  }}}}

git clone --branch feat/send-only-notify https://github.com/steipete/meowcaller.gitcd meowcallergit checkout 752050471fc2bf7a8cdfbf7dbd3cd4e865d85d3fmkdir -p "$HOME/.local/bin"go build -o "$HOME/.local/bin/meowcaller" ./cmd/meowcaller

state_dir="$HOME/.openclaw/credentials/whatsapp-calls/default"mkdir -p "$state_dir"chmod 700 "$state_dir"meowcaller pair --store "$state_dir/wa-voip.db"

Limites: somente chamadas de áudio individuais de saída, nenhum número de destino arbitrário, nenhuma autenticação compartilhada com a conexão de chat, nenhuma chamada para si próprio no modo de número pessoal/chat consigo mesmo, áudio sintetizado limitado a 60 segundos, nenhuma confirmação de audibilidade no aparelho além da conclusão de atendimento/reprodução/encerramento do MeowCaller, e o OpenClaw encerra o processo complementar após uma janela limitada de 115-175 segundos (abrangendo as fases de conexão, atendimento, reprodução e encerramento do MeowCaller).

Solicitações de aprovação

O WhatsApp pode renderizar solicitações de aprovação de execução e plugins como reações 👍/👎, controladas pela configuração de encaminhamento de aprovações no nível superior:

{  approvals: {    exec: {      enabled: true,      mode: "session",    },    plugin: {      enabled: true,      mode: "targets",      targets: [{ channel: "whatsapp", to: "+15551234567" }],    },  },}

approvals.exec e approvals.plugin são independentes; habilitar o WhatsApp como canal apenas vincula o transporte e não envia nada, a menos que a família de aprovações correspondente esteja habilitada e roteada para ele. O modo de sessão entrega aprovações nativas por emoji somente para aprovações originadas no WhatsApp. O modo de destino usa o pipeline de encaminhamento compartilhado para destinos explícitos e não cria uma distribuição separada para MDs de aprovadores.

As reações de aprovação do WhatsApp exigem aprovadores explícitos em allowFrom (ou "*"). defaultTo define destinos de mensagens padrão comuns, não uma lista de aprovadores. Comandos manuais /approve ainda passam pelo fluxo normal de autorização de remetentes do WhatsApp antes da resolução da aprovação.

Hooks de plugins e privacidade

As mensagens de entrada do WhatsApp podem conter conteúdo pessoal, números de telefone, identificadores de grupos, nomes de remetentes e campos de correlação de sessões. O WhatsApp não transmite payloads do hook de entrada message_received aos plugins, a menos que essa opção seja habilitada:

{  channels: {    whatsapp: {      pluginHooks: {        messageReceived: true,      },    },  },}

Restrinja a habilitação a uma conta em channels.whatsapp.accounts.<id>.pluginHooks.messageReceived. Habilite isso somente para plugins nos quais se confia para acessar o conteúdo e os identificadores de entrada do WhatsApp.

Controle de acesso e ativação

Vinculações de ACP configuradas

O WhatsApp oferece suporte a vinculações persistentes de ACP por meio de bindings[] no nível superior:

{  bindings: [    {      type: "acp",      agentId: "codex",      match: {        channel: "whatsapp",        accountId: "work",        peer: { kind: "direct", id: "+15555550123" },      },    },    {      type: "acp",      agentId: "codex",      match: {        channel: "whatsapp",        accountId: "work",        peer: { kind: "group", id: "120363424282127706@g.us" },      },    },  ],}

Conversas diretas correspondem a números E.164; grupos correspondem a JIDs de grupos do WhatsApp. As listas de permissões de grupos, a política de remetentes e o controle de menção/ativação são executados antes que o OpenClaw garanta a existência da sessão de ACP vinculada. Uma vinculação correspondente controla a rota — grupos de transmissão não distribuem esse turno para sessões comuns do WhatsApp.

Comportamento de número pessoal e conversa consigo mesmo

Quando o próprio número vinculado também está presente em allowFrom, as proteções para conversas consigo mesmo são ativadas: ignoram confirmações de leitura nesses turnos, ignoram o comportamento de acionamento automático por JID de menção que enviaria uma notificação para você mesmo e direcionam as respostas por padrão a [{identity.name}] (ou [openclaw]) quando messages.responsePrefix não está definido.

Normalização de mensagens e contexto

[Replying to <sender> id:<stanzaId>]<quoted body or media placeholder>[/Replying]

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

Entrega, divisão em partes e mídia

Citação de respostas

channels.whatsapp.replyToMode controla a citação nativa de respostas (as respostas de saída citam visivelmente a mensagem recebida):

Substituição por conta: channels.whatsapp.accounts.<id>.replyToMode.

{ channels: { whatsapp: { replyToMode: "first" } } }

Nível de reações

channels.whatsapp.reactionLevel controla a abrangência do uso de reações com emojis pelo agente:

Substituição por conta: channels.whatsapp.accounts.<id>.reactionLevel.

{ channels: { whatsapp: { reactionLevel: "ack" } } }

Reações de confirmação

channels.whatsapp.ackReaction envia uma reação imediata ao receber uma mensagem, controlada por reactionLevel (suprimida quando "off"):

{  channels: {    whatsapp: {      ackReaction: {        emoji: "👀",        direct: true,        group: "mentions", // always | mentions | never      },    },  },}

Observações: enviada imediatamente após a aceitação da mensagem de entrada (antes da resposta); se ackReaction estiver presente sem emoji, o WhatsApp usará o emoji de identidade do agente encaminhado, com fallback para "👀" (omita ackReaction ou defina emoji: "" para não enviar confirmação); as falhas são registradas, mas não bloqueiam a entrega da resposta; o modo de grupo mentions reage apenas em turnos acionados por menção, enquanto a ativação de grupo always ignora essa verificação; o WhatsApp usa apenas channels.whatsapp.ackReaction (o messages.ackReaction legado não se aplica aqui).

Reações de status do ciclo de vida

Defina messages.statusReactions.enabled: true para permitir que o WhatsApp substitua a reação de confirmação durante um turno, em vez de manter um emoji de recebimento estático, alternando entre estados como na fila, pensando, atividade de ferramenta, Compaction, concluído e erro:

{  messages: {    statusReactions: {      enabled: true,      emojis: {        deploy: "🛫",        build: "🏗️",        concierge: "💁",      },    },  },}

Observações: channels.whatsapp.ackReaction ainda controla a elegibilidade para mensagens diretas e grupos; o estado na fila usa o mesmo emoji efetivo das reações de confirmação simples; o WhatsApp tem um slot de reação do bot por mensagem, portanto, as atualizações do ciclo de vida substituem a reação atual no mesmo lugar; messages.removeAckAfterReply: true remove a reação de status final após o período configurado de permanência do estado concluído/erro; as categorias de emoji de ferramentas incluem tool, coding, web, deploy, build e concierge.

Várias contas e credenciais

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).
• Controles de ações: channels.whatsapp.actions.reactions, channels.whatsapp.actions.polls (as ações existentes usam true por padrão), channels.whatsapp.actions.calls (padrão false, consulte MeowCaller acima).
• As gravações de configuração iniciadas pelo canal são habilitadas por padrão; desabilite-as por meio de channels.whatsapp.configWrites: false.

Solução de problemas

openclaw channels login --channel whatsappopenclaw channels status

{  web: {    whatsapp: {      keepAliveIntervalMs: 15000,      connectTimeoutMs: 60000,      defaultQueryTimeoutMs: 60000,    },  },}

openclaw channels status --probeopenclaw doctoropenclaw logs --followopenclaw gateway status

cp -a ~/.openclaw/credentials/whatsapp/<accountId> \  ~/.openclaw/credentials/whatsapp/<accountId>.bakopenclaw channels logout --channel whatsapp --account <accountId>openclaw channels login --channel whatsapp --account <accountId>

Prompts de sistema

O WhatsApp oferece suporte a prompts de sistema no estilo do Telegram para grupos e conversas diretas por meio dos mapas groups e direct.

Resolução para mensagens de grupo: primeiro, determina-se o mapa groups efetivo — se a conta definir sua própria chave groups, ela substituirá completamente o mapa raiz groups (sem mesclagem profunda). Em seguida, a consulta do prompt é executada nesse único mapa resultante:

1. Prompt específico do grupo (groups["<groupId>"].systemPrompt): usado quando a entrada do grupo existe e sua chave systemPrompt está definida. Uma string vazia ("") suprime o curinga e não aplica nenhum prompt.
2. Prompt curinga do grupo (groups["*"].systemPrompt): usado quando a entrada específica do grupo está ausente ou existe sem uma chave systemPrompt.

A resolução para mensagens diretas segue o mesmo padrão no mapa direct e em direct["*"].

Diferença em relação ao Telegram: o Telegram suprime o groups raiz para todas as contas em uma configuração com várias contas (até mesmo para contas sem um groups próprio), para impedir que um bot receba mensagens de grupos dos quais não participa. O WhatsApp não aplica essa proteção — groups/direct raiz são herdados por qualquer conta sem uma substituição própria, independentemente da quantidade de contas. Em uma configuração do WhatsApp com várias contas, defina explicitamente o mapa completo em cada conta se quiser prompts específicos por conta.

Comportamentos importantes:

• channels.whatsapp.groups é tanto um mapa de configuração por grupo quanto a lista de permissões de grupos no nível da conversa. No escopo raiz ou da conta, groups["*"] significa "todos os grupos são admitidos" nesse escopo.
• Adicione um curinga systemPrompt somente quando já quiser que esse escopo admita todos os grupos. Para manter apenas um conjunto fixo de ids de grupo elegíveis, repita o prompt em cada entrada explicitamente permitida em vez de usar groups["*"].
• A admissão do grupo e a autorização do remetente são verificações separadas. groups["*"] amplia quais grupos chegam ao processamento de grupos; isso não autoriza todos os remetentes nesses grupos — esse controle continua sendo feito por groupPolicy/groupAllowFrom.
• channels.whatsapp.direct não tem efeito colateral equivalente para mensagens diretas: direct["*"] apenas fornece uma configuração padrão depois que uma mensagem direta já foi admitida por dmPolicy em conjunto com allowFrom ou com as regras do armazenamento de pareamento.

Exemplo:

{  channels: {    whatsapp: {      groups: {        // Use somente se todos os grupos devam ser admitidos no escopo raiz.        // Aplica-se a todas as contas que não definem seu próprio mapa groups.        "*": { systemPrompt: "Prompt padrão para todos os grupos." },      },      direct: {        // Aplica-se a todas as contas que não definem seu próprio mapa direct.        "*": { systemPrompt: "Prompt padrão para todas as conversas diretas." },      },      accounts: {        work: {          groups: {            // Esta conta define seu próprio groups; portanto, o groups raiz é            // completamente substituído. Para manter um curinga, defina "*" explicitamente aqui também.            "120363406415684625@g.us": {              requireMention: false,              systemPrompt: "Concentre-se no gerenciamento de projetos.",            },            // Use somente se todos os grupos devam ser admitidos nesta conta.            "*": { systemPrompt: "Prompt padrão para grupos de trabalho." },          },          direct: {            // Esta conta define seu próprio mapa direct; portanto, as entradas direct            // raiz são completamente substituídas. Para manter um curinga, defina "*" explicitamente aqui também.            "+15551234567": { systemPrompt: "Prompt para uma conversa direta de trabalho específica." },            "*": { systemPrompt: "Prompt padrão para conversas diretas de trabalho." },          },        },      },    },  },}

Referências da configuração

Referência principal: Referência de configuração - WhatsApp

Relacionados

• Pareamento
• Grupos
• Segurança
• Roteamento de canais
• Roteamento multiagente
• Solução de problemas