WhatsApp Setup

WhatsApp is the most popular messaging app on the planet. Pairing it with OpenClaw means your AI assistant lives where your conversations already happen. No extra app to open, no new habit to build.

The pairing process works like Bluetooth headphones: scan a code, connect, done. But unlike Bluetooth, WhatsApp sessions are not permanent. They expire, and when they do, you rescan. The whole cycle takes under a minute once you have done it once.

What You Need

• A WhatsApp account on your phone
• Your OpenClaw instance running and accessible
• Access to the OpenClaw gateway (web UI or CLI)
• About 5 minutes for initial setup

How WhatsApp Integration Works

OpenClaw connects to WhatsApp using the same protocol as WhatsApp Web. Your phone stays the primary device. OpenClaw appears as a linked device, similar to opening WhatsApp Web in a browser.

When WhatsApp Web launched in 2015, it was a simple mirror of your phone conversations. The protocol has evolved significantly since then, moving to a multi-device architecture where linked devices maintain their own encryption keys and can operate independently for a while. OpenClaw benefits from this evolution: your agent can keep responding even when your phone briefly loses connectivity.

This architecture matters because it shapes what works well and what does not:

• Works well: Sending and receiving messages, handling media files, maintaining conversation context across sessions
• Limitations: Sessions expire periodically, some WhatsApp features (status updates, channels) are not accessible, message delivery depends on your phone having been online recently

Step 1: Enable WhatsApp in OpenClaw

Open your OpenClaw configuration and add WhatsApp as a channel.

Via the Gateway UI

1. Open the OpenClaw gateway web interface (default: http://localhost:18789)
2. Navigate to Channels
3. Find WhatsApp in the list and click Enable
4. The gateway will generate a QR code

Via Configuration File

Add WhatsApp to your channels configuration in your OpenClaw config:

channels:
  entries:
    - name: whatsapp
      type: whatsapp
      enabled: true

Restart the gateway after making configuration changes: openclaw gateway restart

Step 2: Pair via QR Code

This is the core step. OpenClaw generates a QR code, and you scan it with your phone to link the device.

Scan the Code

1. Open WhatsApp on your phone
2. Go to Settings → Linked Devices → Link a Device
3. Point your phone camera at the QR code shown in the OpenClaw gateway UI
4. Wait for the confirmation message

Verify the Connection

After scanning, the gateway UI should show the WhatsApp channel as "Connected." Send a test message to your own number (or to the agent directly) to confirm messages flow both ways.

If the QR code has been visible for more than a few minutes, it may have expired. Click "Refresh QR" to generate a new one and scan again.

Step 3: Configure Message Handling

Once paired, decide how your agent handles incoming WhatsApp messages.

DM vs Group Messages

• Direct messages: The agent responds to anyone who messages your linked WhatsApp number. Configure allowlists if you want to restrict access.
• Group messages: The agent can be configured to respond only when mentioned, or to respond to all messages in specific groups.

Media and Attachments

OpenClaw can receive and process images, documents, and voice notes sent via WhatsApp. Images trigger the image analysis tool, documents are processed through the PDF pipeline, and voice notes are transcribed when a speech-to-text model is configured.

Step 4: Handle Session Expiry

This is the part that catches people off guard. WhatsApp linked device sessions are not permanent. They expire for several reasons:

• The session timed out due to inactivity
• WhatsApp updated its protocol (happens periodically)
• You manually logged out the device from your phone
• The OpenClaw server was offline for an extended period

When a session expires, the agent stops responding to WhatsApp messages. OpenClaw logs the disconnection and can notify you through another channel (like Telegram or Discord) that re-pairing is needed.

Re-pairing follows the same QR scan process as the initial setup. Go to the gateway UI, generate a new QR code, and scan it. Session management becomes second nature after a few cycles.

The Japanese practice of kintsugi repairs broken pottery with gold, making the break lines part of the object's beauty. WhatsApp session management works the same way: the breaks are inevitable, but the re-pairing process is fast, and each reconnection is seamless. Build re-pairing into your routine, and the expiry stops being a problem.

Step 5: Multi-Device Considerations

WhatsApp allows up to 4 linked devices per account. OpenClaw uses one of those slots. Plan your linked devices accordingly:

• Slot 1: WhatsApp Web (browser)
• Slot 2: WhatsApp Desktop app
• Slot 3: OpenClaw agent
• Slot 4: Reserved / spare

If you already use all 4 slots, you will need to unlink one device before pairing OpenClaw. Go to Settings → Linked Devices on your phone to manage connected devices.

Troubleshooting

QR Code Will Not Scan

• Ensure the QR code is freshly generated (they expire quickly)
• Check that your phone camera lens is clean
• Try generating the QR code in a different browser or clearing your browser cache

Agent Not Responding After Pairing

• Check the gateway logs: openclaw gateway logs
• Verify the channel shows as "Connected" in the gateway UI
• Send a message directly to your own WhatsApp number (not through a group) to test
• Make sure no other channel is intercepting messages from the same contact

Session Drops Frequently

• Ensure your OpenClaw server has stable internet (no frequent reboots or network interruptions)
• Keep your phone connected to the internet (linked devices need the phone to have been online recently)
• Check if WhatsApp pushed a protocol update (check OpenClaw release notes for patches)
• Consider setting up a secondary notification channel so you get alerted when the session drops

Messages Are Delayed

• Check your server's network latency and DNS resolution
• Verify the LLM provider is responding promptly (check provider status pages)
• Large media files take longer to process. This is expected behavior, not a bug

Security Considerations

• Access control: By default, anyone who has your WhatsApp number can message your agent. Use allowlists to restrict access.
• Message privacy: Messages are processed by your LLM provider. Understand your provider's data retention policies.
• Device linking: Only link OpenClaw on infrastructure you control. Avoid shared or public servers.
• Gateway security: Keep your gateway behind a firewall. Never expose port 18789 to the public internet.

For a complete security review, read the security best practices guide.

WhatsApp vs Other Channels

What to Do Next

• Set up a second notification channel (Telegram or Discord) so you get alerted when the WhatsApp session drops
• Configure allowlists if you want to restrict who can message your agent
• Install skills that work well with messaging: calendar, reminders, web search
• Read the session management guide to understand how OpenClaw handles long conversations