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 para WhatsApp.

Instalação

openclaw onboard e openclaw channels add --channel whatsapp solicitam a instalação do plugin na primeira vez que você o seleciona; 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 estáveis/beta instalam primeiro @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 prefixo (@openclaw/whatsapp) somente para o fallback do registro; fixe uma versão exata apenas 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 de forma independente: 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; ela força uma reconexão somente quando os frames de transporte param de chegar durante uma janela interna fixa (não configurável pelo usuário) ou quando as mensagens do aplicativo permanecem inativas além de quatro vezes o tempo limite normal de mensagens. Logo após uma reconexão de uma sessão recentemente ativa, a primeira janela usa o tempo limite normal de mensagens, mais curto, em vez da janela quatro vezes maior. O OpenClaw pode responder automaticamente a mensagens offline que o Baileys entrega no início dessa reconexão, limitado pelo período de deduplicação dos IDs das mensagens recebidas; a inicialização mantém a proteção curta contra histórico obsoleto.
• Os tempos do socket do Baileys são definidos explicitamente em web.whatsapp.*: keepAliveIntervalMs (intervalo de ping do aplicativo), connectTimeoutMs (tempo limite do handshake de abertura), defaultQueryTimeoutMs (esperas de consultas do Baileys, além dos tempos limite de envio/presença de saída e confirmação de leitura de entrada do OpenClaw).
• Os envios de saída exigem um listener ativo do WhatsApp para a conta de destino; caso contrário, falham imediatamente.
• Os envios para grupos anexam 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 um participante, inclusive em grupos baseados em LID.
• Conversas de status e transmissão (@status, @broadcast) são ignoradas.
• Conversas diretas usam as 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/boletins informativos do WhatsApp podem ser destinos explícitos de saída por meio de seu JID nativo @newsletter, usando metadados de sessão de 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 e 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 fazer uma chamada de voz pelo WhatsApp ao solicitante autorizado atual e reproduzir uma mensagem de TTS do OpenClaw depois que ele atender. A ferramenta não possui parâmetro de número de destino, portanto um prompt não pode redirecionar a chamada. Desabilitada 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 de saída individuais, sem números de destino arbitrários, sem autenticação compartilhada com a conexão de chat, sem chamadas para si próprio no modo de número pessoal/conversa consigo mesmo, áudio sintetizado limitado a 60 segundos, sem 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 a 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 fornece aprovações nativas por emoji somente para aprovações originadas no WhatsApp. O modo de destino usa o pipeline compartilhado de encaminhamento 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 padrão para mensagens comuns, não uma lista de aprovadores. Comandos manuais /approve ainda passam pelo fluxo normal de autorização do remetente do WhatsApp antes da resolução da aprovação.

Hooks de plugins e privacidade

Mensagens recebidas do WhatsApp podem conter conteúdo pessoal, números de telefone, identificadores de grupos, nomes de remetentes e campos de correlação de sessão. O WhatsApp não transmite payloads do hook message_received de mensagens recebidas para plugins, a menos que você habilite explicitamente essa opção:

{  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 você confia para acessar conteúdo e identificadores recebidos pelo WhatsApp.

Controle de acesso e ativação

Vinculações ACP configuradas

O WhatsApp oferece suporte a vinculações ACP persistentes 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 grupo do WhatsApp. Listas de permissões de grupos, a política de remetentes e o requisito de menção/ativação são processados antes que o OpenClaw garanta a existência da sessão ACP vinculada. Uma vinculação correspondente assume o controle da 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: as confirmações de leitura são ignoradas nesses turnos, o comportamento de acionamento automático por JID de menção que enviaria uma notificação para você mesmo é ignorado e as respostas usam [{identity.name}] (ou [openclaw]) por padrão quando messages.responsePrefix não está definido.

Normalização de mensagens e contexto

[Respondendo a <sender> id:<stanzaId>]<corpo citado ou espaço reservado de mídia>[/Respondendo]

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

Entrega, divisão em blocos 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, condicionada por reactionLevel (suprimida quando definido como "off"):

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

Observações: enviada imediatamente após a mensagem recebida ser aceita (antes da resposta); se ackReaction estiver presente sem emoji, o WhatsApp usará o emoji de identidade do agente responsável pela rota, 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 estático de recebimento, 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 simples de confirmação; o WhatsApp tem um único espaço de reação do bot por mensagem, portanto as atualizações do ciclo de vida substituem a reação atual no mesmo local; 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 emojis 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 têm true como 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 com 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 do sistema

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

Resolução para mensagens de grupo: primeiro, o mapa groups efetivo é determinado — se a conta definir sua própria chave groups, ela substituirá completamente o mapa groups raiz (sem mesclagem profunda). Em seguida, a busca do prompt é realizada 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), evitando que um bot receba mensagens de grupos aos quais não pertence. 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 funciona tanto como um mapa de configuração por grupo quanto como 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 permitidos" nesse escopo.
• Adicione um systemPrompt curinga somente quando você já quiser que esse escopo permita todos os grupos. Para manter apenas um conjunto fixo de IDs de grupos 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 os grupos que chegam ao processamento de grupos; ele não autoriza todos os remetentes desses grupos — isso continua sendo controlado por groupPolicy/groupAllowFrom.
• channels.whatsapp.direct não tem um efeito colateral equivalente para mensagens diretas: direct["*"] apenas fornece uma configuração padrão depois que uma mensagem direta já foi admitida por dmPolicy, juntamente com allowFrom ou as regras do armazenamento de pareamento.

Exemplo:

{  channels: {    whatsapp: {      groups: {        // Use only if all groups should be admitted at the root scope.        // Applies to all accounts that do not define their own groups map.        "*": { systemPrompt: "Default prompt for all groups." },      },      direct: {        // Applies to all accounts that do not define their own direct map.        "*": { systemPrompt: "Default prompt for all direct chats." },      },      accounts: {        work: {          groups: {            // This account defines its own groups, so root groups are fully            // replaced. To keep a wildcard, define "*" explicitly here too.            "120363406415684625@g.us": {              requireMention: false,              systemPrompt: "Focus on project management.",            },            // Use only if all groups should be admitted in this account.            "*": { systemPrompt: "Default prompt for work groups." },          },          direct: {            // This account defines its own direct map, so root direct entries are            // fully replaced. To keep a wildcard, define "*" explicitly here too.            "+15551234567": { systemPrompt: "Prompt for a specific work direct chat." },            "*": { systemPrompt: "Default prompt for work direct chats." },          },        },      },    },  },}

Referências de configuração

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

Conteúdo relacionado

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