Duplicate messages in OpenClaw: How to stop your WhatsApp agent from spamming

Duplicate messages are one of the most frustrating problems with WhatsApp AI agents. Your client writes "yes" and the agent responds twice. Or worse: it sends the same introduction message to a lead twice. That destroys credibility.

Why it happens

OpenClaw uses Baileys to connect to WhatsApp. Baileys can emit the same message event multiple times due to WebSocket reconnections, packet duplication, or timing issues between the gateway and the model session.

Additionally, if a user sends two quick messages (like "Yes" + "Go ahead!"), the gateway may process them as two independent requests to the model, generating two responses.

The solution: debounce

Debounce is a mechanism that waits X milliseconds after the last message before processing it. If more messages arrive during that window, they are grouped into one.

The minimum configuration we recommend:

{
  "channels": {
    "whatsapp": {
      "debounceMs": 10000
    }
  },
  "messages": {
    "queue": {
      "mode": "collect"
    },
    "inbound": {
      "debounceMs": 5000,
      "byChannel": {
        "whatsapp": 10000
      }
    }
  }
}

What each parameter does

**channels.whatsapp.debounceMs (10000)**: Waits 10 seconds after the last WhatsApp message before processing. If the user sends "Yes" and 5 seconds later "Go ahead!", both are grouped into a single input for the model.

**messages.queue.mode ("collect")**: Groups messages that arrive while the agent is processing a previous response. Without this, if 3 messages arrive while the agent thinks, it generates 3 responses.

**messages.inbound.debounceMs (5000)**: General debounce for all channels. Second layer of protection.

**messages.inbound.byChannel.whatsapp (10000)**: WhatsApp-specific debounce that overrides the general one.

Why 10 seconds and not less?

With 3 seconds (the minimum some suggest), the agent responds quickly but is still vulnerable to messages sent 4-5 seconds apart. With 10 seconds:

• You cover the common scenario of someone writing in two consecutive messages
• The response takes 10 seconds to arrive, which is more natural — nobody responds instantly
• You eliminate 99% of duplicates

Additional instructions in AGENTS.md

Beyond technical configuration, add to AGENTS.md:

"After sending a message, assume it was sent successfully. NEVER resend a message because you are unsure if it arrived. If you need to confirm, wait for the user's response."

This prevents the agent from re-sending messages due to delivery uncertainty.

Stuck message queue

OpenClaw has an automatic retry system for failed messages. If the gateway disconnects, messages are queued and retried on reconnection. This can cause duplicates when the same message is sent both by the retry and by the agent that already manually retried.

**Solution**: Monitor the `~/.openclaw/delivery-queue/` folder and clean stuck messages. In Open2Claw, our management panel automatically detects and cleans queued messages.