WhatsApp

After onboarding succeeds, configure WhatsApp.

1. Choose the Right Setup Mode

For sandbox testing on your own phone number, use the personal-number path:

• dmPolicy: "allowlist"
• allowFrom includes your own phone number
• selfChatMode: true
• groupPolicy: "disabled" during the first test

This is different from Telegram or Discord. For personal-number WhatsApp, pairing is not the best first setup.

2. Add the WhatsApp Config

Use this exact order.

channels.whatsapp.dmPolicy="allowlist" is validated immediately, so if you set it before allowFrom, OpenClaw will reject the change.

openclaw config set channels.whatsapp.allowFrom '["+15551234567"]' --strict-json
openclaw config set channels.whatsapp.selfChatMode true --json
openclaw config set channels.whatsapp.dmPolicy '"allowlist"' --json
openclaw config set channels.whatsapp.groupPolicy '"disabled"' --json

Replace +15551234567 with the same phone number you linked in WhatsApp.

3. Link WhatsApp

Run:

openclaw channels login --channel whatsapp

Then on your iPhone:

1. Open WhatsApp
2. Go to Settings
3. Open Linked Devices
4. Tap Link a Device
5. Scan the QR code in the sandbox terminal

If the terminal prints Linked after restart; web session ready., that is normal.

4. Start the Gateway

In the sandbox container, the simplest path is:

openclaw gateway

Leave that running in one terminal.

If you want the gateway to keep running while you get your shell prompt back, use:

mkdir -p ~/.openclaw/logs
nohup openclaw gateway > ~/.openclaw/logs/gateway-sandbox.log 2>&1 & echo $! > ~/.openclaw/gateway-sandbox.pid
sleep 4

That means:

• the gateway keeps running in the background
• you can keep using the same terminal
• logs go to ~/.openclaw/logs/gateway-sandbox.log

Verify:

openclaw channels status
tail -n 60 ~/.openclaw/logs/gateway-sandbox.log

What you want to see:

• WhatsApp shows linked
• a log line showing the WhatsApp web session is ready

5. Test Self-Chat

In WhatsApp on your phone:

1. Open Message yourself
2. Send hello

Because this is self-chat mode, you do not need a pairing approval step.

If you started the gateway with plain openclaw gateway, leave that terminal open and use a second terminal for logs:

openclaw logs --follow

If you started the gateway with nohup ... &, you can use the same terminal for:

openclaw logs --follow

Troubleshooting

• dmPolicy="allowlist" requires ... allowFrom: Set allowFrom first, then selfChatMode, then dmPolicy.
• channels.whatsapp: Unrecognized key: "streaming": Remove that key. WhatsApp does not support it in OpenClaw.
• QR login succeeded but no replies arrive: Make sure openclaw gateway is still running and check openclaw channels status.
• You previously tested Cue WhatsApp on the same number: Stop or log out the other runtime first so OpenClaw is the only active WhatsApp listener.
• openclaw gateway restart says the service is disabled: That is expected in the sandbox container. Use openclaw gateway in the foreground instead.

Next: continue to /openclaw/setup/auth.