Zalo 个人

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

安装¶

Zalo Personal 是官方外部插件，未包含在核心中。使用前请安装：

openclaw plugins install @openclaw/zalouser

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

快速设置¶

1. 安装插件（如上）。
2. 登录（QR，在 Gateway 机器上）：
3. openclaw channels login --channel zalouser
4. 使用 Zalo 移动应用扫描二维码。
5. 启用通道：

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

1. 检查 openclaw channels status --probe；如果 Gateway 离线，请启动它。配置更改遵循热重载。
2. DM 访问默认为配对；首次联系时批准配对码。

它是什么¶

• 完全通过 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 工具选择的是凭据配置文件，而不是通道账号。 其 image 操作仅在当前投递账号使用所选配置文件时，才使用该账号的上限。 否则，它使用通道根配置和 agent 回退值； 它不会搜索恰好共享该配置文件的其他账号。配置文件 选择以及该工具的字面 default 配置文件保持不变。

入站持久性¶

OpenClaw 在处理每个原始 zca-js 消息回调之前都会存储它。待处理消息会在 Gateway 重启后从账号队列恢复，并且处理会按每个直接聊天或群组保持串行化。

zca-js socket 监听器不暴露投递确认，也不会在重连后自动重放旧消息。因此，持久队列保护的是回调到达 OpenClaw 之后的本地崩溃窗口；它无法恢复 socket 从未投递的消息。重放墓碑主要用于防止使用相同 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 是一种紧急兼容模式，会重新启用可变的启动名称解析和运行时群组名称匹配。
• 对于普通群组消息，groupAllowFrom 不会回退到 allowFrom：在已允许列表中群组上将其留空会使该群组对任何发送者开放。授权控制命令（例如 /new）是例外；当 groupAllowFrom 为空时，命令发送者检查会回退到 allowFrom。

示例：

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

群组提及门控¶

• channels.zalouser.groups.<group>.requireMention 控制群组回复是否需要提及。
• 解析顺序：群组 id -> group:<id> 别名 -> 群组名称/slug（基于名称的候选项仅在 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" },
      },
    },
  },
}

环境变量¶

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

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

1. 配置中显式指定的 profile。
2. ZALOUSER_PROFILE。
3. ZCA_PROFILE。
4. 非默认账户的账户 id，或默认账户的 default。

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

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

• OpenClaw 在分发回复前会发送输入状态事件（尽力而为）。
• 通道操作支持 zalouser 的消息表情回应操作 react。
• 使用 remove: true 从消息中移除特定的表情回应 emoji。
• 表情回应语义：表情回应
• 对于包含事件元数据的传入消息，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 身份验证和配对流程
• 群组 - 群组聊天行为和提及门控
• 通道路由 - 消息的会话路由
• 安全 - 访问模型和加固