文档
渠道（Channels）
Zalo 个人账号（非官方）

Zalo 个人账号（非官方）

适用范围

在以下情况使用本页：

  • 为 Clawdbot 配置 Zalo 个人账号
  • 调试 Zalo 个人账号登录或消息流

状态：实验性功能。此集成通过 zca-cli 自动化个人 Zalo 账号。

**警告：**这是非官方集成，可能导致账号被暂停/封禁。使用风险自负。

需要插件

Zalo 个人账号以插件形式提供，不包含在核心安装中。

  • 通过 CLI 安装：clawdbot plugins install @clawdbot/zalouser
  • 或从源码检出：clawdbot plugins install ./extensions/zalouser
  • 详情：插件

前置条件：zca-cli

Gateway 机器必须在 PATH 中可用 zca 二进制文件。

  • 验证：zca --version
  • 如果缺失，安装 zca-cli（见 extensions/zalouser/README.md 或上游 zca-cli 文档）。

快速设置（初学者）

  1. 安装插件（见上文）。
  2. 登录（QR 码，在 Gateway 机器上）：
    • clawdbot channels login --channel zalouser
    • 使用 Zalo 移动应用扫描终端中的 QR 码。
  3. 启用渠道：
{
  channels: {
    zalouser: {
      enabled: true,
      dmPolicy: "pairing"
    }
  }
}
  1. 重启 Gateway（或完成入门配置）。
  2. 私信访问默认为配对模式；首次联系时批准配对码。

工作原理

  • 使用 zca listen 接收入站消息。
  • 使用 zca msg ... 发送回复（文本/媒体/链接）。
  • 专为 Zalo Bot API 不可用的"个人账号"使用场景设计。

命名说明

渠道 ID 为 zalouser，明确表示这是自动化个人 Zalo 用户账号（非官方）。我们将 zalo 保留给未来可能的官方 Zalo API 集成。

查找 ID（目录）

使用目录 CLI 发现对等方/群组及其 ID：

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

限制

  • 出站文本分块约 2000 字符（Zalo 客户端限制）。
  • 默认阻止流式传输。

访问控制（私信）

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

通过以下方式批准：

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

群组访问（可选）

  • 默认：channels.zalouser.groupPolicy = "open"（允许群组）。使用 channels.defaults.groupPolicy 在未设置时覆盖默认值。
  • 使用白名单限制：
    • channels.zalouser.groupPolicy = "allowlist"
    • channels.zalouser.groups（键是群组 ID 或名称）
  • 阻止所有群组：channels.zalouser.groupPolicy = "disabled"。
  • 配置向导可以提示群组白名单。
  • 启动时，Clawdbot 将白名单中的群组/用户名称解析为 ID 并记录映射；未解析的条目保持原样。

示例：

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

多账号

账号映射到 zca 配置文件。示例：

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

故障排除

找不到 zca：

  • 安装 zca-cli 并确保其在 Gateway 进程的 PATH 中。

登录无法保持：

  • clawdbot channels status --probe
  • 重新登录：clawdbot channels logout --channel zalouser && clawdbot channels login --channel zalouser
WhatsApp（Web 渠道）Zalo（Bot API）