Zalo 个人账号（非官方）

状态：实验性。本集成通过 OpenClaw 内部的原生 zca-js 自动化个人 Zalo 账号。

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

需要安装插件

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

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

无需外部 zca/openzca CLI 二进制文件。

快速配置（新手上路）

1. 安装插件（见上方）。
2. 登录（在 Gateway 所在机器上 QR 扫码）：
   • openclaw channels login --channel zalouser
   • 用 Zalo 手机 APP 扫描 QR 码。
3. 启用渠道：

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

4. 重启 Gateway（或完成设置流程）。
5. 私信访问默认为配对模式，首次联系时批准配对码。

产品定位

• 完全在进程内通过 zca-js 运行。
• 使用原生事件监听器接收入站消息。
• 通过 JS API 直接发送回复（文本/媒体/链接）。
• 专为无法使用 Zalo Bot API 的"个人账号"场景设计。

渠道 ID 说明

渠道 ID 为 zalouser，明确表示这是对个人 Zalo 用户账号的自动化（非官方）。zalo 保留给潜在的未来官方 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 客户端限制）。
• 流式输出默认被屏蔽。

私信访问控制

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

channels.zalouser.allowFrom 接受用户 ID 或名称。设置时，名称通过插件内置的联系人查询解析为 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；名称在启动时尽可能解析为 ID）
  • channels.zalouser.groupAllowFrom（控制允许的群组内哪些发送方可触发机器人）
• 屏蔽所有群组：channels.zalouser.groupPolicy = "disabled"。
• 配置向导可提示配置群组白名单。
• 启动时 OpenClaw 将白名单中的群组/用户名解析为 ID 并记录映射关系。
• 群组白名单匹配默认只用 ID。未解析的名称在授权时被忽略，除非启用 channels.zalouser.dangerouslyAllowNameMatching: true。
• channels.zalouser.dangerouslyAllowNameMatching: true 是应急兼容模式，会重新启用可变的群组名称匹配。
• 未设置 groupAllowFrom 时回退到 allowFrom。
• 发送方检查同时适用于普通群组消息和控制命令（如 /new、/reset）。

群组白名单示例：

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

群组提及门控

• channels.zalouser.groups.<group>.requireMention 控制群组回复是否需要提及。
• 解析顺序：精确群组 id/name -> 标准化群组 slug -> * -> 默认（true）。
• 适用于白名单群组和开放群组模式。
• 已授权的控制命令（如 /new）可绕过提及门控。
• 群组消息因需要提及被跳过时，OpenClaw 将其存为待处理群组历史，并在下一条被处理的群组消息时作为上下文注入。
• 群组历史限制默认为 messages.groupChat.historyLimit（回退 50）。可通过 channels.zalouser.historyLimit 按账号覆盖。

提及门控配置示例：

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

多账号

账号映射到 OpenClaw 状态中的 zalouser profile：

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

输入状态、反应与投递确认

• OpenClaw 在发送回复前发送输入状态事件（尽力而为）。
• zalouser 的渠道动作支持消息反应动作 react。
  • 使用 remove: true 移除消息上的特定反应 emoji。
  • 反应语义：Reactions
• 对于包含事件元数据的入站消息，OpenClaw 发送已投递 + 已查看确认（尽力而为）。

故障排查

登录后不保持状态：

openclaw channels status --probe
# 重新登录：
openclaw channels logout --channel zalouser && openclaw channels login --channel zalouser

白名单/群组名未解析：

• 在 allowFrom/groupAllowFrom/groups 中使用数字 ID，或精确的好友/群组名称。

从旧版 CLI 方式迁移：

• 移除对外部 zca 进程的任何假设。
• 渠道现在完全在 OpenClaw 内运行，无需外部 CLI 二进制文件。