Skip to main content

Connect WhatsApp to OpenClaw

Link your phone in 5 minutes so you can message your AI assistant from WhatsApp.

Prerequisites

Before connecting WhatsApp, make sure:

  • OpenClaw is installed and running (see VPS setup guide or Railway guide)
  • You have WhatsApp installed on your phone
  • Your phone has internet connection

Step 1: Make Sure OpenClaw is Running

If You Used VPS Setup

SSH into your VPS:

ssh root@YOUR_IP_ADDRESS

Check if OpenClaw is running:

pm2 status

If it shows openclaw as online, you're good to go.

If not, start it:

pm2 start openclaw

If You Used Railway

Go to your Railway dashboard and check that your OpenClaw deployment shows as Active.

Step 2: Get the WhatsApp QR Code

There are two ways to view the QR code:

Method 1: Terminal/SSH (VPS Users)

When OpenClaw starts, it displays a QR code directly in your terminal. Look for output like:

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚                                 โ”‚
โ”‚   Scan this QR code with        โ”‚
โ”‚   WhatsApp to link              โ”‚
โ”‚                                 โ”‚
โ”‚   โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ   โ”‚
โ”‚   โ–ˆโ–ˆโ–ˆ โ–„โ–„โ–„โ–„โ–„ โ–ˆโ–€โ–„ โ–ˆ โ–„โ–„โ–„โ–„โ–„ โ–ˆโ–ˆโ–ˆ   โ”‚
โ”‚   โ–ˆโ–ˆโ–ˆ โ–ˆ   โ–ˆ โ–ˆโ–ˆโ–€โ–€โ–ˆ โ–ˆ   โ–ˆ โ–ˆโ–ˆโ–ˆ   โ”‚
โ”‚   โ–ˆโ–ˆโ–ˆ โ–ˆโ–„โ–„โ–„โ–ˆ โ–ˆ โ–€ โ–ˆ โ–ˆโ–„โ–„โ–„โ–ˆ โ–ˆโ–ˆโ–ˆ   โ”‚
โ”‚   ...

If you missed it or it expired, restart the WhatsApp pairing:

openclaw gateway restart

Method 2: Web Interface (Railway Users or Advanced)

If you set up the web interface:

  1. Open your browser and go to your OpenClaw URL (Railway provides this)
  2. Navigate to Settings โ†’ Messaging โ†’ WhatsApp
  3. The QR code will be displayed on screen

Step 3: Link Your Phone

Now you'll scan the QR code with your phone:

  1. Open WhatsApp on your phone
  2. Tap the three dots (โ‹ฎ) in the top right (Android) or Settings (iPhone)
  3. Tap Linked Devices
  4. Tap Link a Device
  5. Point your phone camera at the QR code on your computer
  6. Wait a few seconds...

You should see "Device linked successfully" or similar.

In your terminal (or Railway logs), you'll see:

โœ“ WhatsApp connected successfully
โœ“ Ready to receive messages

Step 4: Test the Connection

Now test that everything works:

  1. Open WhatsApp on your phone
  2. Start a chat with yourself (yes, message your own number)
  3. Type: "Hello" and send
  4. OpenClaw should respond within a few seconds

Expected response: OpenClaw will introduce itself and confirm it's working.

Try a few more commands:

  • "Help" - See available commands
  • "What's the weather?" - Test web search
  • "Remind me to test this in 5 minutes" - Test reminders

โœ… All Connected!

Your OpenClaw assistant is now linked to WhatsApp. Message it anytime to get help with tasks.

Troubleshooting

QR Code Won't Scan

  • Try again: QR codes expire after 60 seconds. Restart OpenClaw to get a new one
  • Check internet: Both your phone and server need internet
  • Clear space: Make your terminal fullscreen so the QR code is larger
  • Screenshot it: Take a screenshot and zoom in on your phone

Connected But Not Responding

  • Check logs: pm2 logs openclaw (VPS) or Railway logs tab
  • Verify API key: Make sure your AI provider API key is working
  • Restart: pm2 restart openclaw (VPS) or redeploy on Railway
  • Check credits: Ensure you have API credits remaining (Anthropic, OpenAI, etc.)

Getting "This Device is Banned" Error

WhatsApp sometimes flags new linked devices as suspicious. This is rare but can happen.

Solutions:

  • Wait 24 hours and try again
  • Use a different phone number or WhatsApp account (e.g., business account)
  • Try linking through WhatsApp Web first to "warm up" the account
  • Contact WhatsApp support if the issue persists

Connection Keeps Dropping

  • Server issues: Make sure your VPS/Railway instance isn't restarting frequently
  • WhatsApp limits: WhatsApp may disconnect if it detects unusual activity
  • Check pm2: pm2 save ensures OpenClaw restarts automatically

Advanced: Using Telegram Instead

Prefer Telegram over WhatsApp? The setup is even easier:

  1. Message @BotFather on Telegram
  2. Send /newbot and follow the prompts
  3. Copy your bot token
  4. Add it to OpenClaw config: ~/.openclaw/config.yaml
  5. Restart OpenClaw
  6. Message your bot on Telegram

Telegram is often more reliable than WhatsApp for bot usage.

Frequently Asked Questions

Will this affect my normal WhatsApp usage?

No. OpenClaw appears as a "Linked Device" just like WhatsApp Web. Your normal chats with friends/family are unaffected.

Can I unlink OpenClaw later?

Yes. Go to WhatsApp โ†’ Settings โ†’ Linked Devices โ†’ find OpenClaw โ†’ Log Out.

Does OpenClaw see all my WhatsApp messages?

No. OpenClaw only receives messages you send TO it. It doesn't have access to your conversations with other people.

Can multiple people use the same OpenClaw instance?

Yes, but they'd all need to message the same WhatsApp number. Better to:

  • Each person sets up their own OpenClaw instance, OR
  • Use different messaging platforms (one person WhatsApp, another Telegram, etc.)

What if my phone is offline?

OpenClaw stays connected. You can message it from WhatsApp Web or another linked device even if your phone is off.

Next Steps

Having issues? Ask in the OpenClaw Discord community for help.