Configure WhatsApp for OpenClaw (Baileys / WhatsApp Web)

What this guide helps you finish

By the end of this guide, you should have one WhatsApp login path working, one deliberate inbound access policy in place, and a quick recovery path if the session drops later.

Who this is for (and not for)

This guide is for operators setting up WhatsApp for the first time and trying to keep the blast radius small.

It is not the best page if your WhatsApp connection already exists and you only need a narrow credential or listener fix.

Before you start: collect these four facts

Before you scan a QR code, decide:

1. whether you can use a dedicated number,
2. whether unknown senders should be blocked or paired,
3. whether you need self-chat mode or a real external contact path,
4. where your OpenClaw state directory is backed up.

Those choices shape almost every later recovery decision.

Before you start (important expectations)

OpenClaw connects to WhatsApp using the WhatsApp Web flow (Baileys-style). That means:

• You will log in by scanning a QR code (Linked Devices)
• The connection relies on WhatsApp Web session credentials stored in your OpenClaw state dir
• You should treat the WhatsApp integration as “powerful but sensitive”: keep it private and locked down

Official reference:

• WhatsApp channel docs: https://docs.openclaw.ai/channels/whatsapp

If you want the fuller operating model before you scan a QR code, read /channels/whatsapp alongside this quick setup guide. Use this page for the shortest path to first login; use the channel page for number strategy, session ownership, and long-run trust posture.

If you’re still getting comfortable with openclaw.json (paths, env vars, allowlists, model refs), see:

• /guides/openclaw-configuration

Recommended setup: dedicated number

If you can, use a separate number for the assistant:

• Lower risk (you are not experimenting on your personal account)
• Cleaner routing (no self-chat quirks)
• Easier recovery if you need to rotate credentials

Avoid “free SMS”/VoIP numbers when possible (WhatsApp often blocks them).

Step 1: minimal WhatsApp config (secure defaults)

Open your config file:

• Default path: ~/.openclaw/openclaw.json (or $OPENCLAW_STATE_DIR/openclaw.json)

Add a conservative DM policy and allowlist:

{
  channels: {
    whatsapp: {
      // Options are typically: "pairing" (default), "allowlist", "open", "disabled"
      dmPolicy: "allowlist",
      allowFrom: ["+15551234567"],
    },
  },
}

Notes:

• Use E.164 format (+15551234567)
• Start strict. You can loosen it later once you trust your setup.

Step 2: log in (scan QR)

Run:

openclaw channels login

Then on your phone:

• WhatsApp -> Settings
• Linked Devices -> Link a device
• Scan the QR

When login succeeds, OpenClaw will persist credentials under your state directory. Back up your state directory if you want an easy restore path.

Step 3: choose your inbound DM policy

You have two common secure patterns:

Option A (simplest): allowlist only

• Set dmPolicy: "allowlist"
• Add trusted numbers to allowFrom
• Everyone else is blocked

Option B (friendlier): pairing

Pairing lets unknown senders request access, and you approve them:

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing",
    },
  },
}

Approve requests:

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <code>

Optional: personal number + self-chat mode (fallback)

If you must run on your personal number, enable self-chat mode and keep an allowlist:

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

This is useful for testing without messaging other people.

Verification checklist after login

Before you call the setup done, verify:

• the QR login completed and survived one gateway restart
• one intended sender can reach the agent
• one unintended sender is blocked or forced into the policy you chose
• you know how to re-link the session without improvising

What to tighten first if the setup feels risky

If the setup feels too exposed, tighten in this order:

1. use or move to a dedicated number
2. move from open behavior to allowlist or pairing
3. make sure the state directory is private and backed up
4. keep Control UI and gateway access private while you test

Troubleshooting quick wins

• QR does not appear: make sure the gateway is running, then rerun openclaw channels login.
• “Logged out” or messages stop arriving: rerun openclaw channels login to re-link.
• You changed config but behavior did not change: restart the gateway (openclaw gateway restart).

If the lane links successfully but later throws credential or listener failures, go straight to:

• /troubleshooting/solutions/whatsapp-401-no-cookie-auth-credentials
• /troubleshooting/solutions/whatsapp-login-timeout-408-websocket-error
• /troubleshooting/solutions/whatsapp-no-active-listener

Security checklist (do this)

• Do not run with dmPolicy: "open" unless you really understand the blast radius.
• Keep the gateway Control UI private (token/password protected, not public).
• Keep ~/.openclaw/ private and backed up (it contains WhatsApp creds).