What you need
- OpenClaw, installed on the computer or server that will run your agent. If it isn’t yet, follow OpenClaw’s Getting started first.
- Your phone. The one you already use is enough: the agent’s number lives in WhatsApp Business, next to your personal WhatsApp.
- A Wabi number for the agent. Step 1 gets it.
- Your own WhatsApp number, to write to the agent and to put on its allowlist.
Why a separate number? OpenClaw recommends it. If you link your personal WhatsApp instead, every message you receive becomes input for the agent.
1. Get a number from Wabi
- Open Wabi in your browser or in the app, and sign in.
- Pick a country. Choose the one the people who will message your agent expect to see; a US number works from anywhere, and there you also pick the area code.
- Subscribe. The number then shows in Wabi as Active or Trial.
In the browser, keep the Wabi tab open for the next step: that is where the verification code will show.
2. Register it in WhatsApp Business
- Install WhatsApp Business on your phone, from the App Store or Google Play. Your personal WhatsApp stays as it is.
- Open it and enter the Wabi number, with its country code.
- When WhatsApp asks how to verify the number, choose Call me.
- The code appears on Wabi’s main screen, usually within a minute or two. Type it into WhatsApp Business.
- Give the account a name. This is what people see when the agent writes to them, so name it after the agent.
Use WhatsApp Business, not WhatsApp. Wabi numbers are tested with WhatsApp Business.
Stuck? See the code never arrives and “Please try again in 1 hour” in our FAQ.
3. Link OpenClaw to the number
If your OpenClaw has no WhatsApp channel yet, add it. This also offers to install the WhatsApp plugin:
openclaw channels add --channel whatsapp
Then log in. OpenClaw prints a QR code in the terminal:
openclaw channels login --channel whatsapp
- On the phone, open WhatsApp Business, the agent’s account, not your personal WhatsApp.
- Open Linked devices: in the ⋮ menu on Android, in Settings on an iPhone.
- Tap Link a device and scan the QR code.
Check that the link is up:
openclaw channels status
On a remote server, run the login in a terminal you can scan straight from. A QR code that travels as a screenshot can expire on the way.
OpenClaw keeps the session under ~/.openclaw/credentials/whatsapp/. Whoever holds those files holds the WhatsApp account: don’t share or commit them.
4. Decide who may message it
Before the agent answers anyone, tell it whom to answer. The settings are in ~/.openclaw/openclaw.json. For a number of its own, OpenClaw’s docs suggest an allowlist:
{
channels: {
whatsapp: {
dmPolicy: "allowlist",
allowFrom: ["+14155550123"],
},
},
}
Put your own number in allowFrom, in international format with the +. Add more numbers as more people should reach the agent.
The four policies
allowlist: only the numbers inallowFromare answered.pairing, the default: someone new gets a code, and nothing they write reaches the agent until you approve it. Codes expire after an hour.open: anyone may write. It needs"*"inallowFrom.disabled: no direct messages at all.
With pairing, list the waiting requests and approve one:
openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>
Groups
Groups have a policy of their own, groupPolicy, which starts as allowlist, and in a group the agent answers only when it is mentioned. Leave groups for later: OpenClaw’s WhatsApp page has the settings.
5. Start the gateway and say hello
The gateway is the part of OpenClaw that holds the WhatsApp connection. To try it, run it in the terminal:
openclaw gateway
To keep it running after you close the terminal, and after a restart, install it as a service:
openclaw gateway install
openclaw gateway start
Now take your phone, open your personal WhatsApp and send a message to the agent’s number. The reply is your agent.
If you changed openclaw.json while the gateway was running and nothing changed, restart it with openclaw gateway restart.
6. Keep it running
- Keep the Wabi number. It is the key to the agent’s WhatsApp account: WhatsApp asks for it again when you move to a new phone or reinstall. If the subscription ends, the number may later go to someone else.
- Open WhatsApp Business now and then. WhatsApp logs linked devices out when the account has not been used on the phone for 14 days.
- Keep it to conversations. Let the agent answer people who write to it, and don’t use it for bulk messages, least of all on a new account.
- After an OpenClaw update, run
openclaw gateway restart.
An agent reaches WhatsApp as a third-party client. That generally works, but WhatsApp does not guarantee it. Wabi’s guarantee covers the number’s activation: see what the guarantee covers.
If something goes wrong
Start with these three. They say whether the gateway runs, whether WhatsApp is linked, and why a message was dropped:
openclaw channels status --probe
openclaw doctor
openclaw logs --follow
- The status says WhatsApp is not linked
- Log in again with
openclaw channels login --channel whatsappand scan the new QR code from WhatsApp Business. - Linked, but it keeps disconnecting
- Run
openclaw doctorand read the log. If the loop goes on, copy the folder under~/.openclaw/credentials/whatsapp/somewhere safe, runopenclaw channels logout --channel whatsapp, then log in again. - Connected, but no reply to a message
- The sender is probably not allowed. Run
openclaw pairing list whatsappand approve them, or add their number toallowFrom. - Nothing happens in a group
- Mention the agent in the message, and check
groupPolicy. - The QR login times out
- On a machine behind a proxy, check the gateway’s proxy settings. OpenClaw’s troubleshooting page lists what to look at.
- WhatsApp’s verification code never arrived
- That is the number’s side, not OpenClaw’s: see our FAQ, or write to wabi@applaud-software.com.
OpenClaw is an independent open-source project, and Wabi is not affiliated with it. Its commands and settings change: where this page and OpenClaw’s docs differ, the docs are right.