OpenClawSkills
GitHub
通道 • 5 分钟阅读

Zalo 个人号

通过 zca-cli（扫码登录）接入 Zalo 个人号：能力与配置

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

Tutorial.alert.info

警告：这是非官方集成，可能导致账号被限制/封禁。请自行评估风险后使用。
Tutorial.step

需要安装插件

Zalo Personal 以插件形式提供，不随 core 安装打包。

- CLI 安装：openclaw plugins install @openclaw/zalouser

- 或从源码 checkout 安装：openclaw plugins install ./extensions/zalouser

- 详情：''/plugin''

Tutorial.step

前置条件：zca-cli

Gateway 机器必须在 PATH 中能找到 PATH 二进制。

- 验证：zca --version

- 若缺失，请安装 zca-cli（见 extensions/zalouser/README.md 或上游 zca-cli 文档）。

Tutorial.step

新手快速配置

1. 安装插件（见上文）。

2. 登录（二维码；在 gateway 机器上执行）：

- openclaw channels login --channel zalouser

- 用 Zalo 手机 App 扫描终端里的 QR。

3. 启用通道：

4. 重启 Gateway（或完成 onboarding）。

5. 私信默认 pairing：首次联系会收到配对码，批准后才会处理消息。

Json5
{
  channels: {
    zalouser: {
      enabled: true,
      dmPolicy: "pairing",
    },
  },
}
Tutorial.step

这是什么

- 使用 zca listen 接收入站消息。

- 使用 zca msg ... 发送回复（文本/媒体/链接）。

- 用于"无法使用 Zalo Bot API"的个人账号场景。

Tutorial.step

命名说明

通道 id 使用 zalouser，明确表示这是在自动化一个 Zalo 个人用户账号（非官方）。zalo 保留给未来可能的官方 Zalo API 集成。

Tutorial.step

查找 IDs（directory）

使用 directory CLI 查找联系人/群与对应 IDs：

Bash
openclaw directory self --channel zalouser
openclaw directory peers list --channel zalouser --query "name"
openclaw directory groups list --channel zalouser --query "work"
Tutorial.step

限制

- 出站文本按约 2000 字符分段（Zalo 客户端限制）。

- 默认禁用 streaming。

Tutorial.step

访问控制（私信）

channels.zalouser.dmPolicy 支持：pairing | allowlist | open | disabled（默认 pairing）。

channels.zalouser.allowFrom 接受 user IDs 或名称。向导会在可能时通过 zca friend find 把名称解析为 ID。

批准：

- openclaw pairing list zalouser

- openclaw pairing approve zalouser <code>

Tutorial.step

群聊访问（可选）

- 默认：channels.zalouser.groupPolicy = "open"（允许群）。未设置时可用 channels.defaults.groupPolicy 覆盖默认值。

- 如需限制为 allowlist：

- channels.zalouser.groupPolicy = "allowlist"

- channels.zalouser.groups（key 为群 ID 或名称）

- 禁用所有群：channels.zalouser.groupPolicy = "disabled"。

- configure 向导可提示填写群 allowlists。

- 启动时 OpenClaw 会尽力把 allowlists 中的群/用户名称解析为 ID，并把映射写日志；解析失败的条目会保留原样。

示例：

Json5
{
  channels: {
    zalouser: {
      groupPolicy: "allowlist",
      groups: {
        "123456789": { allow: true },
        "Work Chat": { allow: true },
      },
    },
  },
}
Tutorial.step

多账号

账号映射到 zca profiles。例如：

Json5
{
  channels: {
    zalouser: {
      enabled: true,
      defaultAccount: "default",
      accounts: {
        work: { enabled: true, profile: "work" },
      },
    },
  },
}
Tutorial.step

排障

找不到 zca：

- 安装 zca-cli，并确保 gateway 进程的 PATH 可找到它。

登录无法持久化：

- 运行：openclaw channels status --probe

- 重新登录：

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