OpenClaw WhatsApp Setup: The Proven Step-by-Step Integration

Getting OpenClaw connected to WhatsApp takes about 25 minutes when you know the exact sequence. The process involves three moving parts — the WhatsApp bridge, the OpenClaw gateway, and the channel configuration — and the order matters. Do it out of sequence and you'll spend an hour debugging something that wasn't a real problem.

Prerequisites

Before touching any commands, confirm these are in place:

• OpenClaw gateway is running and accessible — verify with curl http://localhost:8080/health returning 200
• At least one agent is configured and running — check with openclaw agents list
• A phone with WhatsApp installed and an active account (personal or Business app)
• Go 1.21+ installed on the server if building the bridge from source (or use a pre-built binary)
• Port 8765 available on the bridge host — this is the default bridge API port

The phone needs to stay connected to the internet during the pairing process and remain online regularly for the session to stay active. A phone on airplane mode or dead battery will terminate the bridge session.

Install the WhatsApp Bridge

The recommended bridge for OpenClaw WhatsApp integration is the go-whatsapp bridge. Pull the latest binary or build from source.

# Download the pre-built binary (Linux amd64)
curl -Lo wa-bridge https://github.com/openclaw-community/wa-bridge/releases/latest/download/wa-bridge-linux-amd64
chmod +x wa-bridge

# Or build from source
git clone https://github.com/openclaw-community/wa-bridge
cd wa-bridge && go build -o wa-bridge ./cmd/bridge

Create a bridge configuration file. The minimal config to get started looks like this:

# wa-bridge.yaml
server:
  port: 8765
  host: "0.0.0.0"
openclaw:
  gateway_url: "http://localhost:8080"
  gateway_token: "${OPENCLAW_GATEWAY_TOKEN}"
session:
  file: "./wa-session.json"
  auto_reconnect: true

QR Code Pairing

Start the bridge and watch the output carefully. The QR code appears in the terminal within 3–5 seconds.

./wa-bridge --config wa-bridge.yaml

A QR code renders in your terminal. You have approximately 60 seconds to scan it. Open WhatsApp on your phone, tap the three dots menu, select Linked Devices, then Add Device. Point your camera at the QR code in the terminal.

Successful pairing logs look like this:

[INFO] WhatsApp session established
[INFO] Connected as: +1 (555) 000-0000
[INFO] Bridge ready to forward messages
[INFO] Listening on :8765

If you don't see "session established" within 10 seconds of scanning, the scan didn't register. Start the bridge again — it will regenerate the QR code. Keep your phone camera steady and ensure the QR is fully visible without glare.

Channel Configuration

With the bridge running and paired, add the WhatsApp channel to OpenClaw. Create a channel YAML in your channels directory.

# channels/whatsapp.yaml
type: whatsapp
name: "WhatsApp Personal"
bridge_url: "http://localhost:8765"
agent_id: "my-agent"
allowed_numbers:
  - "+15550001234"   # optional: restrict to specific numbers
media:
  images: true
  documents: true
  audio: true
  transcribe_audio: true

The agent_id field is the most common misconfiguration point. It must exactly match the agent ID in your agent's YAML file — including case. Run openclaw agents list to confirm the exact agent ID before saving the channel config.

Apply the config and register the channel:

openclaw channels add --file channels/whatsapp.yaml
openclaw channels list  # verify it appears

Test Your First Message

Send a message from your phone to the WhatsApp number linked to the bridge. Watch the gateway logs in real time:

openclaw logs --follow --channel whatsapp

You should see three events in sequence: the incoming message from the bridge, the agent processing the message, and the agent's response being forwarded back. If the agent responds on your phone within 5–10 seconds, the integration is working.

Here's where most people stop. Don't stop here. Send five more test messages covering edge cases — an empty message, a very long message, an emoji-only message, and a voice note. These reveal edge cases before your real users do.

Troubleshooting Common Failures

No message appears in the logs after sending

Check bridge status first: curl http://localhost:8765/status. If the bridge returns "disconnected", the session has expired — restart the bridge and re-scan the QR code. If the bridge is connected but messages don't appear in OpenClaw logs, the bridge URL in your channel YAML is wrong or the gateway token doesn't match.

Agent receives the message but doesn't respond

The agent is running but may have a configuration error. Check agent logs directly: openclaw logs --agent my-agent. A missing LLM API key or misconfigured model is the usual culprit here.

The QR code expires immediately

Your terminal is rendering the QR slowly — this happens on low-bandwidth SSH connections. Use the --qr-png flag to save the QR as a PNG file and scan from your phone using the saved image.

Bridge connects but messages arrive with a 5–10 second delay

This is normal for QR bridge connections. The bridge polls WhatsApp's web interface. If latency is consistently above 15 seconds, check network connectivity between the bridge host and WhatsApp's servers — some VPS providers have egress filtering that slows this traffic.

Frequently Asked Questions

Why does the QR code expire before I can scan it?

QR codes from the WhatsApp bridge expire in about 60 seconds. If your terminal is slow or you're on a remote server, use the --qr-png flag to save the QR as a PNG file. Transfer it to your local machine and scan from the file — it remains valid until the bridge regenerates it.

How do I know if the WhatsApp channel is successfully connected?

Send a test message from your phone to the linked number and watch OpenClaw's gateway logs. You should see an incoming message event within 2–3 seconds. The bridge status endpoint at /status also returns the current connection state.

Can I connect WhatsApp on a VPS without a screen?

Yes. Run the bridge with --qr-png ./qr.png to save the QR as an image. Transfer it to your local machine with SCP and scan it from there. Some bridge builds also serve the QR via a local web interface on port 8766.

The bridge connects but messages don't reach OpenClaw — what's wrong?

Verify the bridge URL and gateway token in your channel YAML match exactly. Check that OpenClaw's gateway is running and reachable from the bridge host. If they're on separate machines, verify firewall rules allow traffic between them on port 8080.

How often do I need to re-scan the QR code?

In normal operation, the session persists indefinitely. Re-scanning is required if the phone goes offline for extended periods, WhatsApp logs out the linked device, or after a major WhatsApp app update. Monitoring the bridge health endpoint catches these drops automatically.

Does setup differ for WhatsApp Business vs personal accounts?

The QR bridge method works identically for both personal and WhatsApp Business app accounts. The WhatsApp Business Cloud API requires a completely separate setup via the Meta developer portal and is documented in the WhatsApp Business API guide.