How to Connect OpenClaw to WhatsApp: Complete Setup Guide [2026]

WhatsApp is the most popular messaging channel for OpenClaw deployments. Over 90% of our managed clients use it as their primary interface for interacting with their AI assistant. This guide walks you through the complete setup — from installing the WhatsApp gateway to sending your first message.

OpenClaw connects to WhatsApp through the open-source Baileys library, which implements WhatsApp Web's multi-device protocol. This means your OpenClaw instance appears as a linked device on your WhatsApp account, just like WhatsApp Desktop or WhatsApp Web.

What Does the OpenClaw WhatsApp Integration Do?

The WhatsApp integration turns your WhatsApp into a two-way interface for your OpenClaw agent. Once connected, you can send natural language commands to your bot and receive responses, files, and status updates directly in your WhatsApp chat.

Key capabilities include:

• Two-way messaging — send commands and receive responses in real time
• Media support — send and receive images, documents, and voice notes
• Group chat mode — add your bot to group chats with configurable triggers
• Contact management — the bot can identify who is messaging based on phone number
• Scheduled messages — morning briefings, reminders, and automated reports sent on a schedule

What Do You Need Before Starting?

Before connecting OpenClaw to WhatsApp, make sure you have:

• A running OpenClaw instance (see our beginner setup guide)
• Node.js 18 or higher installed on your server
• A dedicated phone number with WhatsApp activated (we strongly recommend not using your personal number)
• An LLM API key (Claude or GPT) configured in OpenClaw
• A SIM card or virtual number service (Twilio, TextNow, or a prepaid SIM)

How Do You Connect OpenClaw to WhatsApp Step by Step?

Step 1 — Install the WhatsApp gateway

Navigate to your OpenClaw directory and install the WhatsApp gateway package:

cd ~/openclaw
npm install @openclaw/gateway-whatsapp

Step 2 — Configure the gateway

Add the WhatsApp gateway configuration to your config.yaml file:

gateways:
  whatsapp:
    enabled: true
    auth_dir: ./auth_info
    allowed_numbers:
      - "1234567890"   # your personal number
    group_enabled: false
    group_prefix: "@bot"
    media_download: true
    max_message_length: 4096

Step 3 — Start and scan the QR code

Start OpenClaw with the WhatsApp gateway enabled:

openclaw start --gateway whatsapp

A QR code will appear in your terminal. Open WhatsApp on your phone, go to Settings → Linked Devices → Link a Device, and scan the QR code. Once linked, you will see a confirmation message in the terminal.

Step 4 — Send a test message

Open WhatsApp and send a message to the number you linked. You should receive a response from your OpenClaw agent within a few seconds. Try something simple like "What can you do?" to confirm the connection is working.

Step 5 — Set up a process manager

To keep your WhatsApp connection alive 24/7, use PM2:

npm install -g pm2
pm2 start openclaw -- start --gateway whatsapp
pm2 save
pm2 startup

What Can You Do With OpenClaw on WhatsApp?

Once your WhatsApp integration is live, here are the most common workflows our clients deploy:

• Morning briefings — automated daily summary of calendar, tasks, and news delivered at 7am
• Calendar management — "Schedule a call with David tomorrow at 2pm" and OpenClaw handles it
• Quick research — "What did Competitor X announce this week?" with summarized results
• Document updates — "Add the Q1 numbers to the board deck" and OpenClaw edits Google Docs
• Task reminders — "Remind me to follow up with the investor next Monday"
• Team coordination — in group chats, team members can ask the bot questions or request updates

How Do You Fix Common WhatsApp Connection Issues?

Here are the most frequent issues and their solutions:

• QR code expires before scanning: The QR code refreshes every 20 seconds. Make sure your phone is ready before starting the gateway. If it times out, restart the process to generate a new code.
• Session disconnects overnight: This usually happens when the server restarts or loses internet temporarily. PM2 handles automatic restarts. If the session is fully invalidated, delete the auth_info folder and re-scan.
• Messages not being received: Check that your number is in the allowed_numbers list. Also verify that WhatsApp Web is not open in a browser simultaneously, as this can cause conflicts.
• Bot responds to every group message: Set group_prefix to a trigger word like "@bot" so OpenClaw only responds when explicitly mentioned.
• Media files not downloading: Ensure media_download: true is set and that your server has sufficient disk space. Large files may timeout on slow connections.

FAQ

Can OpenClaw work in WhatsApp group chats?

Yes. You can configure OpenClaw to respond in group chats by setting group_enabled: true in your config. You can also set a prefix trigger (e.g., @bot) so it only responds when mentioned, avoiding noise in busy groups.

Does the WhatsApp integration require a business account?

No. OpenClaw uses the Baileys library which connects through WhatsApp Web's multi-device protocol. A standard personal WhatsApp account works. However, we recommend using a dedicated phone number to keep your personal messages separate.

Will WhatsApp ban my number for using OpenClaw?

WhatsApp does not officially support third-party clients. The risk is low for personal use with moderate message volume, but sending high volumes of automated messages could trigger a ban. Keep usage conversational and avoid bulk messaging.

How do I reconnect if the WhatsApp session drops?

OpenClaw stores session credentials locally. Most disconnections resolve automatically on restart. If the session is fully invalidated, delete the auth_info folder and re-scan the QR code. Running OpenClaw with a process manager like PM2 helps auto-restart on crashes.

*Last updated: March 2026. Published by the Remote OpenClaw team at remoteopenclaw.com.*