WhatsApp

​

Instalação

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>

​

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)

{
  "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"

​

Solicitações de aprovação

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

​

Hooks de plugins e privacidade

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

​

Controle de acesso e ativação

​

Vinculações de 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" },
      },
    },
  ],
}

​

Comportamento de número pessoal e conversa consigo mesmo

​

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: "first" } } }

​

Nível de reações

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

​

Reações de confirmação

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

​

Reações de status do ciclo de vida

{
  messages: {
    statusReactions: {
      enabled: true,
      emojis: {
        deploy: "🛫",
        build: "🏗️",
        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 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 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.

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

{
  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

​

Relacionados

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