OpenClaw Manual OpenClaw

OpenClaw Zalo Personal Channel

Messaging
Medium

Connect OpenClaw to your personal Zalo account using the unofficial zca-cli tool. Unlike the Zalo Bot Platform integration, this channel lets your AI assistant operate through a real Zalo personal account — with support for group chats, media, and friend lists. Authenticate by scanning a QR code, just like linking a new device.

Quick Info
Difficulty Medium
Category Messaging
Features Supported 3 / 6

Zalo Personal Supported Features

Text Messages

Supported

Media & Files

Supported

Reactions

Not Supported

Threads

Not Supported

Voice Messages

Not Supported

Group Chat

Supported

Zalo Personal Prerequisites

  • A personal Zalo account (standard account, not an Official Account)
  • The zca binary installed and available in your system PATH
  • OpenClaw Gateway running and configured
  • Zalo mobile app for QR code scanning during login

Zalo Personal Quick Setup

1

Install the zalouser plugin and zca-cli

Install the OpenClaw plugin with 'openclaw plugins install @openclaw/zalouser'. Then install the zca-cli tool and ensure it's in your PATH. Verify with 'zca --version'.

2

Login via QR code

Run 'openclaw channels login --channel zalouser' to display a QR code in your terminal. Open the Zalo app on your phone and scan the QR code to authenticate the session.

3

Configure and start chatting

Add the zalouser channel configuration to ~/.openclaw/openclaw.json with your preferred dmPolicy and groupPolicy. Start the Gateway with 'openclaw start' and send a message to your Zalo account to test.

Zalo Personal Configuration Example

config.json 
{
  "channels": {
    "zalouser": {
      "enabled": true,
      "dmPolicy": "pairing",
      "groupPolicy": "open"
    }
  }
}

Zalo Personal Deep Dive

Architecture Overview

OpenClaw connects to Zalo through the zca-cli tool — an unofficial command-line client for personal Zalo accounts. Unlike the Zalo Bot Platform integration (which uses HTTP APIs), this channel uses the zca binary to listen for inbound messages and send outbound responses. The Gateway runs 'zca listen' as a background process to receive messages in real-time, and uses 'zca msg' to send replies. This approach works entirely locally — no public URL, webhook, or HTTPS certificate is needed. Because this uses a personal account, the bot can participate in group chats, access friend lists, and send media — features not available through the official Bot Platform.
This is an unofficial integration. Using it may risk account suspension or ban from Zalo. Use a dedicated account rather than your primary personal account.
The zca-cli tool handles the protocol layer. Keep it updated to maintain compatibility with Zalo's service.
This is an experimental integration using an unofficial tool. Zalo may suspend or ban accounts using third-party automation. Use at your own risk.

Installing zca-cli

The zca-cli binary is a prerequisite for this channel. It must be installed and accessible in your system PATH before the Gateway can use the Zalo Personal channel. After installation, verify it's working by running 'zca --version' in your terminal. If the command is not found, check your PATH configuration or reinstall the tool.
terminal 
zca --version
If zca is installed but not in PATH, you can add its directory to your PATH in your shell profile (~/.bashrc, ~/.zshrc, etc.).

QR Code Authentication

Authentication is done by scanning a QR code with your Zalo mobile app — similar to how you'd link a new device. No API tokens or bot tokens are needed. Run the login command to display the QR code in your terminal. Open Zalo on your phone, navigate to the QR scanner, and scan the code. The session will be established and credentials stored locally. If the login does not persist after a restart, try logging out and logging back in to refresh the session.
terminal 
# Login
openclaw channels login --channel zalouser

# If login doesn't persist, re-authenticate
openclaw channels logout --channel zalouser
openclaw channels login --channel zalouser
Keep your phone connected to the internet during the QR scan. The session is validated through Zalo's servers.

DM Policies

DM (Direct Message) policies control who can interact with your AI assistant via private messages. OpenClaw supports four policies: • pairing (default) — New contacts receive a pairing code when they first message you. Approve them via 'openclaw pairing approve zalouser <code>'. Codes expire after 1 hour. • allowlist — Only user IDs or names listed in allowFrom can message the bot. Names are resolved to IDs via 'zca friend find'. • open — Anyone who messages the account gets a response. • disabled — DM handling is completely turned off.
openclaw.json 
{
  "channels": {
    "zalouser": {
      "dmPolicy": "allowlist",
      "allowFrom": ["123456789", "Friend Name"]
    }
  }
}
The 'open' policy lets anyone interact with your personal account. Since this is a real Zalo account visible to your contacts, use with caution.

Group Chat Management

Unlike the Zalo Bot Platform integration, Zalo Personal fully supports group chats. By default, the groupPolicy is set to 'open', meaning the bot will respond in all group conversations. You can restrict group access using the 'allowlist' policy with a groups mapping. Groups can be referenced by their numeric ID or by name. Set groupPolicy to 'disabled' to ignore all group messages entirely.
openclaw.json 
{
  "channels": {
    "zalouser": {
      "groupPolicy": "allowlist",
      "groups": {
        "123456789": { "allow": true },
        "Work Chat": { "allow": true }
      }
    }
  }
}
Use 'openclaw directory groups list --channel zalouser --query "name"' to find group IDs and names.
Group names are case-sensitive. Use the exact name as shown in your Zalo app.

Message Handling

OpenClaw supports sending text messages, images, files, and links through Zalo Personal. Text messages are automatically chunked at approximately 2,000 characters to comply with Zalo's client limits. Inbound messages from contacts and groups are received via the 'zca listen' process and forwarded to the AI. Outbound responses are sent using 'zca msg'. Streaming responses are blocked by default due to the character limit constraint.
Long AI responses are automatically split into multiple messages at the ~2,000-character boundary.
Media sending capabilities depend on the zca-cli version installed. Keep it updated for best compatibility.

Multi-Account Setup

OpenClaw supports running multiple Zalo personal accounts simultaneously by mapping to different zca profiles. Each account has its own profile name, DM policy, and group settings. This is useful if you want to run separate AI assistants for different purposes — for example, a work account and a personal account.
openclaw.json 
{
  "channels": {
    "zalouser": {
      "enabled": true,
      "defaultAccount": "default",
      "accounts": {
        "work": {
          "enabled": true,
          "profile": "work"
        },
        "personal": {
          "enabled": true,
          "profile": "personal"
        }
      }
    }
  }
}

Directory & Discovery

The Zalo Personal channel provides directory commands for discovering friends and groups on your account. These are useful for finding user IDs for allowlists or group IDs for group policies. You can view your own profile, search for friends by name, and search for groups by name — all from the command line.
terminal 
# View your profile
openclaw directory self --channel zalouser

# Search friends
openclaw directory peers list --channel zalouser --query "name"

# Search groups
openclaw directory groups list --channel zalouser --query "work"

Zalo Personal Configuration Reference

enabled
Type: boolean Default: false

Enable or disable the Zalo Personal channel

dmPolicy
Type: string Default: "pairing"

Controls who can DM the bot. Options: pairing, allowlist, open, disabled

allowFrom
Type: string[] Default: []

User IDs or names allowed to message the bot (when dmPolicy is allowlist)

groupPolicy
Type: string Default: "open"

Controls group chat behavior. Options: open, allowlist, disabled

groups
Type: object Default: {}

Map of group IDs or names to permission objects (when groupPolicy is allowlist)

defaultAccount
Type: string Default: "default"

The default zca profile name to use

accounts.<id>.enabled
Type: boolean Default: true

Enable or disable a specific account in multi-account mode

accounts.<id>.profile
Type: string Default: ""

The zca profile name for a specific account

Zalo Personal Frequently Asked Questions

Zalo Personal Troubleshooting

zca command not found

The zca-cli binary is not installed or not in your system PATH.

Install zca-cli and ensure it's in your PATH. Verify with 'zca --version'. If installed but not found, add its installation directory to your PATH in ~/.bashrc or ~/.zshrc.
QR code login fails or session doesn't persist

The Zalo session may have expired or the initial authentication was incomplete.

Try logging out and logging back in: 'openclaw channels logout --channel zalouser' then 'openclaw channels login --channel zalouser'. Ensure your phone has a stable internet connection during the QR scan.
Bot does not respond to group messages

groupPolicy may be set to 'disabled' or 'allowlist' without the group being listed.

Check your groupPolicy setting. If using 'allowlist', ensure the group ID or name is listed in the groups configuration. Use 'openclaw directory groups list --channel zalouser' to find the correct group ID.
Messages are not being received

The zca listen process may not be running, or the session has expired.

Run 'openclaw channels status --probe' to diagnose the connection. If the session has expired, re-authenticate via QR code login. Check Gateway logs for specific error messages.
Account was suspended or banned

Zalo detected unofficial automation on the account.

This is a known risk of using unofficial integrations. Contact Zalo support to attempt account recovery. Consider switching to the official Zalo Bot Platform integration (zalo channel) which has no ban risk, though it lacks group chat support.
View Full Documentation Back to All Channels

Related Channels

WhatsApp

Medium

Connect OpenClaw via QR code using Baileys protocol

Setup Guide

Telegram

Easy

OpenClaw bot via Telegram grammY Bot API

Setup Guide

Discord

Easy

OpenClaw bot integration using discord.js

Setup Guide