Zalo personal

Status: experimental. This integration automates a personal Zalo account via native

inside OpenClaw.

Bundled plugin

Zalo Personal ships as a bundled plugin in current OpenClaw releases, so normal packaged builds do not need a separate install.

If you are on an older build or a custom install that excludes Zalo Personal, install a current npm package when one is published:

• Install via CLI:
  text

  Copy

  openclaw plugins install @openclaw/zalouser
• Or from a source checkout:
  text

  Copy

  openclaw plugins install ./path/to/local/zalouser-plugin
• Details: Plugins

If npm reports the OpenClaw-owned package as deprecated, use a current packaged OpenClaw build or the local checkout path until a newer npm package is published.

No external

/ CLI binary is required.

Quick setup (beginner)

1. Ensure the Zalo Personal plugin is available.
   • Current packaged OpenClaw releases already bundle it.
   • Older/custom installs can add it manually with the commands above.
2. Login (QR, on the Gateway machine):
   • text

     Copy

     openclaw channels login --channel zalouser
   • Scan the QR code with the Zalo mobile app.
3. Enable the channel:

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

4. Restart the Gateway (or finish setup).
5. DM access defaults to pairing; approve the pairing code on first contact.

What it is

• Runs entirely in-process via
  text

  Copy

  zca-js
  .
• Uses native event listeners to receive inbound messages.
• Sends replies directly through the JS API (text/media/link).
• Designed for “personal account” use cases where Zalo Bot API is not available.

Naming

Channel id is

to make it explicit this automates a personal Zalo user account (unofficial). We keep reserved for a potential future official Zalo API integration.

Finding IDs (directory)

Use the directory CLI to discover peers/groups and their IDs:

bash
Copy
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 chunked to ~2000 characters (Zalo client limits).
• Streaming is blocked by default.

Access control (DMs)

supports: (default: ).

accepts user IDs or names. During setup, names are resolved to IDs using the plugin's in-process contact lookup.

Approve via:

• text

  Copy

  openclaw pairing list zalouser
• text

  Copy

  openclaw pairing approve zalouser <code>

Group access (optional)

• Default:
  text

  Copy

  channels.zalouser.groupPolicy = "open"
  (groups allowed). Use
  text

  Copy

  channels.defaults.groupPolicy
  to override the default when unset.
• Restrict to an allowlist with:
  • text

    Copy

    channels.zalouser.groupPolicy = "allowlist"
  • text

    Copy

    channels.zalouser.groups
    (keys should be stable group IDs; names are resolved to IDs on startup when possible)
  • text

    Copy

    channels.zalouser.groupAllowFrom
    (controls which senders in allowed groups can trigger the bot)
• Block all groups:
  text

  Copy

  channels.zalouser.groupPolicy = "disabled"
  .
• The configure wizard can prompt for group allowlists.
• On startup, OpenClaw resolves group/user names in allowlists to IDs and logs the mapping.
• Group allowlist matching is ID-only by default. Unresolved names are ignored for auth unless
  text

  Copy

  channels.zalouser.dangerouslyAllowNameMatching: true
  is enabled.
• text

  Copy

  channels.zalouser.dangerouslyAllowNameMatching: true
  is a break-glass compatibility mode that re-enables mutable group-name matching.
• If
  text

  Copy

  groupAllowFrom
  is unset, runtime falls back to
  text

  Copy

  allowFrom
  for group sender checks.
• Sender checks apply to both normal group messages and control commands (for example
  text

  Copy

  /new
  ,
  text

  Copy

  /reset
  ).

Example:

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

Group mention gating

• text

  Copy

  channels.zalouser.groups.<group>.requireMention
  controls whether group replies require a mention.
• Resolution order: exact group id/name -> normalized group slug ->
  text

  Copy

  *
  -> default (
  text

  Copy

  true
  ).
• This applies both to allowlisted groups and open group mode.
• Quoting a bot message counts as an implicit mention for group activation.
• Authorized control commands (for example
  text

  Copy

  /new
  ) can bypass mention gating.
• When a group message is skipped because mention is required, OpenClaw stores it as pending group history and includes it on the next processed group message.
• Group history limit defaults to
  text

  Copy

  messages.groupChat.historyLimit
  (fallback
  text

  Copy

  50
  ). You can override per account with
  text

  Copy

  channels.zalouser.historyLimit
  .

Example:

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

Multi-account

Accounts map to

profiles in OpenClaw state. Example:

json5
Copy
{
  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 (best-effort).
• Message reaction action
  text

  Copy

  react
  is supported for
  text

  Copy

  zalouser
  in channel actions.
  • Use
    text

    Copy

    remove: true
    to remove a specific reaction emoji from a message.
  • Reaction semantics: Reactions
• For inbound messages that include event metadata, OpenClaw sends delivered + seen acknowledgements (best-effort).

Troubleshooting

Login doesn't stick:

• text

  Copy

  openclaw channels status --probe
• Re-login:
  text

  Copy

  openclaw channels logout --channel zalouser && openclaw channels login --channel zalouser

Allowlist/group name didn't resolve:

• Use numeric IDs in
  text

  Copy

  allowFrom
  /
  text

  Copy

  groupAllowFrom
  /
  text

  Copy

  groups
  , or exact friend/group names.

Upgraded from old CLI-based setup:

• Remove any old external
  text

  Copy

  zca
  process assumptions.
• The channel now runs fully in OpenClaw without 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