How do I connect WhatsApp to OpenClaw?

OpenClaw uses WhatsApp Web via Baileys. You link via QR code (Linked Devices), then the gateway maintains the WebSocket connection. No phone required after setup.

Quick setup (4 steps)

Follow these steps to get WhatsApp connected:

1. Use a separate phone number if possible (recommended for clean routing)
2. Configure WhatsApp in ~/.openclaw/openclaw.json
3. Run openclaw channels login and scan the QR code
4. Start the gateway

Step 1: Choose your number setup

Option A: Dedicated number (recommended)

Use a separate phone number for OpenClaw. Best UX, clean routing, no self-chat quirks. Ideal: spare/old Android phone + eSIM, leave on Wi-Fi and power.

Tip: You can use WhatsApp Business with a different number on the same device, keeping your personal WhatsApp separate.

Option B: Personal number (fallback)

Quick fallback: run OpenClaw on your own number. Message yourself (WhatsApp "Message yourself") for testing. Expect to read verification codes on your main phone during setup. Must enable self-chat mode.

Number sourcing tips: Use a local eSIM from your mobile carrier or a prepaid SIM. Avoid TextNow, Google Voice, or free SMS services — WhatsApp blocks these.

Step 2: Configure OpenClaw

For a dedicated number with single-user allowlist:

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

For your personal number with self-chat mode:

{
  "whatsapp": {
    "selfChatMode": true,
    "dmPolicy": "allowlist",
    "allowFrom": ["+15551234567"]
  }
}

Step 3: Login via QR code

Run the login command to link WhatsApp:

openclaw channels login

A QR code will appear. Open WhatsApp → Settings → Linked Devices → Link a Device, then scan the QR code.

Credentials are stored in ~/.openclaw/credentials/whatsapp/<accountId>/creds.json with a backup at creds.json.bak.

Step 4: Start the gateway

Once linked, start the gateway to begin receiving and sending messages via WhatsApp.

openclaw gateway start

Troubleshooting

Not linked / QR login required

Symptom: openclaw channels status shows linked: false or warns "Not linked".

Fix: Run openclaw channels login and scan the QR code.

Linked but disconnected / reconnect loop

Symptom:openclaw channels status shows running, disconnected.

Fix: Run openclaw doctor or restart the gateway. If it persists, relink via channels login and check logs with openclaw logs --follow.

Will OpenClaw message random contacts?

No. Default DM policy is pairing, so unknown senders only get a pairing code and their message is not processed. OpenClaw only replies to chats it receives, or sends you explicitly trigger.

How does pairing work?

Pairing is a DM gate for unknown senders:

• First DM from a new sender returns a short code (message not processed)
• Approve with: openclaw pairing approve whatsapp <code>
• Codes expire after 1 hour