How to Build a WhatsApp AI Bot in 15 Minutes with OpenClaw

Build a WhatsApp AI Bot in 15 Minutes

Most “build a chatbot” tutorials end with a toy demo that nobody actually uses. This one ends with a real AI assistant living in your WhatsApp — one that can search the web, manage files, run code, and remember context across conversations.

OpenClaw is a self-hosted AI agent gateway. It connects models like Claude, GPT-4, or Gemini to messaging channels — and WhatsApp is one of the most popular. In this tutorial, you’ll go from zero to a working WhatsApp AI bot in about 15 minutes.

No cloud deployment. No Twilio. No business API nonsense. Just your laptop, a phone number, and a few terminal commands.

---

What You’ll Need (Prerequisites)

Before we start, make sure you have:

• Node.js 22 or newer — check with node --version
• A phone number for WhatsApp — a spare/old number is ideal, but your personal number works too
• An AI model API key — Anthropic (Claude) recommended, but OpenAI, Gemini, Moonshot, and others work
• A terminal — macOS Terminal, Linux shell, or WSL2 on Windows

Windows users: Install WSL2 first. Open PowerShell as admin and run wsl --install. Then do everything inside the Ubuntu terminal.

Optional but recommended: A Brave Search API key so your bot can search the web. It’s free for 2,000 queries/month.

---

Step 1: Install the OpenClaw CLI

Open your terminal and run:

curl -fsSL https://openclaw.ai/install.sh | bash

That’s the one-liner installer. It pulls the latest release and sets up the openclaw command globally.

Alternative (if you prefer npm):

npm install -g openclaw@latest

Verify it worked:

openclaw --version

You should see a version number. If you get “command not found,” restart your terminal or check that your npm global bin is on your PATH.

---

Step 2: Run the Onboarding Wizard

This is where the magic happens. The onboarding wizard walks you through everything — model auth, gateway settings, channel setup, and security defaults — in one interactive flow.

openclaw onboard --install-daemon

The --install-daemon flag tells it to also install a background service (launchd on macOS, systemd on Linux) so your bot stays running after you close the terminal.

Here’s what the wizard will ask you:

Model & Auth

You’ll pick your AI provider. The recommended path:

• Anthropic API key — paste your key from console.anthropic.com
• OpenAI — works with Codex subscription (OAuth) or a standard API key
• Other providers — Gemini, Moonshot, OpenCode Zen, Vercel AI Gateway, and more

The wizard stores credentials securely in ~/.openclaw/credentials/ — they’re never sent anywhere except the model provider.

Gateway Settings

Accept the defaults here unless you know what you’re doing:

• Port: 18789 (default)
• Bind: loopback (local only — secure by default)
• Auth: Token (auto-generated, even for local connections)

Channel Selection

When the wizard asks about channels, select WhatsApp. It will prompt you to log in right there (next step).

---

Step 3: Link WhatsApp

When you select WhatsApp during onboarding (or afterwards), the CLI will show a QR code in your terminal:

openclaw channels login

Now grab your phone:

1. Open WhatsApp → Settings → Linked Devices
2. Tap Link a Device
3. Scan the QR code on your terminal screen

That’s it. Your OpenClaw instance is now connected to WhatsApp via the same Linked Devices feature you’d use for WhatsApp Web. No Business API, no Meta developer account, no webhooks.

Which Phone Number Should You Use?

Dedicated number (recommended): Use a spare SIM or eSIM. This gives you a clean separation — your bot has its own WhatsApp identity. A cheap prepaid SIM works great; it only needs to receive one SMS for verification.

Personal number (quick test): You can run the bot on your own number and message yourself using WhatsApp’s “Message yourself” feature. Enable self-chat mode in the config:

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

---

Step 4: Set Up DM Security

By default, OpenClaw uses pairing mode — unknown senders get a short code and their messages aren’t processed until you approve them. This prevents random people from using your bot.

The wizard already set your phone number in the allowlist. If you need to approve additional users later:

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <code>

Or switch to an explicit allowlist:

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

---

Step 5: Send Your First Message

Your gateway should already be running (the daemon started during onboarding). Verify:

openclaw gateway status

If it’s not running:

openclaw gateway start

Now open WhatsApp on your phone and send a message to your bot’s number (or to yourself if using personal number mode). Type something like:

What’s the weather in Auckland today?

Within a few seconds, you’ll see the bot thinking (👀 reaction) and then a response. Congratulations — you have a working WhatsApp AI bot.

Quick Verify Checklist

Run these to confirm everything is healthy:

openclaw status
openclaw health

You can also test from the terminal:

openclaw message send --target "+1YOUR_NUMBER" --message "Hello from the CLI!"

---

Step 6: Customize Your Bot with SOUL.md

Out of the box, your bot uses a generic persona. The real power comes from customizing it. OpenClaw uses a file called SOUL.md in your workspace to define who your bot is.

Open the workspace:

cd ~/.openclaw/workspace

Edit SOUL.md with your favorite editor:

nano SOUL.md

Here’s an example:

# Soul

You are Max, a friendly and knowledgeable AI assistant.

## Personality
- Casual but professional tone
- Use emoji occasionally but don't overdo it
- Keep responses concise — nobody likes walls of text on WhatsApp
- If you don't know something, say so honestly

## Boundaries
- Never share personal information about the user
- Don't engage with harmful or illegal requests
- Keep conversations PG-13 in group chats

## Expertise
- You're great at research, summarization, and quick answers
- You can search the web, analyze images, and work with files
- You speak English and Spanish fluently

Save the file. The changes take effect on the next new conversation session.

Other Workspace Files You Can Customize

• AGENTS.md — operating instructions and memory guidelines
• USER.md — information about you (the owner) so the bot knows your preferences
• TOOLS.md — notes about specific tools and how you want them used

---

Step 7: Add Skills from ClawHub

Skills are modular capabilities you can add to your bot. They’re like plugins — each one teaches the bot how to use a specific tool or API.

Browse available skills:

clawhub search "image"

Install one:

clawhub install nano-banana-pro

That installs the Gemini image generation skill. Now your bot can generate and edit images right in WhatsApp.

Some popular skills to get started:

Skill	What It Does
web-search	Search the web via Brave API
nano-banana-pro	Generate images with Gemini
summarize	Summarize articles and documents

Update all installed skills:

clawhub update --all

Skills live in ~/.openclaw/skills (shared across agents) or ~/.openclaw/workspace/skills (per-agent). Workspace skills take priority on name conflicts.

---

Step 8: Enable Web Search (Recommended)

Give your bot the ability to search the web:

openclaw configure --section web

Paste your Brave Search API key when prompted. Now when someone asks your bot a question it can’t answer from training data, it’ll search the web and give a sourced response.

web_fetch (reading web pages) works without any API key — only web_search needs one.

---

Bonus: Add Auto-Reactions

Want your bot to react with 👀 immediately when it receives a message (before it starts generating a reply)? Add this to your config:

{
  "channels": {
    "whatsapp": {
      "ackReaction": {
        "emoji": "👀",
        "direct": true,
        "group": "mentions"
      }
    }
  }
}

This gives users instant feedback that their message was received — especially useful when the AI takes a few seconds to respond.

---

Troubleshooting

Bot not responding?

openclaw health
openclaw status --all

WhatsApp disconnected?

openclaw channels login

Re-scan the QR code on your phone.

Pairing issues (first DM ignored)?

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <code>

Need detailed logs?

openclaw logs --follow

---

What You’ve Built

In 15 minutes, you now have:

• ✅ A self-hosted AI assistant running on your own machine
• ✅ WhatsApp as the chat interface — accessible from any phone
• ✅ A customizable persona via SOUL.md
• ✅ Extensible skills from ClawHub
• ✅ Web search capabilities
• ✅ Secure DM access control (pairing or allowlist)
• ✅ A background daemon that keeps running 24/7

No monthly SaaS fees. No data leaving your machine (except to your chosen AI provider). Full control.

---

Next Steps

You’ve got the basics running. Here’s where to go from here:

🔒 Security Hardening

Your bot has access to powerful tools. Before exposing it to more users, take the OpenClaw Security Hardening course — it covers sandboxing, tool policies, prompt injection defense, and production-safe configurations.

openclaw security audit --deep

🤖 Multi-Agent Setup

Want multiple bots — one for work, one personal, one for a team? OpenClaw supports multi-agent routing where different WhatsApp senders talk to different agents:

openclaw agents add work --workspace ~/.openclaw/workspace-work

Check out our Multi-Agent Orchestration guide for the full walkthrough.

📱 Add More Channels

WhatsApp is just the beginning. Add Telegram, Discord, Slack, or iMessage:

openclaw configure

🏠 Mobile Nodes

Connect your iPhone or Android as a node — give your bot access to your phone’s camera, location, and screen. See the Nodes documentation to get started.

---

Have questions? Join the OpenClaw community and share what you’ve built.