Set Up the Zalo ClawBot Channel with the openclaw-zaloclawbot Plugin

OpenClaw talks to Zalo ClawBot by way of the external @zalo-platforms/openclaw-zaloclawbot plugin, which is listed in the catalog. Sign-in happens with a Zalo Mini App QR code, and the plugin id you set in config is openclaw-zaloclawbot.

Note

All of this plugin's runtime code sits in the external @zalo-platforms/openclaw-zaloclawbot package. Anything described on this page past installation and configuration comes from the plugin maintainers, and OpenClaw core source has not been checked to confirm it.

Compatibility

Prerequisites

• Node.js >= 22
• OpenClaw installed (openclaw CLI available)
• A Zalo account on a mobile device to scan the login QR code

Install with onboard (recommended)

openclaw onboard

Choose Zalo ClawBot in the channel menu. From the official catalog the wizard pulls down the plugin (with integrity verification), prints the login QR into the terminal, and completes the channel setup once you scan that code using the Zalo app.

Manual installation

For a gateway that is already onboarded, add the channel like this:

1. Install the plugin

openclaw plugins install "@zalo-platforms/openclaw-zaloclawbot@0.1.4"

Pin the exact version shown, so that during install OpenClaw can check the package against the catalog's integrity hash.

2. Enable the plugin

openclaw plugins enable openclaw-zaloclawbot

Before you log in, look at the application result. A plugin you deliberately disabled stays disabled after a reinstall.

3. Generate a QR code and log in

openclaw channels login --channel openclaw-zaloclawbot

Using the Zalo mobile app, scan the QR code rendered in the terminal, then accept the Terms of Use within the Zalo Mini App and approve the session.

4. Verify the channel

openclaw channels status --probe

If the Gateway is not running, bring it up. Config edits are picked up via hot reload. Should the live channel still not have the saved login, execute openclaw plugins reload openclaw-zaloclawbot and then recheck its status.

How it works

The standard Zalo channel makes you register your own Zalo Official Account (OA) and set up static developer credentials. Zalo ClawBot works differently: it is an owner-bound personal assistant running on shared official infrastructure.

1. Onboarding: scanning the QR code opens a Zalo Mini App, which provisions a fresh private bot under a shared official OA and ties it straight to your Zalo user ID.
2. Owner-bound privacy: only the owner can exchange messages with the bot. Anything sent by other users is discarded at the platform level.
3. Official API path: rather than browser or web-session automation, the plugin goes through Zalo Bot Platform APIs.

Under the hood

Zalo is reached through a long-polling loop that stays open (getUpdates). For gateway runs on a local desktop or terminal, webhooks stay off unless you turn them on. Processing of messages happens client-side, after which they are mapped onto your local agent runtime.

Bot credentials are kept by the plugin inside the OpenClaw state directory. That directory is sensitive: apply the same access-control and backup policy you use for the rest of OpenClaw state.

Troubleshooting

• QR login timeout: for security, the login token (zbsk) only lasts 5 minutes. Should the QR code expire before you scan it, run the login command again to get a fresh one.
• Gateway fails to load: verify that your OpenClaw host version is 2026.4.10 or newer. The external npm-plugin installation ledger this ID depends on is not supported by older versions.

Related

• Channels Overview - all supported channels
• Zalo - the bundled Zalo Bot Creator / Marketplace channel
• Pairing - DM authentication and pairing flow
• Plugins - installing and managing plugins