Guia completo para integrar o OpenClaw ao WhatsApp: da configuração ao uso prático

Conversar com uma inteligência artificial (IA) pelo WhatsApp permite chamar o assistente diretamente no aplicativo de mensagens que você mais usa, sem ficar alternando entre apps. A integração com o WhatsApp é um pouco mais complexa do que com o Telegram, mas, depois que você entende o funcionamento, leva apenas de 5 a 10 minutos para configurar.

Guia de baixo custo para criar seu agente: ArkClaw torna os agentes de IA realmente acessíveis

O OpenClaw, que ganhou muita popularidade recentemente, é útil, mas sua configuração pode afastar muita gente. O ArkClaw, da Volcengine, reduz essa barreira ao mínimo. Sem precisar lidar com servidores ou configurar tokens, você cria com um clique um agente de IA disponível 24 horas por dia, capaz de controlar o navegador, executar scripts e gerenciar o calendário.

O principal é o preço baixo: a mensalidade custa apenas 9,9 yuans e, com o meu código de convite ZLKUK54M (cadastre-se aqui), sai por apenas 8,9 yuans. Se você é programador, também pode assinar diretamente o Coding Plan Pro para usar o serviço sem custo adicional.

Por que integrar uma IA ao WhatsApp?

Antes de começar, talvez você se pergunte: por que não usar diretamente o Telegram ou a interface web?

Na verdade, cada plataforma tem suas vantagens. No meu caso, escolhi o WhatsApp principalmente pelos seguintes motivos:

• Hábito de uso: o WhatsApp é o aplicativo de mensagens que mais uso no dia a dia, e meus amigos e familiares já estão nele
• Integração sem interrupções: não é preciso abrir um aplicativo específico de IA; basta fazer a pergunta na própria conversa
• Linked Devices: o recurso multidispositivo do WhatsApp é maduro e oferece uma conexão estável
• Privacidade sob controle: os dados ficam no seu próprio servidor, sem passar por terceiros

O Telegram também tem seus pontos fortes, como uma API mais aberta e um ecossistema de bots mais rico. A melhor escolha depende do seu cenário de uso.

Preparação: confira o ambiente

Antes de iniciar a integração, confirme alguns pré-requisitos.

Requisitos obrigatórios

1. OpenClaw instalado e em execução — se ainda não instalou, consulte primeiro o guia de instalação anterior
2. Uma conta do WhatsApp no celular — deve ser a conta principal, usada para ler o QR code e estabelecer a conexão
3. Gateway em execução — confirme que openclaw gateway foi iniciado
4. Conexão de rede estável — o celular e o computador precisam estar conectados durante a leitura do QR code

Observação técnica

Há um detalhe importante: ao usar o runtime Bun, você pode encontrar alguns problemas de compatibilidade ao conectar o WhatsApp ou o Telegram. A recomendação oficial é executar o Gateway com Node.js, que tende a ser mais estável.

Confira seu ambiente de execução:

# Verificar a versão do Node.js
node --version

# Confirmar que o Gateway está em execução
ps aux | grep openclaw

Três métodos de integração

O OpenClaw oferece três maneiras de conectar o WhatsApp. Vou apresentá-las em ordem de recomendação.

Método 1: assistente onboard (o mais simples)

Este é o método mais fácil e é indicado para quem está configurando tudo pela primeira vez.

Se você ainda não concluiu a configuração inicial, execute diretamente:

openclaw onboard --install-daemon

Durante o assistente, você deverá escolher quais canais de mensagens deseja conectar. Selecione WhatsApp e siga estas etapas:

1. Um QR code será exibido no terminal
2. Abra o WhatsApp no celular e acesse “Configurações” → “Dispositivos conectados”
3. Toque em “Conectar um dispositivo” e leia o QR code
4. Depois da leitura, o terminal informará que a conexão foi concluída

Todo o processo é rápido e leva apenas de 1 a 2 minutos. Na primeira vez, fiquei um pouco tenso, achando que a leitura poderia falhar, mas funcionou logo na primeira tentativa.

Método 2: comando channels login

Se você já concluiu o onboard e só quer adicionar o canal do WhatsApp separadamente, use este comando:

openclaw channels login

Depois de executá-lo, acontece o seguinte:

1. O terminal mostra um QR code (ou ele é exibido na interface web)
2. Você lê o código com o WhatsApp
3. A conexão é estabelecida e o recebimento de mensagens começa

A vantagem deste método é ser rápido e direto, sem exigir que você passe por todo o processo de configuração.

Método 3: configuração pela interface web (o mais flexível)

Se quiser ter um controle mais detalhado da configuração, você pode usar a interface web.

Acesse o painel de controle do OpenClaw (por padrão, http://localhost:18789) e faça o seguinte:

Etapa 1: abra a página de configuração

Vá para Settings → Config e clique no botão RAW, no canto superior direito, para abrir o editor da configuração bruta.

Etapa 2: adicione a configuração do WhatsApp

Na seção channels, adicione a configuração do WhatsApp:

{
  "channels": {
    "whatsapp": {
      "dmPolicy": "allowlist",
      "allowFrom": ["+8613800138000"],
      "groupPolicy": "allowlist",
      "mediaMaxMb": 50,
      "debounceMs": 0
    }
  }
}

Veja o significado de cada opção:

• dmPolicy: política para mensagens diretas; allowlist permite apenas usuários incluídos na lista de permissões
• allowFrom: lista de permissões; informe seu próprio número de telefone no formato internacional, com o código do país
• groupPolicy: política para mensagens em grupo; definir como allowlist também é a opção mais segura
• mediaMaxMb: tamanho máximo permitido para os arquivos de mídia recebidos, em MB
• debounceMs: atraso de debounce das mensagens, em milissegundos; normalmente pode ser definido como 0

Etapa 3: salve e leia o QR code

Clique no botão Update, no canto superior direito, para salvar a configuração. Em seguida, volte à página Channels. Um QR code será exibido; leia-o com o WhatsApp.

Explicação detalhada da configuração

Agora vamos examinar com mais atenção as opções que acabamos de mencionar.

Gerenciamento de permissões: quem pode enviar mensagens para sua IA?

dmPolicy e groupPolicy são duas configurações de segurança muito importantes.

dmPolicy (política de mensagens diretas) oferece três opções:

• allowlist: somente números incluídos na lista de permissões podem enviar mensagens (recomendado)
• denylist: todos podem enviar mensagens, exceto os números da lista de bloqueio
• open: qualquer pessoa pode enviar mensagens (não recomendado, a menos que você saiba exatamente o que está fazendo)

Eu uso allowlist e adiciono apenas o meu número e os de familiares. Afinal, a IA tem permissão para acessar o sistema, e não quero que desconhecidos enviem comandos a ela.

Formato dos números de telefone em allowFrom

Os números devem estar no formato internacional, incluindo o código do país:

"allowFrom": [
  "+8613800138000",    // Número da China
  "+14155552671",      // Número dos Estados Unidos
  "+447700900000"      // Número do Reino Unido
]

Não se esqueça do sinal + e do código do país; sem eles, o número não será reconhecido.

groupPolicy (política de grupos)

Se quiser usar a IA em grupos do WhatsApp, será preciso configurar a política de grupos. Sinceramente, não recomendo liberar o acesso à IA diretamente em grupos, a menos que seja um grupo privado com pessoas em quem você confia plenamente.

Você pode configurar assim:

"groupPolicy": "allowlist",
"allowFrom": ["ID do grupo"]

O ID do grupo pode ser encontrado nos logs. Outra opção é definir temporariamente a política como open, enviar uma mensagem e consultar o ID nos logs.

Roteamento de mensagens: como a IA processa suas mensagens

O OpenClaw encaminha automaticamente as mensagens do WhatsApp para o modelo de IA. O fluxo completo funciona assim:

1. Você envia uma mensagem pelo WhatsApp
2. O OpenClaw Gateway recebe a mensagem
3. O sistema verifica se o remetente está na lista de permissões
4. Se estiver autorizado, a mensagem é encaminhada ao modelo de IA
5. A IA gera uma resposta
6. A resposta é enviada ao WhatsApp

Esse processo é rápido e normalmente leva de 1 a 2 segundos, dependendo da velocidade de resposta do modelo de IA.

Processamento de arquivos de mídia

A configuração mediaMaxMb determina o tamanho máximo dos arquivos que podem ser recebidos. O valor padrão de 50 MB costuma ser suficiente.

Atualmente, o OpenClaw aceita os seguintes tipos de mídia:

• Imagens (JPG, PNG etc.)
• Arquivos de áudio
• Documentos (PDF, TXT etc.)

Se a sua IA estiver configurada com recursos de visão, como o GPT-4V, ela poderá reconhecer o conteúdo das imagens enviadas.

Etapas detalhadas para ler o QR code

Independentemente do método escolhido, no final será necessário ler um QR code. A etapa é simples, mas há alguns detalhes importantes.

No celular

1. Abra o WhatsApp
2. Toque em “Mais opções” (os três pontos) no canto superior direito
3. Selecione “Dispositivos conectados” (ou “Linked Devices”)
4. Toque em “Conectar um dispositivo” (ou “Link a Device”)
5. Talvez seja necessário confirmar sua impressão digital ou digitar a senha
6. Quando a câmera abrir, aponte-a para o QR code exibido no computador

Cuidados no computador

• Validade do QR code: normalmente, o código expira depois de 1 a 2 minutos; se a leitura falhar, atualize-o e gere outro
• Nitidez: verifique se o QR code está nítido e se a fonte do terminal não está pequena demais
• Rede: é necessário ter conexão no momento da leitura; confirme que o celular e o computador estão online

Na primeira vez que tentei, a fonte do terminal estava tão pequena que o QR code ficou praticamente ilegível, e precisei tentar várias vezes. Depois, percebi que bastava aumentar a janela do terminal.

Como saber se a conexão deu certo

Depois de ler o QR code, você verá os seguintes sinais:

• No celular: o OpenClaw aparece na lista de “Dispositivos conectados”
• No computador: o terminal mostra “WhatsApp connected” ou uma mensagem semelhante
• Na interface web: a página Channels exibe o WhatsApp em verde, indicando que está conectado

Teste e validação

Assim que a conexão for concluída, faça um teste para confirmar que tudo está funcionando.

Envie a primeira mensagem

Envie uma mensagem para você mesmo pelo WhatsApp, por exemplo:

Olá, você consegue me ouvir?

Se a configuração estiver correta, a IA responderá em alguns segundos. Na primeira vez em que recebi uma resposta, fiquei sorrindo para a tela do celular — parecia mágico.

Teste diferentes tipos de mensagem

Experimente estas ações:

• Mensagem de texto: faça uma pergunta à IA
• Imagem: envie uma imagem e peça à IA para descrever o conteúdo; isso exige um modelo com visão
• Documento: envie um arquivo PDF ou TXT
• Áudio: se houver suporte, teste a conversão de voz em texto

Consulte os logs

Se algo der errado, os logs podem ajudar a identificar o problema:

# Consultar os logs do OpenClaw
openclaw gateway --port 18789

Os logs mostram as mensagens recebidas, o processo de tratamento, os erros e outras informações.

Solução de problemas comuns

Ao instalar um software, é normal encontrar problemas. Abaixo estão os erros que enfrentei e as respectivas soluções.

Problema 1: nada acontece depois de ler o QR code

Possíveis causas:

• O QR code expirou
• Há um problema na conexão de rede
• A versão do WhatsApp é antiga demais

Soluções:

1. Atualize o QR code e faça a leitura novamente
2. Verifique a conexão de rede do celular e do computador
3. Atualize o WhatsApp para a versão mais recente

Problema 2: a conexão falha com o erro status=515

Esse é um erro bastante comum e recebe atenção específica na documentação oficial.

Mensagem de erro completa:

WhatsApp login failed: status=515 Unknown Stream Errored (restart required)

Soluções:

1. Volte para Settings → Config
2. Clique no botão Update, no canto superior direito, mesmo sem ter alterado a configuração
3. Retorne à página Channels e confira o status da conexão
4. Se ainda não funcionar, reinicie o Gateway

# Reiniciar o Gateway
pkill -f openclaw
openclaw gateway --port 18789

Problema 3: a mensagem é enviada, mas a IA não responde

Possíveis causas:

• O remetente não está na lista de permissões
• Há um problema na configuração do modelo de IA
• A chave de API expirou

Etapas de diagnóstico:

1. Verifique se o número está no formato internacional correto
2. Consulte os logs para confirmar que a mensagem foi recebida
3. Teste se a IA responde normalmente na interface web
4. Confirme se a chave de API ainda é válida

Problema 4: permissão negada

Sintoma: depois de enviar uma mensagem, você recebe “Permission denied” ou não recebe resposta

Solução:

• Confirme que seu número está na lista allowFrom
• Verifique o formato do número, incluindo o código do país
• Para mensagens em grupo, confira a configuração de groupPolicy

Problema 5: não é possível enviar arquivos de mídia

Possíveis causas:

• O arquivo excede o limite de mediaMaxMb
• O formato do arquivo não é aceito
• O upload falhou por causa da rede

Soluções:

• Aumente o valor de mediaMaxMb
• Tente compactar o arquivo
• Verifique a conexão de rede

Problema 6: a conexão cai depois que o Gateway é reiniciado

Sintoma: depois de reiniciar o computador ou o Gateway, o WhatsApp se desconecta

Soluções:

1. Em condições normais, a reconexão deve acontecer automaticamente
2. Se isso não ocorrer, execute openclaw channels login de novo
3. Leia novamente o QR code para restabelecer a conexão
4. Como alternativa, verifique se o daemon foi iniciado corretamente

Dicas avançadas

Depois que as funções básicas estiverem prontas, você pode experimentar configurações mais avançadas.

Gerenciamento de vários dispositivos

O WhatsApp permite conectar vários dispositivos ao mesmo tempo. Se o OpenClaw estiver instalado em mais de um computador, você poderá conectá-los separadamente, e as mensagens serão sincronizadas em todos eles.

Mas atenção: uma mesma conta do WhatsApp só pode se conectar ao OpenClaw uma vez. Para conectar vários computadores, será necessário usar contas diferentes do WhatsApp.

Estratégia de resposta personalizada

Você pode definir debounceMs na configuração para controlar o debounce das mensagens:

"debounceMs": 1000

Assim, se você enviar várias mensagens seguidas, a IA aguardará 1 segundo para processá-las juntas, evitando chamadas frequentes à API.

Filtragem de mensagens

Se quiser ignorar determinados tipos de mensagem, você pode criar regras de filtragem na configuração de Skills. Por exemplo, é possível responder apenas a mensagens que comecem com “IA”.

Otimização de desempenho

Se o volume de mensagens for alto, considere:

• Reduzir o limite de mediaMaxMb para economizar largura de banda
• Ajustar debounceMs para evitar solicitações frequentes
• Usar um modelo de IA mais rápido

Recomendações de segurança

Depois de integrar o WhatsApp, alguns cuidados de segurança são indispensáveis.

1. Controle rigorosamente a lista de permissões

Adicione a allowFrom apenas números em que você confia. Lembre-se de que, se as Skills correspondentes estiverem habilitadas, esses números poderão usar a IA para executar comandos no sistema, o que representa um nível alto de acesso.

2. Confira regularmente os dispositivos conectados

Verifique periodicamente quais dispositivos aparecem em “Dispositivos conectados” no WhatsApp. Se encontrar algum que não reconheça, remova-o imediatamente.

3. Exija confirmação para operações sensíveis

Para ações como excluir arquivos ou alterar configurações, recomenda-se adicionar às Skills um mecanismo de confirmação em duas etapas para evitar operações acidentais.

4. Não faça a conexão em dispositivos públicos

Não leia o QR code do WhatsApp em computadores de lan houses, bibliotecas ou outros locais públicos. O dispositivo pode estar sendo monitorado, o que colocaria sua conta em risco.

5. Atualize o OpenClaw regularmente

Mantenha o OpenClaw na versão mais recente para receber as correções de segurança em tempo hábil:

npm update -g openclaw
# ou
pnpm update -g openclaw

Considerações finais

Pronto: a esta altura, você já deve ter integrado o WhatsApp ao OpenClaw com sucesso. Vamos recapitular todo o processo:

WhatsApp vs. Telegram: qual escolher?

Se ainda estiver em dúvida entre as duas plataformas, considere estas sugestões.

Escolha o WhatsApp se:

• Você usa principalmente o WhatsApp no dia a dia
• Quer compartilhar a IA com amigos e familiares
• Valoriza a estabilidade do Linked Devices

Escolha o Telegram se:

• Quer uma API mais aberta
• Precisa aproveitar o ecossistema de bots
• Precisa de recursos de canais e grupos

Na verdade, você também pode configurar os dois. O OpenClaw aceita vários canais simultaneamente, então é possível integrar tanto o WhatsApp quanto o Telegram e escolher a plataforma mais adequada em cada situação.

Qual é o próximo passo?

Depois de concluir a conexão, você pode:

• Explorar as Skills do OpenClaw e adicionar mais recursos à IA
• Enviar imagens e documentos para testar recursos multimodais
• Estudar uma lógica de resposta personalizada
• Desenvolver seu próprio plugin de Skill, se tiver interesse

Por fim, um lembrete: integrar o WhatsApp é conveniente, mas exige atenção à segurança. Gerencie a lista de permissões com cuidado e não conceda acesso à IA a pessoas em quem você não confia.

Divirta-se! Se tiver alguma dúvida, consulte a documentação ou peça ajuda à comunidade.

---