Zalo Personal（非官方）

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

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

需要安装插件

Zalo Personal 以插件形式提供，不包含在核心安装中。

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

不需要外部 zca/openzca CLI 程序。

快速开始

安装插件（见上文）。
登录（QR 扫码，在 Gateway 机器上操作）：
- openclaw channels login --channel zalouser
- 使用 Zalo 手机应用扫描 QR 码。
启用频道：

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

重启 Gateway（或完成引导）。
私信默认使用配对模式；首次联系时审批配对码。

简介

完全在进程内通过 zca-js 运行。
使用原生事件监听器接收入站消息。
通过 JS API 直接发送回复（文本/媒体/链接）。
适用于 Zalo Bot API 不可用时的”个人账号”使用场景。

命名说明

频道 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/名称 -> 标准化群组 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 配置文件。示例：

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

输入指示器、表情回应和投递确认

OpenClaw 在发送回复前发送输入事件（尽力而为）。
频道操作中的消息表情回应 react 对 zalouser 可用。
- 使用 remove: true 移除消息上的特定表情 emoji。
- 表情回应语义：表情回应
对于包含事件元数据的入站消息，OpenClaw 发送已送达 + 已读确认（尽力而为）。

故障排查

登录状态不保持：

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

白名单/群组名称未解析：

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

从旧版基于 CLI 的设置升级：

移除对旧版外部 zca 进程的依赖。
该频道现在完全在 OpenClaw 内运行，无需外部 CLI 程序。