Zalo ClawBot Channel Setup via openclaw-zaloclawbot Plugin

OpenClaw integrates with Zalo ClawBot via the @zalo-platforms/openclaw-zaloclawbot plugin, which is listed in the catalog. Authentication is handled through a QR code from a Zalo Mini App; the plugin identifier used in configuration is openclaw-zaloclawbot.

Compatibility

Prerequisites

• Node.js 22 or newer
• OpenClaw must be installed, with the openclaw CLI accessible
• A Zalo account on a mobile device capable of scanning the login QR code

Install with onboard (recommended)

openclaw onboard

From the channel selection menu, choose Zalo ClawBot. The wizard pulls the plugin from the official catalog (with integrity verification), displays the login QR code in your terminal, and finalizes the channel after you scan it using the Zalo app.

Manual installation

To attach the channel to a gateway that has already been onboarded:

1. Install the plugin

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

Always use the exact pinned version so that OpenClaw can validate the package against the catalog's integrity hash during installation.

2. Enable the plugin in config

openclaw config set plugins.entries.openclaw-zaloclawbot.enabled true

3. Generate a QR code and log in

openclaw channels login --channel openclaw-zaloclawbot

Use the Zalo mobile app to scan the QR code shown in the terminal, then accept the Terms of Use presented in the Zalo Mini App and authorize the session.

4. Restart the gateway

openclaw gateway restart

How it works

Zalo ClawBot functions as a personal assistant tied to its owner on shared official infrastructure, unlike the standard Zalo channel that requires you to register your own Zalo Official Account (OA) and set up static developer credentials:

1. Onboarding: the QR code points to a Zalo Mini App that links a newly created, private bot under a shared official OA directly to your Zalo user ID.
2. Owner-bound privacy: the bot only responds to its owner. Messages sent by other users are discarded at the platform level.
3. Official API path: the plugin uses Zalo Bot Platform APIs, not browser automation or web-session techniques.

Under the hood

A persistent long-polling loop (getUpdates) is used by the plugin to communicate with Zalo. Webhooks are turned off by default for local desktop or terminal gateway runs. Messages are processed on the client side and mapped to your local agent runtime.

Bot credentials are managed by the plugin within the OpenClaw state directory. This directory should be treated as sensitive and protected under the same access-control and backup policies as the rest of OpenClaw state.

The runtime for this plugin resides entirely in the external @zalo-platforms/openclaw-zaloclawbot package; details about its behavior beyond installation and configuration come from the plugin's maintainers and have not been verified against OpenClaw core source.

Troubleshooting

• QR login timeout: the login token (zbsk) expires after five minutes for security reasons. If the QR code expires before you scan it, run the login command again to generate a new one.
• Gateway fails to load: make sure your OpenClaw host is running version 2026.4.10 or later. Older versions lack support for the external npm-plugin installation ledger that this ID requires.

Related

• Channels Overview - a list of all supported channels
• Zalo - the built-in Zalo Bot Creator / Marketplace channel
• Pairing - DM authentication and the pairing workflow
• Plugins - installing and managing plugins