OpenClaw WhatsApp Integration: Full Setup Guide for 2026

By the end of this guide you'll have OpenClaw reliably routing messages between WhatsApp and an LLM of your choice — direct messages restricted to numbers you trust, a group chat allowlist that actually works, media support for images and voice notes, and a configuration that survives reboots.

The whole setup takes about 25 minutes on a server that already has OpenClaw installed. If you're starting from scratch, add another 10 minutes to get OpenClaw itself running — our OpenClaw beginner self-hosting guide covers that side.

This guide is based on running OpenClaw's WhatsApp channel continuously on a Hostinger VPS for the last eight weeks as our family assistant. Every step and every config value below matches what's actually in our live config file.

What You'll Need

• A running OpenClaw instance on a Linux VPS or home-lab box with Node 22.14 LTS or Node 24. (Bun is explicitly unsupported for the WhatsApp channel — stick with Node.)
• A WhatsApp account you're willing to link. We strongly recommend a dedicated SIM, not your personal number. See the FAQ for why.
• A phone with the WhatsApp app logged into that account, for the QR scan.
• SSH access to your server.
• An LLM API key already configured in OpenClaw (Anthropic, OpenAI, or any provider OpenClaw supports — it's BYO-key).
• About 25 minutes uninterrupted.

If you don't yet have a VPS, Hostinger's base tier is more than adequate — OpenClaw plus the WhatsApp channel uses well under 500 MB of RAM in normal operation.

Understand How OpenClaw Talks to WhatsApp

Before touching config, understand the architecture so you can reason about failures.

OpenClaw's WhatsApp channel is built on Baileys — an open-source implementation that speaks WhatsApp Web's protocol. Practically, this means OpenClaw behaves like a Linked Device: you pair it by scanning a QR code from your phone's WhatsApp app, exactly as you would to use WhatsApp Web in a browser. Your messages then flow through OpenClaw, which talks to WhatsApp's servers via the Web protocol.

This has three important consequences:

1. No Meta Business API account is needed. You don't need to register as a business, apply for access, or pay Meta.
2. Your phone must be online periodically. WhatsApp Web requires the primary device to sync occasionally; a phone that's dead for a week will break the session.
3. It's governed by WhatsApp's consumer ToS, not the Business API ToS. Heavy commercial or bulk use is outside what Baileys-based integrations are designed for.

For personal or family use, this model works beautifully. For a real business, use a proper WhatsApp Business API provider like Twilio and integrate that via OpenClaw's webhook plugin instead.

Prepare a Dedicated WhatsApp Number (Strongly Recommended)

Don't link the number your life runs on. Use a cheap dedicated SIM, a virtual number from a provider like Google Voice (where available) or MVNO eSIM, or a secondary physical SIM in your phone. Reasons:

• If WhatsApp flags the linked account, you don't lose your main number.
• Test runs of agent behaviour are safer when they can't accidentally message your family.
• If you want to hand the agent off or share it with co-workers, the dedicated account stays clean.

Install WhatsApp fresh on that account, open it on a phone, and make sure it's active (send one message to confirm). That's the number you'll pair with OpenClaw.

Log In Your WhatsApp Account to OpenClaw

SSH into your OpenClaw host and run:

openclaw channels login --channel whatsapp

A QR code renders in your terminal. On your phone: open WhatsApp → Settings → Linked Devices → Link a Device → scan the terminal QR code.

Within a few seconds the terminal confirms the pairing. OpenClaw writes credentials to ~/.openclaw/credentials/whatsapp/default/creds.json. Back up this directory — losing it means re-pairing.

If you want a named account (for multi-account setups later) use the account flag now so credentials land in the right folder:

openclaw channels login --channel whatsapp --account family

Set an Allowlist Before You Send a Single Message

This is the step you do not skip. An unlocked WhatsApp channel will respond to every message from every WhatsApp contact, which is noisy at best and catastrophic at worst (think: a spam contact triggering real LLM costs).

Open ~/.openclaw/openclaw.json and locate (or add) the channels.whatsapp block. The minimum safe config:

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

What each key means:

• dmPolicy: "allowlist" — only the numbers listed in allowFrom can DM the agent. Other options are pairing (QR-based per-user pairing), open (anyone — never do this on a public gateway), and disabled (no DMs).
• allowFrom — E.164-format phone numbers allowed to DM. Include the + and country code.
• groupPolicy: "disabled" — groups are off by default. We'll turn them on deliberately in the next step.

Save the file and restart the OpenClaw daemon (systemctl restart openclaw if you installed as a daemon; otherwise stop and restart the foreground process). Send yourself a WhatsApp message from an allowlisted number — the agent should respond within a couple of seconds.

Turn On Group Chat Support (Carefully)

Groups are the killer feature — an agent that joins your family group chat and answers questions when mentioned is exactly the kind of quiet utility that makes self-hosted agents worth running. They're also the biggest footgun, because groups have more surface area and more ways to go wrong.

OpenClaw layers group access control. A message is only processed if all of these are true:

1. The group is in channels.whatsapp.groups
2. The sender satisfies groupPolicy + groupAllowFrom
3. The agent is mentioned (default), or you've explicitly set activation: "always"

Recommended starter group config:

{
  "channels": {
    "whatsapp": {
      "dmPolicy": "allowlist",
      "allowFrom": ["+15551234567"],
      "groupPolicy": "allowlist",
      "groupAllowFrom": ["+15551234567", "+15557654321", "+15559999999"],
      "groups": ["120363012345678901@g.us"],
      "activation": "mention"
    }
  }
}

To find a group's ID: join the group with your paired number, send a test message, then check OpenClaw's logs — the group JID appears in the message trace. Copy the ...@g.us value into your groups list.

Start with activation: "mention" (the default). This means the agent only responds when directly @-mentioned in the group, which keeps it quiet and polite. You can switch to activation: "always" later if you're confident about the signal-to-noise ratio.

Configure Message Chunking and Media

OpenClaw splits long LLM responses into WhatsApp-friendly chunks and handles media in both directions. Sensible defaults:

{
  "channels": {
    "whatsapp": {
      "textChunkLimit": 4000,
      "chunkMode": "newline",
      "mediaMaxMb": 50,
      "sendReadReceipts": true,
      "replyToMode": "auto",
      "reactionLevel": "minimal"
    }
  }
}

• textChunkLimit: 4000 — the default. Matches WhatsApp's reliable message size.
• chunkMode: "newline" — split on paragraph breaks. Much more readable than splitting mid-sentence.
• mediaMaxMb: 50 — inbound media over this limit is rejected with a friendly message.
• sendReadReceipts: true — the agent marks messages read after processing. Turn off if you prefer the classic "blue ticks off" look.
• replyToMode: "auto" — the agent quotes the user's message in its reply when that adds context.
• reactionLevel: "minimal" — the agent uses emoji reactions sparingly (👀 while thinking, ✅ when done). Other options: off, ack, extensive.

Media support is rich: images, video, audio, voice notes, documents, stickers, locations, contacts. Outbound voice notes play correctly on iOS and Android because OpenClaw automatically rewrites audio/ogg to audio/ogg; codecs=opus — this is a subtle but important detail if you're generating TTS responses.

Run Multiple WhatsApp Accounts From One OpenClaw

Families with multiple phone numbers, or small teams with a shared assistant plus per-user assistants, can run several paired numbers through the same OpenClaw install.

Pair each account with the --account flag:

openclaw channels login --channel whatsapp --account family
openclaw channels login --channel whatsapp --account work

Configure each under accounts.<id> with per-account overrides:

{
  "channels": {
    "whatsapp": {
      "accounts": {
        "family": {
          "dmPolicy": "allowlist",
          "allowFrom": ["+15551234567", "+15557654321"]
        },
        "work": {
          "dmPolicy": "open",
          "groupPolicy": "allowlist",
          "groupAllowFrom": ["+15559999999"]
        }
      }
    }
  }
}

Each account maintains its own session, credentials, and policies. Restart the daemon after any config change.

Troubleshooting Common Failures

"Not linked" on every outbound send. Run openclaw doctor and openclaw logs --follow. If the session was invalidated (WhatsApp does this periodically after long idle periods or explicit revocation), re-pair with openclaw channels login --channel whatsapp --account <name>.

Reconnect loop — pair, disconnect, re-pair, disconnect. Almost always a clock-skew issue on the VPS or a WhatsApp account that's been flagged. Run timedatectl status to confirm the server clock is correct, and check your phone's Linked Devices list to see if something is forcibly unlinking the session.

Group messages ignored. Walk the layers in order: is the group in groups? Is the sender in groupAllowFrom? Is groupPolicy set to allowlist? Is the activation mode mention, and are you actually tagging the agent? OpenClaw logs will tell you which gate rejected the message.

Outbound delivery silently fails. The docs are clear: "Outbound sends fail fast when no active gateway listener exists for the target account." Translation: the daemon needs to be running, the account needs to be paired, and the listener needs to be healthy. openclaw doctor is your first stop.

Voice notes don't play on iOS. That's the audio/ogg / codecs=opus issue, and OpenClaw should handle it automatically. If you're piping raw audio through a plugin that bypasses OpenClaw's media handling, re-route it through the standard media channel and the rewrite will happen.

Status and broadcast messages cause weird behaviour. They shouldn't — OpenClaw explicitly ignores status and broadcast chats. If you see agent responses in broadcast lists, check for a custom plugin that's intercepting messages before the gate.

Does OpenClaw's WhatsApp Integration Work for Business Use Cases?

For internal business use by a small team — where the "business" is mostly routing real humans to an LLM to save time — yes, and it works well. For customer-facing commercial messaging, bulk outbound, or any scenario where a WhatsApp ban would be catastrophic, no — you want to migrate to the official WhatsApp Business API (via Twilio, MessageBird, or similar) and integrate that through an OpenClaw webhook plugin. Baileys is a consumer-grade integration and should be treated as such for risk purposes.

What to Do Next

With WhatsApp wired up, the natural follow-ons are:

• Add Telegram and Signal — the same pairing + allowlist pattern, covered in the main OpenClaw docs. Multi-channel coverage is where the gateway model really pays off.
• Compare your self-hosted setup against alternatives — if you're questioning whether OpenClaw is still the right base, our OpenClaw vs NanoClaw and OpenClaw vs Hermes Agent comparisons cover the tradeoffs.
• Harden the VPS. If you're exposing more channels, review our OpenClaw security-risks piece — most of the failure modes are operator-side, not OpenClaw-side.

A working WhatsApp channel is the single most useful integration in most self-hosted agent deployments, because it's where most of us already spend time. Thirty minutes of careful setup replaces a lot of context-switching, and the payoff is immediate.