Zalo 个人版

​

安装

openclaw plugins install @openclaw/zalouser

• 固定版本：openclaw plugins install @openclaw/zalouser@<version>
• 从源代码检出安装：openclaw plugins install ./path/to/local/zalouser-plugin
• 详情：插件。

​

快速设置

1. 安装插件（见上文）。
2. 登录（QR，在 Gateway 机器上）：
   • openclaw channels login --channel zalouser
   • 使用 Zalo 手机应用扫描二维码。
3. 启用该通道：

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

4. 重启 Gateway（或完成设置）。
5. DM 访问默认是 pairing；首次联系时请在配对码上批准。

​

它是什么

• 完全通过 zca-js 库在进程内运行（不需要外部 zca/openzca 二进制文件）。
• 使用原生事件监听器（message、error）接收传入消息。
• 直接通过 JS API 发送回复（文本/媒体/链接）。
• 面向“个人账号”使用场景设计，在这些场景中无法使用 Zalo Bot API。

​

命名

​

查找 ID（目录）

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

​

限制

• 出站文本按 2000 个字符分块（Zalo 客户端限制）。
• 不支持流式传输。
• 已完成的入站消息 ID 保留 30 天，每个账户最多保留最近的 1000 条记录。

​

入站持久性

​

访问控制（私信）

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

​

群组访问（可选）

• 默认：channels.zalouser.groupPolicy = "allowlist"（群组需要显式的 allowlist 条目）。
• 打开所有群组：channels.zalouser.groupPolicy = "open"。
• 屏蔽所有群组：channels.zalouser.groupPolicy = "disabled"。
• 当 groupPolicy = "allowlist" 时：
  • channels.zalouser.groups 的键应为稳定的群组 ID；仅当启用 channels.zalouser.dangerouslyAllowNameMatching: true 时，名称才会在启动时解析为 ID。
  • channels.zalouser.groupAllowFrom 控制允许的群组中哪些发送者可以触发机器人；静态发送者访问组可通过 accessGroup:<name> 引用。
• 配置向导可以提示输入群组 allowlist。
• 群组 allowlist 的匹配默认仅按 ID 进行。除非启用 channels.zalouser.dangerouslyAllowNameMatching: true，否则无法解析的名称会在认证时被忽略。
• channels.zalouser.dangerouslyAllowNameMatching: true 是一种破窗兼容模式，会重新启用可变的启动时名称解析和运行时群组名匹配。
• 对于普通群组消息，groupAllowFrom 不会 回退到 allowFrom：如果在一个已列入 allowlist 的群组中将其留空，则该群组对任意发送者开放。已授权的控制命令（例如 /new）是例外；当 groupAllowFrom 为空时，命令发送者检查会回退到 allowFrom。

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

​

群组提及门控

• channels.zalouser.groups.<group>.requireMention 控制群组回复是否需要提及。
• 解析顺序：group id -> group:<id> 别名 -> 群组名称/slug（基于名称的候选项仅在 dangerouslyAllowNameMatching: true 时适用）-> * -> 默认值（true）。
• 同时适用于 allowlist 群组和开放群组模式。
• 引用机器人的消息会被视为对群组激活的隐式提及。
• 已授权的控制命令（例如 /new）可以绕过提及门控。
• 当群组消息因需要提及而被跳过时，OpenClaw 会将其作为待处理的群组历史保存，并在下一条已处理的群组消息中包含它。
• 群组历史上限：channels.zalouser.historyLimit，然后是 messages.groupChat.historyLimit，最后的回退值为 50。

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

​

多账户

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

​

环境变量

1. 配置中的显式 profile。
2. ZALOUSER_PROFILE。
3. ZCA_PROFILE。
4. 非默认账号使用账号 id，默认账号使用 default。

​

打字、反应与送达确认

• OpenClaw 会在发送回复前先发送一个输入中事件（尽力而为）。
• 通道操作中支持 zalouser 的消息反应动作 react。
  • 使用 remove: true 可从消息中移除特定反应表情。
  • 反应语义：反应
• 对于包含事件元数据的入站消息，OpenClaw 会发送已送达 + 已查看确认（尽力而为）。

​

故障排除

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

• 在 allowFrom/groupAllowFrom 中使用数字 ID，并在 groups 中使用稳定的群组 ID。如果你有意需要精确的好友/群组名称，请启用 channels.zalouser.dangerouslyAllowNameMatching: true。

• 移除任何对外部 zca 进程的假设；该通道现在通过 zca-js 完全在进程内运行，不再需要外部 CLI 二进制文件。

​

相关内容

• Channels 概览 - 所有支持的渠道
• 配对 - DM 认证和配对流程
• 群组 - 群聊行为和提及门控
• 渠道路由 - 消息的会话路由
• 安全 - 访问模型和加固。