OpenClaw + WhatsApp

Run OpenClaw in a Hyperbrowser sandbox and connect it to WhatsApp. Your agent receives and responds to WhatsApp messages through the built-in WhatsApp Web / Baileys channel.

How It Works

Create a sandbox from the openclaw base image.
Configure OpenClaw with your model provider and the WhatsApp channel.
Link a WhatsApp account by scanning a QR code.
Start the OpenClaw gateway and message your agent.

Prerequisites

A Hyperbrowser API key
An OpenAI API key (or another supported model provider)
A WhatsApp account to link to the agent
The Hyperbrowser Node SDK or Python SDK

Quick Start

Create a sandbox, configure the WhatsApp channel with an allowlisted phone number, and start the gateway:

import { Hyperbrowser } from "@hyperbrowser/sdk";
import { config } from "dotenv";
import { StringDecoder } from "node:string_decoder";

config();

const client = new Hyperbrowser({
  apiKey: process.env.HYPERBROWSER_API_KEY,
});

// 1. Create a sandbox from the openclaw image
const sandbox = await client.sandboxes.create({
  imageName: "openclaw",
  timeoutMinutes: 60,
});

console.log("Sandbox ID:", sandbox.id);
console.log("Session URL:", sandbox.sessionUrl);

// 2. Set the default model
await sandbox.exec(
  'openclaw config set agents.defaults.model.primary "openai/gpt-5.2"'
);

// 3. Install the WhatsApp plugin
await sandbox.exec("openclaw plugins install @openclaw/whatsapp");

const gatewayToken = process.env.OPENCLAW_APP_TOKEN ?? crypto.randomUUID();
const gatewayPort = Number(process.env.GATEWAY_PORT ?? 18789);

await sandbox.exec("openclaw config set gateway.mode local");

// 4. Configure the WhatsApp channel (dedicated-number allowlist)
const ownerNumber = "+15551234567"; // replace with the phone number allowed to DM the bot

await sandbox.exec(
  [
    "openclaw config set channels.whatsapp.dmPolicy allowlist",
    `openclaw config set channels.whatsapp.allowFrom '["${ownerNumber}"]' --strict-json`,
    "openclaw config set channels.whatsapp.groupPolicy disabled",
  ].join(" && ")
);

// 5. Link WhatsApp in a PTY terminal so the QR renders correctly
console.log("\nScan the QR code below with your WhatsApp app:\n");

const login = await sandbox.terminal.create({
  command: "bash",
  args: ["-lc", "openclaw channels login --channel whatsapp"],
  rows: 40,
  cols: 120,
});

const loginConnection = await login.attach();
const loginDecoder = new StringDecoder("utf8");

for await (const event of loginConnection.events()) {
  if (event.type === "output") {
    process.stdout.write(loginDecoder.write(event.raw));
    continue;
  }

  break;
}

process.stdout.write(loginDecoder.end());
await loginConnection.close();

console.log("\nWhatsApp linked successfully.");

// 6. Start the gateway
const gateway = await sandbox.processes.start(
  `openclaw gateway --bind lan --port ${gatewayPort} --auth token --token "${gatewayToken}"`,
  { env: { OPENAI_API_KEY: process.env.OPENAI_API_KEY! } }
);

// 7. Wait for the gateway to become ready
for (let i = 0; i < 15; i++) {
  const check = await sandbox.exec("openclaw gateway status --require-rpc");
  if (check.exitCode === 0) break;
  await new Promise((r) => setTimeout(r, 2000));
}

console.log("Gateway started. You can now message your agent on WhatsApp.");

import codecs
import os
import time
import uuid

from dotenv import load_dotenv
from hyperbrowser import Hyperbrowser

load_dotenv()

client = Hyperbrowser(api_key=os.environ["HYPERBROWSER_API_KEY"])

# 1. Create a sandbox from the openclaw image
sandbox = client.sandboxes.create(
    {
        "image_name": "openclaw",
        "timeout_minutes": 60,
    }
)

print(f"Sandbox ID: {sandbox.id}")
print(f"Session URL: {sandbox.session_url}")

# 2. Set the default model
sandbox.exec('openclaw config set agents.defaults.model.primary "openai/gpt-5.2"')

# 3. Install the WhatsApp plugin
sandbox.exec("openclaw plugins install @openclaw/whatsapp")

gateway_token = os.environ.get("OPENCLAW_APP_TOKEN", str(uuid.uuid4()))
gateway_port = int(os.environ.get("GATEWAY_PORT", "18789"))

sandbox.exec("openclaw config set gateway.mode local")

# 4. Configure the WhatsApp channel (dedicated-number allowlist)
owner_number = "+15551234567"  # replace with the phone number allowed to DM the bot
allow_json = f'["{owner_number}"]'

sandbox.exec(
    " && ".join(
        [
            "openclaw config set channels.whatsapp.dmPolicy allowlist",
            f"openclaw config set channels.whatsapp.allowFrom '{allow_json}' --strict-json",
            "openclaw config set channels.whatsapp.groupPolicy disabled",
        ]
    )
)

# 5. Link WhatsApp in a PTY terminal so the QR renders correctly
print("\nScan the QR code below with your WhatsApp app:\n")

login = sandbox.terminal.create(
    {
        "command": "bash",
        "args": ["-lc", "openclaw channels login --channel whatsapp"],
        "rows": 40,
        "cols": 120,
    }
)

login_connection = login.attach()
login_decoder = codecs.getincrementaldecoder("utf-8")()

for event in login_connection.events():
    if event.type == "output":
        print(login_decoder.decode(event.raw), end="")
        continue

    break

print(login_decoder.decode(b"", final=True), end="")
login_connection.close()

print("\nWhatsApp linked successfully.")

# 6. Start the gateway
gateway = sandbox.processes.start(
    f'openclaw gateway --bind lan --port {gateway_port} --auth token --token "{gateway_token}"',
    env={"OPENAI_API_KEY": os.environ["OPENAI_API_KEY"]},
)

# 7. Wait for the gateway to become ready
for _ in range(15):
    check = sandbox.exec("openclaw gateway status --require-rpc")
    if check.exit_code == 0:
        break
    time.sleep(2)

print("Gateway started. You can now message your agent on WhatsApp.")

import codecs
import os
import time
import uuid

from dotenv import load_dotenv
from hyperbrowser import Hyperbrowser
from hyperbrowser.models import (
    CreateSandboxParams,
    SandboxTerminalCreateParams,
)

load_dotenv()

client = Hyperbrowser(api_key=os.environ["HYPERBROWSER_API_KEY"])

# 1. Create a sandbox from the openclaw image
sandbox = client.sandboxes.create(
    CreateSandboxParams(
        image_name="openclaw",
        timeout_minutes=60,
    )
)

print(f"Sandbox ID: {sandbox.id}")
print(f"Session URL: {sandbox.session_url}")

# 2. Set the default model
sandbox.exec('openclaw config set agents.defaults.model.primary "openai/gpt-5.2"')

# 3. Install the WhatsApp plugin
sandbox.exec("openclaw plugins install @openclaw/whatsapp")

gateway_token = os.environ.get("OPENCLAW_APP_TOKEN", str(uuid.uuid4()))
gateway_port = int(os.environ.get("GATEWAY_PORT", "18789"))

sandbox.exec("openclaw config set gateway.mode local")

# 4. Configure the WhatsApp channel (dedicated-number allowlist)
owner_number = "+15551234567"  # replace with the phone number allowed to DM the bot
allow_json = f'["{owner_number}"]'

sandbox.exec(
    " && ".join(
        [
            "openclaw config set channels.whatsapp.dmPolicy allowlist",
            f"openclaw config set channels.whatsapp.allowFrom '{allow_json}' --strict-json",
            "openclaw config set channels.whatsapp.groupPolicy disabled",
        ]
    )
)

# 5. Link WhatsApp in a PTY terminal so the QR renders correctly
print("\nScan the QR code below with your WhatsApp app:\n")

login = sandbox.terminal.create(
    SandboxTerminalCreateParams(
        command="bash",
        args=["-lc", "openclaw channels login --channel whatsapp"],
        rows=40,
        cols=120,
    )
)

login_connection = login.attach()
login_decoder = codecs.getincrementaldecoder("utf-8")()

for event in login_connection.events():
    if event.type == "output":
        print(login_decoder.decode(event.raw), end="")
        continue

    break

print(login_decoder.decode(b"", final=True), end="")
login_connection.close()

print("\nWhatsApp linked successfully.")

# 6. Start the gateway
gateway = sandbox.processes.start(
    f'openclaw gateway --bind lan --port {gateway_port} --auth token --token "{gateway_token}"',
    env={"OPENAI_API_KEY": os.environ["OPENAI_API_KEY"]},
)

# 7. Wait for the gateway to become ready
for _ in range(15):
    check = sandbox.exec("openclaw gateway status --require-rpc")
    if check.exit_code == 0:
        break
    time.sleep(2)

print("Gateway started. You can now message your agent on WhatsApp.")

Verify the Setup

After linking, verify everything is running from the sandbox terminal or via the SDK:

const status = await sandbox.exec("openclaw gateway status --require-rpc");
console.log(status.stdout);

const channels = await sandbox.exec("openclaw channels list");
console.log(channels.stdout);

const probe = await sandbox.exec("openclaw channels status --probe");
console.log(probe.stdout);

const deep = await sandbox.exec("openclaw status --deep");
console.log(deep.stdout);

status = sandbox.exec("openclaw gateway status --require-rpc")
print(status.stdout)

channels = sandbox.exec("openclaw channels list")
print(channels.stdout)

probe = sandbox.exec("openclaw channels status --probe")
print(probe.stdout)

deep = sandbox.exec("openclaw status --deep")
print(deep.stdout)

Send a WhatsApp message from the allowed phone number to the linked WhatsApp number. With dmPolicy=allowlist, no pairing approval step is needed.

Personal Number Setup

If you want to use your own WhatsApp number instead of a dedicated one, enable selfChatMode. Replace step 4 in the quick start with:

const myNumber = "+15551234567"; // your personal WhatsApp number

await sandbox.exec(
  [
    "openclaw config set channels.whatsapp.dmPolicy allowlist",
    `openclaw config set channels.whatsapp.allowFrom '["${myNumber}"]' --strict-json`,
    "openclaw config set channels.whatsapp.selfChatMode true --strict-json",
  ].join(" && ")
);

my_number = "+15551234567"  # your personal WhatsApp number
allow_json = f'["{my_number}"]'

sandbox.exec(
    " && ".join([
        "openclaw config set channels.whatsapp.dmPolicy allowlist",
        f"openclaw config set channels.whatsapp.allowFrom '{allow_json}' --strict-json",
        "openclaw config set channels.whatsapp.selfChatMode true --strict-json",
    ])
)

With selfChatMode enabled, send a message in your own WhatsApp chat (“Message yourself”) and OpenClaw responds there.

Adding Group Chats

To let your agent respond in group chats when mentioned, add this configuration after the initial setup:

const ownerNumber = "+15551234567";

await sandbox.exec(
  [
    "openclaw config set channels.whatsapp.groupPolicy allowlist",
    `openclaw config set channels.whatsapp.groupAllowFrom '["${ownerNumber}"]' --strict-json`,
    `openclaw config set channels.whatsapp.groups '{"*":{"requireMention":true}}' --strict-json`,
    "openclaw config validate",
  ].join(" && ")
);

owner_number = "+15551234567"
group_allow_json = f'["{owner_number}"]'

sandbox.exec(
    " && ".join([
        "openclaw config set channels.whatsapp.groupPolicy allowlist",
        f"openclaw config set channels.whatsapp.groupAllowFrom '{group_allow_json}' --strict-json",
        'openclaw config set channels.whatsapp.groups \'{"*":{"requireMention":true}}\' --strict-json',
        "openclaw config validate",
    ])
)

This means:

Only allowlisted senders can control the agent in groups.
The agent only responds when mentioned.

Pairing Mode

If you want new DM senders to require explicit approval instead of an allowlist, switch to pairing mode:

await sandbox.exec(
  [
    "openclaw config set channels.whatsapp.dmPolicy pairing",
    "openclaw config unset channels.whatsapp.allowFrom",
    "openclaw config validate",
  ].join(" && ")
);

// After an unknown sender messages the bot:
const pairings = await sandbox.exec("openclaw pairing list whatsapp");
console.log(pairings.stdout);

// Approve a specific pairing code
await sandbox.exec("openclaw pairing approve whatsapp CODE_HERE");

sandbox.exec(
    " && ".join([
        "openclaw config set channels.whatsapp.dmPolicy pairing",
        "openclaw config unset channels.whatsapp.allowFrom",
        "openclaw config validate",
    ])
)

# After an unknown sender messages the bot:
pairings = sandbox.exec("openclaw pairing list whatsapp")
print(pairings.stdout)

# Approve a specific pairing code
sandbox.exec("openclaw pairing approve whatsapp CODE_HERE")

If you keep allowFrom populated alongside dmPolicy=pairing, allowlisted numbers bypass the pairing step.

Troubleshooting

WhatsApp link lost after restart — The WhatsApp session lives in ~/.openclaw. Use a volume to persist it across sandbox restarts.
Messages not delivered — Verify the channel is connected with openclaw channels status --probe. Check that allowFrom includes the correct E.164 phone number (for example +15551234567).
QR code expired — Run openclaw channels login --channel whatsapp again to generate a new QR code.
Gateway bind errors — If you only need access from inside the sandbox (not from the host), set gateway.bind to loopback instead of lan.

Next Steps

Sandbox Processes

Run and manage processes inside your sandbox.

Sandbox Snapshots

Save sandbox state and restore it later.

Volumes

Persist WhatsApp sessions and data across restarts.

Base Images

See all available base images.

Get Started

Sandbox

Base Images

Custom Images

Volumes

Local Filesystem

How It Works

Prerequisites

Quick Start

Verify the Setup

Personal Number Setup

Adding Group Chats

Pairing Mode

Troubleshooting

Next Steps

Sandbox Processes

Sandbox Snapshots

Volumes

Base Images

​How It Works

​Prerequisites

​Quick Start

​Verify the Setup

​Personal Number Setup

​Adding Group Chats

​Pairing Mode

​Troubleshooting

​Next Steps

Sandbox Processes

Sandbox Snapshots

Volumes

Base Images

How It Works

Prerequisites

Quick Start

Verify the Setup

Personal Number Setup

Adding Group Chats

Pairing Mode

Troubleshooting

Next Steps