Understanding OpenClaw WhatsApp Integration

OpenClaw is a self-hosted gateway that connects your favorite messaging apps — including WhatsApp — to AI coding agents like Pi. For users who rely heavily on WhatsApp, understanding how OpenClaw integrates with it is key to unlocking powerful automation and personal assistance across devices.

This guide walks through how to set up, configure, and troubleshoot WhatsApp as a channel in OpenClaw.

Why Use OpenClaw with WhatsApp?

OpenClaw lets you message your AI assistant from WhatsApp — the app you already use every day — without sacrificing control, privacy, or flexibility. Instead of relying on hosted services, you run OpenClaw on your own machine, giving you full control over who your assistant talks to and what it does.

Use cases include:

Getting automated responses to common WhatsApp messages
Monitoring group chats for mentions and replying intelligently
Scheduling check-ins or reminders through WhatsApp
Connecting your AI to business workflows via a familiar interface

Quick Setup Workflow

Step 1: Configure WhatsApp Access Policy

Before linking, define who can interact with your agent. The most secure default uses a pairing system with allowlists:

{
  "channels": {
    "whatsapp": {
      "dmPolicy": "pairing",
      "allowFrom": ["+15551234567"],
      "groupPolicy": "allowlist",
      "groupAllowFrom": ["+15551234567"]
    }
  }
}

dmPolicy: "pairing" ensures unknown contacts must approve a connection before they can message your assistant.
allowFrom lists approved phone number(s) for direct messages.
groupPolicy and groupAllowFrom manage access to WhatsApp groups.

Step 2: Link WhatsApp via QR

Run this command to start the pairing process:

openclaw channels login --channel whatsapp

If using multiple accounts, specify one:

openclaw channels login --channel whatsapp --account work

OpenClaw will display a QR code. Scan it using the WhatsApp app on your phone to link.

Step 3: Start the Gateway

Once linked, start the OpenClaw gateway:

openclaw gateway

The gateway maintains the connection and routes messages between WhatsApp and your AI agent.

Step 4: Approve First Pairing (If Needed)

If you're using pairing mode, the first message from an unapproved sender generates a pairing code. Approve it using:

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>

Codes expire after one hour, and only three pending requests are allowed at once.

Note: OpenClaw works best with a dedicated WhatsApp number. This reduces confusion between personal and agent traffic and simplifies routing.

How It Works Under the Hood

OpenClaw uses WhatsApp Web’s protocol (via the Baileys library) to maintain a persistent socket connection to your WhatsApp account. Unlike some wrappers that rely on mobile apps, OpenClaw runs independently and reconnects automatically if the session drops.

Key technical points:

The gateway owns and manages the WhatsApp session (stored at ~/.openclaw/credentials/whatsapp/<accountId>/creds.json).
Messages flow through a secure tunnel: mobile → WhatsApp server → OpenClaw gateway → AI agent → response back through the same path.
Groups are isolated into their own sessions to prevent context bleed.
Direct messages by default collapse into the main agent session unless configured otherwise.

Access Control & Security

DM and Group Policies

You can fine-tune access using policy rules:

pairing: Unknown senders must be approved via code.
allowlist: Only listed numbers can interact.
open: Any number can message (only if allowFrom includes "*").
disabled: No inbound messages allowed.

Multi-account setups support per-account overrides. For example:

{
  "channels": {
    "whatsapp": {
      "accounts": {
        "work": {
          "dmPolicy": "allowlist",
          "allowFrom": ["+15559876543"]
        }
      }
    }
  }
}

Mention Gating in Groups

To avoid spamming large groups, OpenClaw requires mentions by default. A group member must mention the assistant (by name or configured pattern) for a reply to be triggered.

You can control this behavior per group or globally using:

agents.list[].groupChat.mentionPatterns
messages.groupChat.mentionPatterns

Additionally, users can toggle activation modes within a session using:

/activation mention — reply only when mentioned (default)
/activation always — respond to any message in the group

Message Handling and Context

Reply Context

When someone replies to a previous message, OpenClaw automatically includes context:

[Replying to Jorden id:abc123]
Can you send the meeting notes?
[/Replying]

This helps the AI understand the conversation flow.

Media and Attachments

Incoming media (images, videos, documents, etc.) are normalized with placeholders like <media:image> or <media:document>. Location and contact cards are converted into readable text before processing.

On the outbound side, OpenClaw supports sending:

Images and videos
Audio notes (voice messages)
Documents
Stickers (if supported by the platform)

Media is automatically optimized to fit size limits, and failed sends gracefully fall back to text warnings instead of silent failures.

Read Receipts

By default, OpenClaw sends read receipts when it receives a message. You can disable this globally:

{
  "channels": {
    "whatsapp": {
      "sendReadReceipts": false
    }
  }
}

Or selectively per account. Note that self-chats (messages from your own number) skip read receipts automatically.

Advanced Features

Acknowledgment Reactions

You can configure OpenClaw to react to incoming messages with a quick emoji acknowledgment — useful for signaling that your assistant is “on it.”

Example config:

{
  "channels": {
    "whatsapp": {
      "ackReaction": {
        "emoji": "👀",
        "direct": true,
        "group": "mentions"
      }
    }
  }
}

This reacts with 👀 in DMs and only in group messages when the assistant is mentioned.

Text Chunking

Long responses are split into chunks to comply with WhatsApp’s message limits. By default, OpenClaw splits at 4000 characters.

You can customize this:

{
  "channels": {
    "whatsapp": {
      "textChunkLimit": 3000,
      "chunkMode": "newline"
    }
  }
}

length: Splits at character limit
newline: Tries to split at paragraph breaks first, then falls back to length

Troubleshooting Common Issues

"Not Linked" Error

If OpenClaw reports the WhatsApp channel as unlinked:

openclaw channels status
openclaw channels login --channel whatsapp

Re-scan the QR code to re-establish the session.

Reconnect Loops

If the gateway keeps disconnecting and reconnecting:

openclaw doctor
openclaw logs --follow

Check for network issues or outdated sessions. As a last resort, log out and re-link:

openclaw channels logout --channel whatsapp

Group Messages Being Ignored

Check the following in order:

Is the group in your groups allowlist (if defined)?
Does the sender match groupAllowFrom or allowFrom?
Are mentions required? Is the assistant being mentioned?
Is groupPolicy set to allowlist but no senders are approved?

Final Tips

Run OpenClaw on a stable machine or server; interruptions affect availability.
Use a separate number for your assistant when possible.
Combine WhatsApp with cron jobs for scheduled interactions (e.g., daily check-ins).
Keep your OpenClaw instance updated to avoid compatibility issues with WhatsApp’s API.

With proper setup, OpenClaw turns WhatsApp into a powerful interface for your AI assistant — private, reliable, and fully under your control.