How to Connect OpenClaw to Zalo - Bot API Setup Guide

Zalo is one of the places where the OpenClaw docs are appropriately conservative, and that is exactly what you want. The documented channel is the Zalo Bot API surface, marked experimental, with DMs supported and a very clear warning that Marketplace bot behavior has practical limits you should not guess past.

What the official docs support

The docs say DMs are supported, current Marketplace bots do not have usable group support in practice, outbound text is chunked to 2000 characters, and streaming is blocked by default. Media and richer content paths are documented carefully as limited or environment-dependent, which is a strong sign not to promise more than the official page does.

This channel makes sense when the target audience is already on Zalo and simple one-to-one assistant interactions are enough. It is not the right place to design around groups, threads, or complex media workflows unless the official docs for your exact Zalo product surface say otherwise.

What you need first

• A bot token from the Zalo Bot Platform
• A decision on long-polling versus webhook mode
• A DM access policy, pairing, allowlist, open, or disabled
• Realistic expectations about Marketplace bot limitations

Recommended setup flow

The stable path is token first, DMs first, then optional webhook mode only if you actually need it.

1. Create the bot in the Zalo Bot Platform and copy the full bot token. The docs note that the usable runtime token may appear in the welcome message for Marketplace bots, so copy the final value carefully instead of assuming the first screen is enough.
2. Set the token through ZALO_BOT_TOKEN for the default account or under channels.zalo.accounts.default.botToken in config. The docs prefer the accounts form for new configs even though the flat single-account keys still exist.
3. Restart the gateway and keep DMs on pairing first. Unknown senders receive a pairing code, and that is a safer default than open mode while you verify that the bot is behaving the way the Marketplace surface actually allows.
4. Decide whether you need webhook mode. The docs say long-polling is the default and does not need a public URL, while webhook mode requires HTTPS, a webhook secret, and mutually excludes polling. Do not run both at once.
5. Stay inside the documented limits. Outbound text is chunked to 2000 characters, media limits default to 5 MB, and several richer message types are still documented as limited or unreliable for Marketplace bots.

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

Access, safety, and operational notes

The docs are blunt that DM pairing is the default and that allowFrom expects numeric user IDs because there is no reliable username lookup. That is the right mental model here: use stable IDs, keep group assumptions low, and only open the channel wider when you have direct evidence from your own environment.

If you choose webhook mode, remember the built-in safety details. The secret must be 8 to 256 characters, the URL must use HTTPS, duplicate events are ignored for a short replay window, and burst traffic on the webhook path can be rate-limited with HTTP 429 responses. That is all by design.

How to verify it is working

Start with a DM-only test. Verify token resolution with openclaw channels status --probe, confirm pairing behavior from an unknown sender, then send one short text reply before you assume richer content will work. For this integration, conservative testing is the smart move.

Common gotchas

• Current Marketplace bots do not have usable group support in practice
• Webhook mode and long-polling are mutually exclusive
• Streaming is blocked by default because of the 2000 character limit

If you want the operator version with tighter rollout checklists, safer defaults, and more production patterns, The OpenClaw Playbook is the easiest shortcut.