OpenClaw Evolution WhatsApp

Canal OpenClaw para mensagens WhatsApp recebidas por webhooks da Evolution API.

Instalacao

openclaw plugins install [email protected]

Objetivo

Este plugin substitui a tentativa de parear o WhatsApp Web do OpenClaw quando o WhatsApp Business recusa novo linked-device. A Evolution continua proprietaria da sessao WhatsApp, e o OpenClaw recebe apenas os eventos autorizados pelo webhook.

Fluxo

1. Evolution envia messages.upsert para o gateway OpenClaw.
2. O plugin valida o header secreto configurado.
3. O plugin ignora mensagens fromMe, grupos por padrao e remetentes fora da allowlist.
4. A mensagem e despachada pelo pipeline oficial do OpenClaw.
5. A resposta do agente volta para a Evolution por POST /message/sendText/{instanceName}.

Configuracao OpenClaw

Exemplo sanitizado:

{
  "plugins": {
    "allow": ["evolution-whatsapp"],
    "entries": {
      "evolution-whatsapp": {
        "enabled": true
      }
    }
  },
  "channels": {
    "evolution-whatsapp": {
      "enabled": true,
      "apiBaseUrl": "https://evolution.example.com",
      "instanceName": "Auto-n8n",
      "apiKey": { "source": "env", "provider": "default", "id": "EVOLUTION_API_KEY" },
      "webhookSecret": { "source": "env", "provider": "default", "id": "EVOLUTION_WEBHOOK_SECRET" },
      "webhookPath": "/webhook/evolution-whatsapp",
      "webhookSecretHeader": "x-openclaw-evolution-secret",
      "dmPolicy": "allowlist",
      "allowFrom": ["+5500000000000"],
      "ignoreGroups": true,
      "sendBodyMode": "textMessageWithFallback",
      "linkPreview": false
    }
  }
}

Secrets aceitos pelo plugin:

• EVOLUTION_API_KEY
• EVOLUTION_WEBHOOK_SECRET
• SecretRef em channels.evolution-whatsapp.apiKey
• SecretRef em channels.evolution-whatsapp.webhookSecret

Nunca salvar esses valores no Git.

Configuracao Evolution

No webhook da instancia:

• URL: https://<openclaw-host>/webhook/evolution-whatsapp
• Metodo: POST
• Eventos: MESSAGES_UPSERT ou equivalente messages.upsert
• Header customizado: nome igual a webhookSecretHeader, valor igual a EVOLUTION_WEBHOOK_SECRET

Health check

curl https://<openclaw-host>/webhook/evolution-whatsapp/health

Resposta esperada:

{"status":"ok","channel":"evolution-whatsapp"}

Rollback

1. Desativar o webhook Evolution que aponta para /webhook/evolution-whatsapp.
2. Desabilitar channels.evolution-whatsapp.enabled.
3. Remover evolution-whatsapp de plugins.allow se necessario.
4. Reiniciar o gateway OpenClaw.

Nao reativar o endpoint antigo do assistente-pessoal-ai sem aprovacao humana explicita, para evitar mistura de projetos.