跳转至

Zalo 个人

状态:实验性。此集成通过原生 zca-js 在进程内自动化个人 Zalo 账户,无需外部 CLI 二进制文件。

Warning

这是一个非官方集成,可能导致账户被停用或封禁。请自行承担使用风险。

安装

Zalo Personal 是一个官方外部插件,未随核心捆绑提供。使用前请先安装:

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

快速设置

  1. 安装插件(见上文)。
  2. 登录(在 Gateway 机器上扫描二维码):
  3. openclaw channels login --channel zalouser
  4. 使用 Zalo 手机应用扫描二维码。
  5. 启用该通道:
{
  channels: {
    zalouser: {
      enabled: true,
      dmPolicy: "pairing",
    },
  },
}
  1. 检查 openclaw channels status --probe;如果 Gateway 离线,请启动它。配置更改遵循热重载。
  2. 私信访问默认为配对模式;首次联系时批准配对码。

这是什么

  • 完全通过 zca-js 库在进程内运行(无外部 zca/openzca 二进制文件)。
  • 使用原生事件监听器(message、error)接收入站消息。
  • 直接通过 JS API 发送回复(文本/媒体/链接)。
  • 专为无法使用 Zalo Bot API 的“个人账户”场景而设计。

命名

通道 ID 为 zalouser,以明确它自动化的是一个个人 Zalo 用户账户(非官方)。zalo 保留给未来可能的官方 Zalo 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 仍会保留记录。
  • channels.zalouser.mediaMaxMb 以 MiB 为单位限制每个出站附件的大小。所选通道账户的 mediaMaxMb 会覆盖根配置,然后由 agents.defaults.mediaMaxMb 提供回退值。图片可能会被优化;省略限制则保留共享加载器的默认值。
  • 不支持流式传输。
  • 已完成的入站消息 ID 会保留 30 天,且每个账户最多保留最近 1000 条。

可选的 zalouser 工具选择的是凭证配置文件,而不是通道账户。 其图片操作仅在该账户使用所选配置文件时,才使用当前投递账户的限额。 否则,它会使用通道根配置和 agent 回退;它不会搜索恰好共用该配置文件的其他账户。 配置文件选择以及该工具的字面 default 配置文件均保持不变。

入站消息持久性

OpenClaw 在处理每条原始 zca-js 消息回调之前,会先将其存储。Gateway 重启后,待处理消息会从账户队列中恢复,并且每个私聊或群组的处理保持串行化。

zca-js socket 监听器不提供投递确认,也不会在重连后自动重放旧消息。因此,持久化队列只能保护回调到达 OpenClaw 之后的本地崩溃窗口;它无法恢复 socket 从未投递的消息。重放墓碑(replay tombstone)主要是一种保护机制,用于防止具有相同 Zalo 消息 ID 的重复回调。

访问控制(私信)

channels.zalouser.dmPolicy:pairing | allowlist | open | disabled(默认:pairing)。

channels.zalouser.allowFrom 应使用稳定的 Zalo 用户 ID。它也可以引用静态发送者访问组(accessGroup:<name>)。在交互式设置期间,可以使用插件的进程内联系人查找功能,将输入的名称解析为 ID。

如果配置中仍保留原始名称,则仅当启用 channels.zalouser.dangerouslyAllowNameMatching: true 时,启动时才会解析该名称。若未选择启用该选项,运行时发送者检查仅基于 ID,原始名称将被忽略,不参与授权。

通过以下方式批准:

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

群组访问(可选)

  • 默认:channels.zalouser.groupPolicy = "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> 引用。
  • 配置向导可以提示输入群组白名单。
  • 群组白名单匹配默认仅基于 ID。未解析的名称在认证时会被忽略,除非启用了 channels.zalouser.dangerouslyAllowNameMatching: true。
  • channels.zalouser.dangerouslyAllowNameMatching: true 是一种紧急兼容模式(break-glass compatibility mode),它会重新启用可变的启动时名称解析和运行时群组名称匹配。
  • 对于普通群组消息,groupAllowFrom 不会回退到 allowFrom:在白名单群组中将其留空,会让该群组对任何发送者开放。已授权的控制命令(例如 /new)属于例外;当 groupAllowFrom 为空时,命令发送者检查会回退到 allowFrom。

示例:

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

Note

channels.zalouser.groups.<id>.allow 是旧版字段名;当前配置使用 enabled。openclaw doctor --fix 会自动将 allow 迁移为 enabled。

群组提及门控

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

示例:

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

多账号

账号映射到 OpenClaw 状态中的 zalouser 配置文件。示例:

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

环境变量

配置文件选择也可以来自环境变量:

变量 用途
ZALOUSER_PROFILE 当通道或账号配置中未设置 profile 时使用的配置文件名称。
ZCA_PROFILE 旧版回退项,仅在未设置 ZALOUSER_PROFILE 时使用。

配置文件名称用于选择 OpenClaw 状态中保存的 Zalo 登录凭据。解析顺序:

  1. 配置中显式指定的 profile。
  2. ZALOUSER_PROFILE。
  3. ZCA_PROFILE。
  4. 非默认账号的账号 ID,或默认账号的 default。

对于多账号设置,建议在配置中为每个账号设置 profile,以免一个环境变量使多个账号共享同一登录会话。

输入状态、表情回应和送达确认

  • 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/基于 CLI 的设置升级:

  • 移除任何外部 zca 进程假设;该通道现在通过 zca-js 完全在进程内运行,没有外部 CLI 二进制文件。

升级后缺少 DM 历史记录:

  • 运行 openclaw doctor --fix 以修复受支持的旧版 DM 会话密钥。Doctor 会检查每个已配置的代理,包括命名代理,并保留真实的群组会话。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw