WhatsApp

​

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.

openclaw plugins install clawhub:@openclaw/whatsapp

​

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>

​

Ligue para o solicitante atual com MeowCaller (experimental)

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

git clone --branch feat/send-only-notify https://github.com/steipete/meowcaller.git
cd meowcaller
git checkout 752050471fc2bf7a8cdfbf7dbd3cd4e865d85d3f
mkdir -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"

• 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

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

​

Hooks de Plugin e privacidade

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

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

​

Controle de acesso e ativação

​

Vinculações ACP configuradas

{
  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

• 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

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

​

Nível de reação

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

​

Reações de confirmação

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

• 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

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

• 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 whatsapp
openclaw channels status

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

openclaw channels status --probe
openclaw doctor
openclaw logs --follow
openclaw gateway status

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

​

Prompts de sistema

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.

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.

• 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.

{
  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 de configuração - 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