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 git: usa por padrão o caminho do plugin local.
• Estável/Beta: usa o pacote npm @openclaw/whatsapp na tag de lançamento oficial atual.

A instalação manual continua disponível:

openclaw plugins install @openclaw/whatsapp

Use o pacote sem versão para acompanhar a tag de lançamento oficial atual. Fixe uma versão exata somente quando precisar de uma instalação reproduzível.

No Windows, o plugin do WhatsApp precisa do Git no PATH durante a instalação npm porque uma de suas dependências Baileys/libsignal é obtida de uma URL git. Instale o Git for Windows, depois reinicie o shell e execute novamente a instalação:

winget install --id Git.Git -e

O Portable Git também funciona se seu diretório bin estiver no PATH.

# 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-auth
openclaw channels login --channel whatsapp --account work

openclaw gateway

openclaw pairing list whatsapp
openclaw 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 loop de reconexão.
• O watchdog de reconexão usa a atividade de transporte do WhatsApp Web, não apenas o volume de mensagens de aplicativo recebidas, portanto uma sessão silenciosa de dispositivo vinculado não é reiniciada apenas porque ninguém enviou uma mensagem recentemente. Um limite maior de silêncio de aplicação ainda força uma reconexão se frames de transporte continuarem chegando, mas nenhuma mensagem de aplicação for processada durante a janela do watchdog; após uma reconexão transitória para uma sessão recentemente ativa, essa verificação de silêncio de aplicação usa o timeout normal de mensagens para a 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 timeouts de consultas do Baileys.
• Envios de saída exigem um listener ativo do WhatsApp para a conta de destino.
• Envios em 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 participantes do WhatsApp, incluindo grupos apoiados por LID.
• Chats de status e broadcast são ignorados (@status, @broadcast).
• O watchdog de reconexão acompanha a atividade de transporte do WhatsApp Web, não apenas o volume de mensagens de aplicativo recebidas: sessões silenciosas de dispositivo vinculado permanecem ativas enquanto frames de transporte continuam, mas uma interrupção de 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 consolida DMs na sessão principal do agente).
• Sessões de grupo são isoladas (agent:<agentId>:whatsapp:group:<jid>).
• Canais/Newsletters do WhatsApp 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 da semântica de sessão de DM.
• 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 configuração de proxy em nível de host em vez de configurações de proxy específicas do canal WhatsApp.
• Quando messages.removeAckAfterReply está ativado, a OpenClaw limpa a reação de confirmação do WhatsApp após uma resposta visível ser entregue.

# Hooks de plugin e privacidade

Mensagens recebidas do WhatsApp podem conter conteúdo pessoal de mensagens, números de telefone, identificadores de grupo, 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ê aceite explicitamente:

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

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

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

Ative 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

# Comportamento de número pessoal e conversa consigo mesmo

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

• ignorar recibos de leitura para turnos de conversa consigo mesmo
• ignorar comportamento de acionamento automático por JID de menção que, caso contrário, faria ping em você mesmo
• se messages.responsePrefix não estiver definido, respostas de conversa 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, fragmentação e mídia

# Citação de resposta

O WhatsApp oferece suporte à 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 quão amplamente o agente usa reações com 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 oferece suporte a 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:

• enviadas imediatamente depois que a entrada é aceita (antes da resposta)
• 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 desvio para essa verificação
• WhatsApp usa channels.whatsapp.ackReaction (o legado messages.ackReaction não é usado aqui)

# Múltiplas 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 whatsapp
openclaw channels status

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

openclaw doctor
openclaw logs --follow

# Prompts do sistema

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

Hierarquia de resolução para mensagens de grupo:

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

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

Hierarquia de resolução para mensagens diretas:

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

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

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

Comportamento importante:

• channels.whatsapp.groups é ao mesmo tempo um mapa de configuração por grupo e a allowlist de grupos no nível do chat. No escopo raiz ou no escopo da conta, groups["*"] significa "todos os grupos são admitidos" para esse escopo.
• Adicione um systemPrompt de grupo curinga somente 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["*"] como padrão de prompt. Em vez disso, repita o prompt em cada entrada de grupo explicitamente permitida.
• A admissão de grupos e a autorização de remetentes 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 nesses grupos. O acesso do 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 direct 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.
            "[email protected]": {
              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." },
          },
        },
      },
    },
  },
}

# Ponteiros da referência de configuração

Referência principal:

• Referência de configuração - WhatsApp

Campos do WhatsApp de alto sinal:

• acesso: dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups
• entrega: textChunkLimit, chunkMode, mediaMaxMb, sendReadReceipts, ackReaction, reactionLevel
• multi-account: 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