WhatsApp

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 do 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 de desenvolvimento + checkout do git: usa por padrão o caminho do Plugin local.
• Stable/Beta: instala primeiro o Plugin oficial @openclaw/whatsapp do ClawHub, com npm como fallback.
• O runtime do WhatsApp é distribuído fora do pacote npm principal do OpenClaw para que as dependências de runtime específicas do WhatsApp permaneçam com o Plugin externo.

A instalação manual continua disponível:

openclaw plugins install clawhub:@openclaw/whatsapp

Use o pacote npm simples (@openclaw/whatsapp) apenas quando precisar do fallback do registro. Fixe uma versão exata apenas quando precisar de 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>

Ligue para o solicitante atual com MeowCaller (experimental)

O Plugin do WhatsApp pode expor whatsapp_call em turnos de agente originados do WhatsApp. A ferramenta usa MeowCaller para fazer uma chamada de voz do WhatsApp para o solicitante autorizado atual e reproduz uma mensagem TTS da OpenClaw depois que ele atende. A ferramenta não aceita um número de destino, portanto um prompt não pode redirecionar a chamada para terceiros. Este recurso experimental fica 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 atuais:

• apenas chamadas de áudio de saída um para um
• sem números de destino arbitrários
• sem autenticação compartilhada com a conexão de chat
• sem chamadas para si mesmo no modo número pessoal/self-chat
• á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
• a OpenClaw interrompe o processo auxiliar após uma janela limitada de 115 a 175 segundos, incluindo as fases de conexão, atendimento, reprodução e desligamento do MeowCaller

Padrões de implantação

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

Modelo de runtime

• O Gateway gerencia o socket do WhatsApp e o loop de reconexão.
• O watchdog de reconexão usa a atividade do transporte do WhatsApp Web, não apenas o volume de mensagens de app de entrada, portanto uma sessão silenciosa de dispositivo vinculado não é reiniciada somente porque ninguém enviou uma mensagem recentemente. Um limite mais longo de silêncio da aplicação ainda força uma reconexão se frames de transporte continuarem chegando, mas nenhuma mensagem de aplicação for tratada durante a janela do watchdog; após uma reconexão transitória para uma sessão ativa recentemente, essa verificação de silêncio da aplicação usa o timeout normal de mensagens na primeira janela de recuperação.
• Os tempos do socket Baileys são explícitos em web.whatsapp.*: keepAliveIntervalMs controla pings de aplicação do WhatsApp Web, connectTimeoutMs controla o timeout do handshake de abertura, e defaultQueryTimeoutMs controla esperas de consulta do Baileys mais os limites locais da OpenClaw para envio/presença de saída e operações de confirmação de leitura de entrada.
• Envios de saída exigem um listener ativo do WhatsApp para a conta de destino.
• Envios de grupo anexam metadados nativos de menção para tokens @+<digits> e @<digits> em texto e legendas de mídia quando o token corresponde aos metadados atuais de participante do WhatsApp, incluindo grupos com suporte a LID.
• Chats de status e broadcast são ignorados (@status, @broadcast).
• O watchdog de reconexão segue a atividade do transporte do WhatsApp Web, não apenas o volume de mensagens de app de entrada: sessões silenciosas de dispositivos vinculados permanecem ativas enquanto frames de transporte continuam, mas uma interrupção do transporte força reconexão bem antes do caminho posterior de desconexão remota.
• Chats diretos usam regras de sessão de DM (session.dmScope; o padrão main colapsa DMs para a sessão principal do agente).
• Sessões de grupo são isoladas (agent:<agentId>:whatsapp:group:<jid>).
• WhatsApp Channels/Newsletters podem ser destinos explícitos de saída com seu JID nativo @newsletter. Envios de newsletter de saída usam metadados de sessão de canal (agent:<agentId>:whatsapp:channel:<jid>) em vez de semântica de sessão de DM.
• O transporte WhatsApp Web respeita variáveis de ambiente de proxy padrão no host do Gateway (HTTPS_PROXY, HTTP_PROXY, NO_PROXY / variantes em minúsculas). Prefira configuração de proxy em nível de host em vez de configurações de proxy específicas do canal do WhatsApp.
• Quando messages.removeAckAfterReply está habilitado, a OpenClaw limpa a reação de confirmação do WhatsApp depois que uma resposta visível é entregue.

Prompts de aprovação

O WhatsApp pode renderizar prompts de aprovação de exec e Plugin com reações 👍 / 👎. A entrega é controlada pela configuração de encaminhamento de aprovação de 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; isso não envia prompts de aprovação a menos que a família de aprovação correspondente esteja habilitada e roteie para o WhatsApp. O modo de sessão entrega aprovações nativas por emoji somente para aprovações que se originam do WhatsApp. O modo de destino usa o pipeline de encaminhamento compartilhado para destinos explícitos do WhatsApp e não cria fanout separado de DM para aprovadores.

Reações de aprovação do WhatsApp exigem aprovadores explícitos do WhatsApp de allowFrom ou "*". defaultTo controla destinos padrão comuns de mensagens; ele não é um aprovador de aprovação. Comandos manuais /approve ainda passam pelo caminho normal de autorização de remetente do WhatsApp antes da resolução da aprovação.

Hooks de Plugin e privacidade

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

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

Você pode limitar a habilitação a uma conta:

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

Habilite isso apenas para plugins nos quais você confia para receber conteúdo e identificadores de mensagens recebidas do WhatsApp.

Controle de acesso e ativação

Vinculações ACP configuradas

O WhatsApp é compatível com vinculações ACP persistentes com entradas bindings[] de 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" },      },    },  ],}

• Chats diretos correspondem a números E.164, como +15555550123.
• Grupos correspondem a JIDs de grupos do WhatsApp, como 120363424282127706@g.us.
• Allowlists de grupos, política de remetente e controle por menção ou ativação são executados antes de o OpenClaw garantir que a sessão ACP configurada exista.
• Uma vinculação ACP configurada correspondente é dona da rota. Grupos de broadcast do WhatsApp não distribuem esse turno para sessões comuns do WhatsApp.

Comportamento de número pessoal e chat consigo mesmo

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

• ignora confirmações de leitura para turnos de chat consigo mesmo
• ignora comportamento de acionamento automático por JID de menção que, caso contrário, mencionaria você mesmo
• se messages.responsePrefix não estiver definido, respostas de chat consigo mesmo usam por padrão [{identity.name}] ou [openclaw]

Normalização de mensagens e contexto

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

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

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

Entrega, divisão em partes e mídia

Citação de respostas

O WhatsApp é compatível com citação nativa de respostas, em que respostas de saída citam visivelmente a mensagem recebida. Controle isso com channels.whatsapp.replyToMode.

O padrão é "off". Substituições por conta usam channels.whatsapp.accounts.<id>.replyToMode.

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

Nível de reação

channels.whatsapp.reactionLevel controla a amplitude com que o agente usa reações de emoji no WhatsApp:

Padrão: "minimal".

Substituições por conta usam channels.whatsapp.accounts.<id>.reactionLevel.

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

Reações de confirmação

O WhatsApp é compatível com reações de confirmação imediatas no recebimento de entrada via channels.whatsapp.ackReaction. 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      },    },  },}

Notas de comportamento:

• enviada imediatamente depois que a entrada é aceita (antes da resposta)
• se ackReaction estiver presente sem emoji, o WhatsApp usa o emoji de identidade do agente roteado, recorrendo a "👀"; omita ackReaction ou defina emoji: "" para não enviar nenhuma reação de confirmação
• falhas são registradas, mas não bloqueiam a entrega normal da resposta
• o modo de grupo mentions reage em turnos acionados por menção; a ativação de grupo always atua como bypass para essa verificação
• o WhatsApp usa channels.whatsapp.ackReaction (messages.ackReaction legado não é usado 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 deixar um emoji de recibo estático. Quando ativado, o OpenClaw usa o mesmo slot de reação da mensagem de entrada para estados do ciclo de vida, como enfileirado, pensando, atividade de ferramenta, Compaction, concluído e erro.

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

Notas de comportamento:

• channels.whatsapp.ackReaction ainda controla se as reações de status são elegíveis para mensagens diretas e grupos.
• A reação de status enfileirado usa o mesmo emoji de confirmação efetivo das reações de confirmação simples.
• O WhatsApp tem um slot de reação de bot por mensagem, portanto as atualizações de ciclo de vida substituem a reação atual no mesmo lugar.
• messages.removeAckAfterReply: true limpa a reação de status final após a retenção configurada de concluído/erro.
• As categorias de emoji de ferramenta 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).
• Portões de ação:
  • channels.whatsapp.actions.reactions
  • channels.whatsapp.actions.polls
• Gravações de configuração iniciadas pelo canal são ativadas por padrão (desative via 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 Telegram para grupos e chats diretos por meio dos mapas groups e direct.

Hierarquia de resolução para mensagens de grupo:

O mapa groups efetivo é determinado primeiro: se a conta define seus próprios groups, ele substitui completamente o mapa groups raiz (sem mesclagem profunda). A consulta do prompt então é executada no mapa único resultante:

1. Prompt de sistema específico do grupo (groups["<groupId>"].systemPrompt): usado quando a entrada específica do grupo existe no mapa e sua chave systemPrompt está definida. Se systemPrompt for uma string vazia (""), o curinga é suprimido e nenhum prompt de sistema é aplicado.
2. Prompt de sistema curinga do grupo (groups["*"].systemPrompt): usado quando a entrada específica do grupo está totalmente ausente do mapa ou quando ela existe, mas não define nenhuma chave systemPrompt.

Hierarquia de resolução para mensagens diretas:

O mapa direct efetivo é determinado primeiro: se a conta define seu próprio direct, ele substitui completamente o mapa direct raiz (sem mesclagem profunda). A consulta do prompt então é executada no mapa único resultante:

1. Prompt de sistema específico do direto (direct["<peerId>"].systemPrompt): usado quando a entrada específica do par existe no mapa e sua chave systemPrompt está definida. Se systemPrompt for uma string vazia (""), o curinga é suprimido e nenhum prompt de sistema é aplicado.
2. Prompt de sistema curinga do direto (direct["*"].systemPrompt): usado quando a entrada específica do par está totalmente ausente do mapa ou quando ela existe, mas não define nenhuma chave systemPrompt.

Diferença em relação ao comportamento de várias contas do Telegram: No Telegram, groups raiz é suprimido intencionalmente para todas as contas em uma configuração de várias contas — até mesmo contas que não definem nenhum groups próprio — para impedir que um bot receba mensagens de grupo para grupos aos quais ele não pertence. O WhatsApp não aplica essa proteção: groups raiz e direct raiz são sempre herdados por contas que não definem substituição no nível da conta, independentemente de quantas contas estejam configuradas. Em uma configuração do WhatsApp com várias contas, se você quiser prompts de grupo ou diretos por conta, defina explicitamente o mapa completo em cada conta em vez de depender de padrões no nível raiz.

Comportamento importante:

• channels.whatsapp.groups é tanto um mapa de configuração por grupo quanto a lista de permissões de grupo no nível do chat. No escopo raiz ou da conta, groups["*"] significa "todos os grupos são admitidos" para esse escopo.
• Só adicione um systemPrompt de grupo curinga quando você já quiser que esse escopo admita todos os grupos. Se você ainda quiser que apenas um conjunto fixo de IDs de grupo seja elegível, não use groups["*"] para o padrão do prompt. Em vez disso, repita o prompt em cada entrada de grupo explicitamente permitida.
• Admissão de grupo e autorização de remetente são verificações separadas. groups["*"] amplia o conjunto de grupos que podem chegar ao tratamento de grupos, mas por si só não autoriza todos os remetentes desses grupos. O acesso de remetente ainda é controlado separadamente por channels.whatsapp.groupPolicy e channels.whatsapp.groupAllowFrom.
• channels.whatsapp.direct não tem o mesmo efeito colateral para DMs. direct["*"] fornece apenas uma configuração padrão de chat direto depois que uma DM já foi admitida por dmPolicy mais allowFrom ou 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." },          },        },      },    },  },}

Indicadores da referência de configuração

Referência principal:

• Referência de configuração - WhatsApp

Campos de alto sinal do WhatsApp:

• acesso: dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups
• entrega: textChunkLimit, chunkMode, mediaMaxMb, sendReadReceipts, ackReaction, reactionLevel
• várias contas: accounts.<id>.enabled, accounts.<id>.authDir, substituições no nível da conta
• operações: configWrites, debounceMs, web.enabled, web.heartbeatSeconds, web.reconnect.*, web.whatsapp.*
• comportamento da sessão: session.dmScope, historyLimit, dmHistoryLimit, dms.<id>.historyLimit
• prompts: groups.<id>.systemPrompt, groups["*"].systemPrompt, direct.<id>.systemPrompt, direct["*"].systemPrompt

Relacionado

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