Configuration

Mensagens de grupo do WhatsApp

Para o modelo de grupos entre canais (Discord, iMessage, Matrix, Microsoft Teams, QQBot, Signal, Slack, Telegram, WhatsApp, Zalo), consulte Grupos. Esta página aborda o comportamento específico do WhatsApp sobre esse modelo: ativação, listas de permissões de grupos, chaves de sessão por grupo e injeção de contexto de mensagens pendentes.

Objetivo: permitir que o OpenClaw permaneça em grupos do WhatsApp, seja ativado somente quando mencionado e mantenha essa conversa separada da sessão pessoal de mensagem direta.

Comportamento

Modos de ativação: mention (padrão) ou always. mention exige um ping: uma @menção real do WhatsApp (mentionedJids), um padrão de expressão regular configurado, os dígitos E.164 do bot em qualquer parte do texto ou uma resposta citando uma das mensagens do bot (exceto em configurações de conversa consigo mesmo com número compartilhado). always ativa o agente a cada mensagem, mas o prompt de grupo injetado instrui o agente a responder somente quando agregar valor e, caso contrário, retornar exatamente o token de silêncio NO_REPLY (sem diferenciar maiúsculas de minúsculas). Os padrões vêm da configuração (channels.whatsapp.groups requireMention) e podem ser substituídos por grupo por meio de /activation.
Lista de permissões de grupos: quando channels.whatsapp.groups está definido, somente os JIDs de grupo listados são admitidos (inclua "*" para permitir todos); mensagens de grupos não listados são descartadas com uma indicação no log.
Política de grupos: channels.whatsapp.groupPolicy controla se as mensagens de grupo são aceitas (open|disabled|allowlist). allowlist usa channels.whatsapp.groupAllowFrom (alternativa: channels.whatsapp.allowFrom explícito). O padrão é allowlist (bloqueado até que você adicione remetentes).
Sessões por grupo: as chaves de sessão têm a forma agent:<agentId>:whatsapp:group:<jid> (contas que não são a padrão acrescentam :thread:whatsapp-account-<accountId>), portanto, diretivas como /verbose on, /trace on ou /think high (enviadas como mensagens independentes) ficam restritas a esse grupo; o estado das mensagens diretas pessoais não é alterado.
Injeção de contexto: mensagens de grupo somente pendentes (50 por padrão) que não acionaram uma execução recebem o prefixo [Chat messages since your last reply - for context], com a linha de acionamento sob [Current message - respond to this]. A janela de pendências é limpa após a execução; mensagens que já estão na sessão não são reinjetadas.
Atribuição do remetente: cada linha do grupo contém o rótulo do remetente dentro do envelope da mensagem, por exemplo, [WhatsApp <groupJid> <timestamp>] Alice (+447700900123): text, e a identidade do remetente, além do assunto e dos membros do grupo, é incluída no bloco não confiável de metadados da conversa.
Efêmeras/de visualização única: os invólucros são removidos antes da extração de texto/menções, portanto, os pings dentro deles ainda acionam o agente.
Prompt de sistema do grupo: o primeiro turno de uma sessão de grupo (e qualquer turno após /activation alterar o modo) injeta orientações de ativação no prompt de sistema (Activation: trigger-only ... ou Activation: always-on ..., além de "dirija-se ao remetente específico"). As orientações persistentes de entrega em conversas de grupo ("Você está em uma conversa de grupo do WhatsApp...") são sempre incluídas.

Exemplo de configuração (WhatsApp)

Faça com que as menções ao nome de exibição funcionem mesmo quando o WhatsApp remover o @ visual do corpo do texto:

json5

{  channels: {    whatsapp: {      groups: {        "*": { requireMention: true },      },      historyLimit: 50, // janela de contexto pendente do grupo (padrão 50)    },  },  agents: {    list: [      {        id: "main",        groupChat: {          mentionPatterns: ["@?openclaw", "\\+?15555550123"],        },      },    ],  },}

Observações:

As expressões regulares não diferenciam maiúsculas de minúsculas e usam as mesmas proteções de regex segura que as demais áreas de configuração de regex; padrões inválidos e repetições aninhadas inseguras são ignorados.
O WhatsApp ainda envia menções canônicas por meio de mentionedJids quando alguém toca no contato, portanto, o número como alternativa raramente é necessário, mas funciona como uma proteção útil.
A janela de contexto pendente é resolvida como channels.whatsapp.accounts.<id>.historyLimit → channels.whatsapp.historyLimit → messages.groupChat.historyLimit → 50.

Comando de ativação (somente para o proprietário)

Use o comando de chat em grupo:

/activation mention
/activation always

Somente números de proprietários (de channels.whatsapp.allowFrom ou o próprio número E.164 do bot, quando não definido) podem alterar isso; /activation enviado por qualquer outra pessoa é ignorado e armazenado apenas como contexto. Envie /status como uma mensagem independente no grupo para ver o modo de ativação atual.

Como usar

Adicione sua conta do WhatsApp (a que está executando o OpenClaw) ao grupo.
Diga @openclaw ... (ou inclua o número). Somente remetentes na lista de permissões podem acioná-lo, a menos que você defina groupPolicy: "open".
O prompt do agente inclui o contexto pendente do grupo e linhas identificadas por remetente, para que ele possa responder à pessoa certa.
As diretivas de sessão (/verbose on, /trace on, /think high, /new ou /reset, /compact) aplicam-se somente à sessão desse grupo; envie-as como mensagens independentes para que sejam registradas. Sua sessão pessoal por mensagem direta permanece independente.

Teste / verificação

Teste de fumaça manual:
- Envie uma menção a @openclaw no grupo e confirme uma resposta que faça referência ao nome do remetente.
- Envie uma segunda menção e verifique se o bloco de histórico está incluído e, depois, se é limpo no turno seguinte.
Verifique os logs do Gateway (execute com --verbose) em busca de entradas inbound web message que mostrem from: <groupJid> e o corpo identificado por remetente.

Considerações conhecidas

Heartbeats são executados na sessão principal do agente; sessões de grupo nunca recebem execuções de Heartbeat.
A supressão de eco memoriza o prompt combinado (histórico + mensagem atual) por sessão para que as próprias mensagens entregues pelo bot não o acionem novamente; um lote idêntico repetido pode ser ignorado como eco.
As entradas do armazenamento de sessões aparecem como agent:<agentId>:whatsapp:group:<jid> no armazenamento de sessões SQLite por agente; uma entrada ausente significa apenas que o grupo ainda não acionou uma execução.
Os indicadores de digitação seguem session.typingMode / agents.defaults.typingMode. Quando as respostas visíveis são configuradas para o modo somente pela ferramenta de mensagens, a digitação começa imediatamente por padrão para que os membros do grupo possam ver o agente trabalhando, mesmo que nenhuma resposta final automática seja publicada. A configuração explícita do modo de digitação ainda tem precedência.

Relacionado

Was this useful?