OpenClaw on Zalo

Zalo, the Vietnam-focused messaging app, ships as a bundled plugin in current OpenClaw releases, marked experimental, with direct messages and group chats both implemented against Zalo Bot Creator and Marketplace bots. The page is explicit about scope: Official Account bots are a different product surface it does not cover. Here is the setup, how messages flow, the limits, access control for direct messages and groups, the webhook contract, and the troubleshooting list.

Setup

• Create a bot token on the Zalo bot platform; it has a numeric id and a secret, and for Marketplace bots the usable runtime token may appear in the bot’s welcome message.
• Set the token as an environment variable for the default account or in the config under an accounts entry, the flat top-level keys being a legacy single-account shorthand; then run the probe, start the Gateway if it is offline, and approve the pairing code on first contact.
• Older builds or custom installs that exclude Zalo install the package from npm, pinned only for reproducible installs.
• Multiple accounts are more entries under the accounts map, each with its own token and name, and a default-account key picks the default.

Routing back to Zalo is deterministic. The model never chooses channels.

How it works and the limits

Inbound messages are normalised into the shared channel envelope with media placeholders, replies always route back to the same chat, quote-reply is fixed off, and groups require a mention to trigger the bot, which is not configurable per channel. Transport is long-polling by default with no public URL required, or webhook mode with a URL and a secret. The limits table: outbound text is chunked at 2,000 characters, the Zalo API limit; media in and out is capped at five megabytes by default; a webhook request body is capped at one megabyte with a thirty-second read timeout; the webhook rate limit is 120 requests per minute per path and client IP, then HTTP 429; and replay tombstones keep up to 20,000 completed events per account for thirty days, keyed by message id.

Access control

• Direct messages default to pairing, with codes that expire after one hour; the other policies are allowlist, open, which requires the wildcard, and disabled, and the allow list takes numeric Zalo user ids since there is no username lookup.
• Groups are gated by mention plus group policy, open, allowlist or disabled, with a group allow list that falls back to the DM one; an unset group policy resolves to open when the channel is configured and fails closed to allowlist when the channel block is missing entirely.
• A reported real-world caveat: on some Marketplace-bot setups the bot could not be added to a group at all, a platform-side constraint to check in the bot’s platform settings rather than an OpenClaw policy.

OpenClaw pairing explains the approval code the DM default sends, and OpenClaw hooks and webhooks the durable-acceptance webhook contract this channel shares with the others.

The webhook contract and message types

Webhook mode needs an HTTPS URL and a secret of 8 to 256 characters; Zalo sends events with a secret-token header that is compared in constant time, the Gateway serves the configured path, requests must carry a JSON content type, and OpenClaw returns 200 only after it durably stores the raw event, 500 on a storage failure, with the durable acceptance header a reverse proxy can require. Polling and webhook are mutually exclusive per Zalo’s own docs. Text and media are supported; reactions, threads, polls and native commands are not, and the plugin declares block-streaming capability without the outbound tuning knobs some other regional channels have. When the bot does not respond, check the token with the probe, the sender’s approval, and the logs; when the webhook receives nothing, check HTTPS, the secret length, the path’s reachability, that polling is not also running, and back off after a 429 burst. OpenClaw on Telegram is the closest sibling in shape, a bot token and a choice between polling and webhook.

On Diali

Zalo is not among the channels Diali connects today: the ones we run are WhatsApp, Telegram, Discord, Slack, Mattermost, Matrix, SMS and voice, and a self-run instance is where this plugin lives for now. Connect your first channel in five minutes shows our connect flow, Hosted OpenClaw on Diali is the assistant and Diali security describes the boundary.

• Bundled, experimental, DMs and mention-gated groups.
• Long-polling by default; an HTTPS webhook with a durable 200 otherwise.
• Bot Creator and Marketplace bots only, not Official Accounts.