8.15 Zalo个人版

Zalo个人版（非官方）通过 zca-cli 自动化个人账号，实现与 Zalo 的对话收发。

状态

实验性（experimental）。该集成通过 zca-cli 自动化个人账号。

需要插件

Zalo个人版以插件形式提供，核心安装不包含：

• 通过 CLI 安装：openclaw plugins install @openclaw/zalouser
• 从源码检出安装：openclaw plugins install ./extensions/zalouser
• 详情见 插件系统

插件在 Gateway 进程中运行，因此必须安装在运行 Gateway 的机器上，并在安装后重启 Gateway。若从本地目录安装，请先在该目录执行 pnpm install。

前置条件：zca-cli

Gateway 所在机器必须能在 PATH 中找到 zca：

zca --version

如果未安装，请参考 extensions/zalouser/README.md 或 zca-cli 上游文档。

快速开始（新手）

1. 安装插件（见上文）。
2. 在 Gateway 机器上登录（终端显示二维码）：

openclaw channels login --channel zalouser

使用 Zalo 手机端扫码登录。

3. 启用频道：

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

4. 重启 Gateway（或完成向导）。
5. 首次私聊默认需要配对，审批配对码。

它是什么

• 使用 zca listen 接收消息。
• 使用 zca msg ... 发送回复（文本/媒体/链接）。
• 适用于无法使用 Zalo Bot API 的“个人账号”场景。

命名

频道 id 为 zalouser，用于明确这是个人账号自动化（非官方）。zalo 保留给未来可能的官方 API 集成。

查找 ID（目录）

用目录 CLI 查询联系人/群组的 ID：

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

限制

• 外发文本会按约 2000 字符分片（Zalo 客户端限制）。
• 默认关闭流式输出。

CLI 命令

• openclaw channels login --channel zalouser
• openclaw channels logout --channel zalouser
• openclaw channels status --probe
• openclaw channels doctor

代理工具

通过 message 工具发送消息，channel 指定为 zalouser，支持的动作包括 chat、message。

访问控制（私聊）

channels.zalouser.dmPolicy 支持：pairing | allowlist | open | disabled（默认 pairing）。channels.zalouser.allowFrom 支持用户 ID 或名称。向导可在可用时通过 zca friend find 将名称解析为 ID。

审批示例：

openclaw pairing list zalouser
openclaw pairing approve zalouser <code>

群组访问（可选）

• 默认：channels.zalouser.groupPolicy = "open"（允许群组）。
• 如未显式设置，可用 channels.defaults.groupPolicy 覆盖默认值。
• 限制允许列表：
• channels.zalouser.groupPolicy = "allowlist"
• channels.zalouser.groups（键为群组 ID 或名称）
• 完全禁止群组：channels.zalouser.groupPolicy = "disabled"。
• 向导可提示设置群组白名单。
• 启动时会将白名单中的名称解析为 ID（解析失败保留原值）。

示例：

{
  channels: {
    zalouser: {
      groupPolicy: "allowlist",
      groups: {
        "123456789": { allow: true },
        "Work Chat": { allow: true },
      },
    },
  },
}

多账号

账号映射到 zca profiles：

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

故障排除

找不到 zca：安装 zca-cli 并确保 Gateway 进程的 PATH 可访问。

登录不生效：

openclaw channels status --probe
openclaw channels logout --channel zalouser
openclaw channels login --channel zalouser