How to Connect OpenClaw to Zalo

Prerequisites

• ✓An existing OpenClaw gateway deployment with access to install and configure plugins.
• ✓Access to the Zalo Bot Platform at https://bot.zaloplatforms.com with permission to create a bot.
• ✓A Zalo Bot Creator / Marketplace bot (this guide reflects Marketplace-bot behavior, not Zalo Official Account bots).

Steps

1. 1

   Ensure the Zalo plugin is available in your OpenClaw install

   OpenClaw bundles the Zalo channel plugin in current packaged releases, but older or custom builds may exclude it. Verify that your build includes the plugin, and if not, install it so the gateway can speak to the Zalo Bot API.

   Use the CLI install path for most setups, or the local path variant if you work from a source checkout.

   bashCopy

   openclaw plugins install @openclaw/zalo

2. 2

   Install the Zalo plugin from a local source checkout (optional path)

   If you maintain a custom OpenClaw build or a forked Zalo plugin, install it from your local filesystem instead of the registry. This keeps your gateway aligned with your source tree while still using the standard plugin mechanism.

   Only use this path if your packaged build does not already include Zalo.

   bashCopy

   openclaw plugins install ./path/to/local/zalo-plugin

3. 3

   Create a Zalo bot and obtain the bot token

   You need a bot token from the Zalo Bot Platform so OpenClaw can authenticate to the Zalo API. Create a new bot, configure its basic settings, then copy the full token string.

   For Marketplace bots, Zalo may surface the runtime token in the bot’s welcome message after creation, so make sure you grab that exact `numeric_id:secret` value.

   textCopy

   1.   Go to https://bot.zaloplatforms.com and sign in.
   2.   Create a new bot and configure its settings.
   3.   Copy the full bot token (typically `numeric_id:secret`). For Marketplace bots, the usable runtime token may appear in the bot’s welcome message after creation.

4. 4

   Configure the Zalo bot token in OpenClaw

   Wire the Zalo bot token into your gateway config so the Zalo channel can start. botToken` config.

   The minimal config below enables the channel, sets the token, and keeps DM access on the default pairing policy.

   jsonCopy

   {
     channels: {
       zalo: {
         enabled: true,
         accounts: {
           default: {
             botToken: "12345689:abc-xyz",
             dmPolicy: "pairing",
           },
         },
       },
     },
   }

5. 5

   Set the Zalo bot token via environment variable (default account only)

   If you prefer environment-based secrets, set `ZALO_BOT_TOKEN` instead of hardcoding the token in your config file. This works for the default Zalo account and keeps the token out of version control.

   Make sure your process manager or shell exports this variable before starting the gateway.

   bashCopy

   ZALO_BOT_TOKEN=...

6. 6

   Restart the OpenClaw gateway to bring up the Zalo channel

   After you add the token via env or config, restart the gateway so it can resolve the Zalo credentials and start the channel. Zalo initializes when a valid token is present, so a restart is required for changes to take effect.

   Once it’s up, DM access defaults to pairing, and you will approve the first contact with a pairing code.

   textCopy

   1.   Restart the gateway. Zalo starts when a token is resolved (env or config).
   2.   DM access defaults to pairing. Approve the code when the bot is first contacted.

7. 7

   Approve DM access using the pairing flow

   By default, unknown Zalo senders must be paired before the agent responds, which protects your bot from random traffic. When a user first messages the bot, they receive a pairing code that you approve from the CLI.

   Use the pairing commands below to list pending codes and approve the ones you trust.

   bashCopy

   openclaw pairing list zalo
   openclaw pairing approve zalo <CODE>

8. 8

   Optionally enable webhook mode instead of long-polling

   OpenClaw uses long-polling for Zalo by default, which avoids exposing a public URL. webhookSecret`.

   Remember that webhook and getUpdates polling are mutually exclusive per the Zalo API, and the secret must meet the documented length requirements.

   textCopy

   Webhook mode: set `channels.zalo.webhookUrl` and `channels.zalo.webhookSecret`.
       *   The webhook secret must be 8-256 characters.
       *   Webhook URL must use HTTPS.
       *   Zalo sends events with `X-Bot-Api-Secret-Token` header for verification.
       *   Gateway HTTP handles webhook requests at `channels.zalo.webhookPath` (defaults to the webhook URL path).
       *   Requests must use `Content-Type: application/json` (or `+json` media types).
       *   Duplicate events (`event_name + message_id`) are ignored for a short replay window.
       *   Burst traffic is rate-limited per path/source and may return HTTP 429.

9. 9

   Send a test message to a Zalo chat from the CLI

   Once the channel is live, verify end-to-end delivery by sending a message from the OpenClaw CLI to a known Zalo chat id. This confirms that your token, routing, and delivery mode are all working.

   Use the `--channel zalo` and `--target` flags to direct the message to the right Zalo conversation.

   bashCopy

   openclaw message send --channel zalo --target 123456789 --message "hi"

Configuration

Troubleshooting

openclaw channels status --probe
openclaw logs --follow

Frequently asked questions