Zalo Personal Plugin: QR Login and Messaging via zca-js
This page covers the Zalo personal plugin for OpenClaw, which uses native zca-js to automate a personal Zalo account for QR login and messaging. It is intended for users who need to integrate a personal Zalo account with the Gateway.
Read this when
- You want Zalo Personal (unofficial) support in OpenClaw
- You are configuring or developing the zalouser plugin
OpenClaw supports Zalo personal accounts through a plugin that leverages native zca-js to drive a standard Zalo user account automatically. No separate zca/openzca CLI binary is necessary.
Warning
Using unofficial automation carries the risk of account suspension or a permanent ban. Proceed at your own risk.
Naming
The channel identifier zalouser is used to clarify that this automates a personal Zalo user account (unofficial). The zalo channel id is reserved for the official bundled Zalo Bot and webhook integration, documented at Zalo.
Where it runs
This plugin operates inside the Gateway process. If you run a remote Gateway, install and configure the plugin on that host, then restart the Gateway.
Install
From npm
openclaw plugins install @openclaw/zalouser
Install the bare package to track the latest official release tag; only pin a specific version when you require a reproducible installation. Afterward, restart the Gateway.
From a local folder (dev)
PLUGIN_SRC=./path/to/local/zalouser-plugin
openclaw plugins install "$PLUGIN_SRC"
cd "$PLUGIN_SRC" && pnpm install
Restart the Gateway after installation.
Config
Channel configuration belongs under channels.zalouser (not plugins.entries.*):
{
channels: {
zalouser: {
enabled: true,
dmPolicy: "pairing",
},
},
}
Refer to Zalo personal channel config for details on DM and group access control, setting up multiple accounts, environment variables, and troubleshooting.
CLI
openclaw channels login --channel zalouser
openclaw channels login --channel zalouser --account <name>
openclaw channels logout --channel zalouser
openclaw channels status --probe
openclaw message send --channel zalouser --target <threadId> --message "Hello from OpenClaw"
openclaw directory self --channel zalouser
openclaw directory peers list --channel zalouser --query "name"
openclaw directory groups list --channel zalouser --query "name"
openclaw directory groups members --channel zalouser --group-id <id>
Agent tool
Tool name: zalouser
Actions: send, image, link, friends, groups, me, status
Channel message actions (separate from the agent tool) additionally support react for reacting to messages.