Automate Personal Zalo Accounts with OpenClaw

Ever felt stuck trying to automate a chat platform that doesn’t offer an official API? It is a common frustration when you want to connect your personal accounts to your own tools but find the door closed. If you are looking to bring your Zalo personal account into your automation workflow, this experimental integration for OpenClaw is exactly what you need.

Zalo Personal (unofficial)

This integration is currently experimental. It automates a personal Zalo account using native zca-js right inside OpenClaw.

Warning: This is an unofficial integration. It might lead to account suspension or a ban, so use it at your own risk.

Plugin required

Zalo Personal works as a plugin and does not come bundled with the core installation.

• Install via CLI: openclaw plugins install @openclaw/zalouser
• Or from a source checkout: openclaw plugins install ./path/to/local/zalouser-plugin
• Details: Plugins

You won’t need any external zca or openzca CLI binaries for this to work.

Quick setup (beginner)

1. Install the plugin using the commands mentioned above.
2. Log in by scanning a QR code on your Gateway machine:
   • openclaw channels login --channel zalouser
   • Scan the QR code with your Zalo mobile app.
3. Enable the channel in your configuration:

{
  channels: {
    zalouser: {
      enabled: true,
      dmPolicy: "pairing",
    },
  },
}

4. Restart the Gateway or finish your setup.
5. DM access defaults to pairing. You just need to approve the pairing code when someone first contacts you.

What it is

• This runs entirely in-process using zca-js.
• It uses native event listeners to catch inbound messages.
• It sends replies directly through the JS API for text, media, links, and events.
• It is designed for personal account use cases where the Zalo Bot API is not available.

Naming

The channel ID is zalouser. This makes it explicit that you are automating a personal Zalo user account. We keep the name zalo reserved for a potential official Zalo API integration in the future.

Finding IDs (directory)

You can use the directory CLI to find peers or groups and their specific IDs:

openclaw directory self --channel zalouser
openclaw directory peers list --channel zalouser --query "name"
openclaw directory groups list --channel zalouser --query "work"

Limits

• Outbound text is split into chunks of about 2000 characters because of Zalo client limits.
• Streaming is blocked by default.

Access control (DMs)

The channels.zalouser.dmPolicy setting supports pairing, allowlist, open, or disabled. It defaults to pairing.

The channels.zalouser.allowFrom field accepts user IDs or names. During setup, the plugin resolves names to IDs using an in-process contact lookup.

You can approve access via:

• openclaw pairing list zalouser
• openclaw pairing approve zalouser <code>

Group access (optional)

• By default, channels.zalouser.groupPolicy is set to "open", so groups are allowed. Use channels.defaults.groupPolicy if you want to override this default when it is unset.
• You can restrict access to an allowlist by setting:
  • channels.zalouser.groupPolicy = "allowlist"
  • channels.zalouser.groups (keys should be stable group IDs; names are resolved to IDs on startup)
  • channels.zalouser.groupAllowFrom (this controls which senders in allowed groups can trigger the bot)
• To block all groups, use channels.zalouser.groupPolicy = "disabled".
• The configuration wizard can prompt you for group allowlists.
• On startup, OpenClaw resolves group or user names in allowlists to IDs and logs the mapping.
• Group allowlist matching only uses IDs by default. Unresolved names are ignored for authentication unless you enable channels.zalouser.dangerouslyAllowNameMatching: true.
• channels.zalouser.dangerouslyAllowNameMatching: true is a compatibility mode that enables matching by mutable group names.
• If groupAllowFrom is not set, the system falls back to allowFrom for group sender checks.
• Sender checks apply to normal group messages and control commands like /new or /reset.

Example:

{
  channels: {
    zalouser: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["1471383327500481391"],
      groups: {
        "123456789": { allow: true },
        "Work Chat": { allow: true },
      },
    },
  },
}

Group mention gating

• channels.zalouser.groups.<group>.requireMention controls if group replies need a mention.
• The resolution order is: exact group ID/name, normalized group slug, *, and then the default (true).
• This applies to both allowlisted groups and open group mode.
• Authorized control commands like /new can bypass this mention gating.
• When a group message is skipped because a mention is required, OpenClaw stores it as pending history and includes it with the next processed group message.
• The group history limit defaults to messages.groupChat.historyLimit (fallback 50). You can override this per account with channels.zalouser.historyLimit.

Example:

{
  channels: {
    zalouser: {
      groupPolicy: "allowlist",
      groups: {
        "*": { allow: true, requireMention: true },
        "Work Chat": { allow: true, requireMention: false },
      },
    },
  },
}

Multi-account

Accounts map to zalouser profiles in the OpenClaw state. Example:

{
  channels: {
    zalouser: {
      enabled: true,
      defaultAccount: "default",
      accounts: {
        work: { enabled: true, profile: "work" },
      },
    },
  },
}

Typing, reactions, and delivery acknowledgements

• OpenClaw sends a typing event before dispatching a reply as a best-effort action.
• The message reaction action react is supported for zalouser in channel actions.
  • Use remove: true to remove a specific reaction emoji from a message.
  • Reaction semantics: Reactions
• For inbound messages that include event metadata, OpenClaw sends delivered acknowledgements and seen receipts.

Troubleshooting

Login doesn’t stick:

• openclaw channels status --probe
• Re-login: openclaw channels logout --channel zalouser && openclaw channels login --channel zalouser

Allowlist/group name didn’t resolve:

• Use numeric IDs in allowFrom, groupAllowFrom, or groups. You can also use exact friend or group names.

Upgraded from old CLI-based setup:

• Remove any old external zca process assumptions.
• The channel now runs fully in OpenClaw without any external CLI binaries.

Related

• Channels Overview — all supported channels
• Pairing — DM authentication and pairing flow
• Groups — group chat behavior and mention gating
• Channel Routing — session routing for messages
• Security — access model and hardening

Next steps

• Check out the Pairing guide to manage your DM security.
• Learn more about Group Chat Behavior to fine-tune your bot’s interactions.

Need more help? Ask the AI Setup Assistant.