消息平台

Zalo 个人账号

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

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

安装插件

Zalo 个人账号以插件形式提供，不包含在核心安装包中。你需要先安装插件才能使用：

通过 CLI 安装：openclaw plugins install @openclaw/zalouser
或从源码目录安装：openclaw plugins install ./extensions/zalouser
详细说明请参阅插件

安装后无需额外配置外部 zca 或 openzca CLI 二进制文件。

快速上手

如果你是第一次使用，按以下步骤即可快速完成配置：

安装插件（见上文）。
在网关机器上登录账号：
- 运行 openclaw channels login --channel zalouser
- 使用 Zalo 手机应用扫描显示的二维码
在配置中启用频道：

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

重启网关（或完成引导流程）。
私信访问默认使用配对模式，首次联系时需要批准配对码。

工作原理

这个集成完全在 OpenClaw 进程内通过 zca-js 运行，无需外部依赖：

使用原生事件监听器实时接收消息
通过 JS API 直接发送回复（支持文本、媒体、链接）
专为无法使用 Zalo Bot API 的「个人账号」场景设计

为什么叫 zalouser

频道 ID 使用 zalouser 而非 zalo，是为了明确表示这是自动化个人 Zalo 用户账号的非官方方案。我们保留 zalo 这个名称，以便未来支持官方 Zalo API 集成。

查找联系人和群组 ID

配置访问控制时，你需要知道联系人和群组的 ID。使用目录 CLI 可以快速查找：

# 查看当前账号信息
openclaw directory self --channel zalouser

# 搜索联系人
openclaw directory peers list --channel zalouser --query "name"

# 搜索群组
openclaw directory groups list --channel zalouser --query "work"

已知限制

使用前请了解以下限制：

发送的消息会被自动分块，每段约 2000 字符（Zalo 客户端限制）
默认禁用流式输出功能

控制谁能私信你的智能体

通过配置 dmPolicy，你可以决定谁可以通过私信与你的智能体交互。channels.zalouser.dmPolicy 支持以下选项（默认为 pairing）：

pairing — 首次联系需要批准配对码
allowlist — 仅允许白名单中的用户
open — 允许所有人
disabled — 禁用私信功能

你还可以通过 channels.zalouser.allowFrom 指定允许的用户 ID 或名称。在引导过程中，名称会自动解析为 ID。

批准配对请求：

# 查看待批准的配对请求
openclaw pairing list zalouser

# 批准特定配对码
openclaw pairing approve zalouser <code>

控制智能体可以加入哪些群组

默认情况下，智能体可以加入任何群组（groupPolicy = "open"）。你可以通过以下方式限制群组访问：

限制到白名单：

{
  channels: {
    zalouser: {
      groupPolicy: "allowlist",
      groups: {
        "123456789": { allow: true },
        "Work Chat": { allow: true },
      },
    },
  },
}

禁止所有群组：

{
  channels: {
    zalouser: {
      groupPolicy: "disabled",
    },
  },
}

配置向导会在设置时提示你输入群组白名单。启动时，OpenClaw 会将白名单中的群组/用户名称解析为 ID 并记录映射关系；无法解析的条目会保持原样。

群组中是否需要 @提及才回复

通过 requireMention 可以控制智能体在群组中是否只在被提及时才回复：

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

解析顺序：精确的群组 ID/名称 → 规范化的群组 slug → * 通配符 → 默认值（true）。此设置对白名单群组和开放群组模式都生效。

配置多个 Zalo 账号

如果你需要同时使用多个 Zalo 个人账号，可以通过配置多个 profile 实现：

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

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

为了提供更好的对话体验，zalouser 频道支持以下功能：

输入状态：发送回复前，OpenClaw 会尽力发送「正在输入」状态
表情反应：支持通过频道操作发送 react 动作
- 使用 remove: true 可移除特定表情反应
- 详细说明请参阅反应
送达确认：对于包含事件元数据的入站消息，OpenClaw 会尽力发送「已送达」和「已读」确认

常见问题

登录状态无法保持：

# 检查频道状态
openclaw channels status --probe

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

白名单或群组名称没有正确解析：

在 allowFrom 或 groups 中使用数字 ID，或确保使用完全匹配的联系人/群组名称。

从旧版 CLI 方案升级：

如果你之前使用过基于外部 zca 进程的旧方案，请移除相关配置。新版本完全在 OpenClaw 内部运行，不再需要外部 CLI 二进制文件。

Zalo 配对

安装插件​

快速上手​

工作原理​

为什么叫 zalouser​

查找联系人和群组 ID​

已知限制​

控制谁能私信你的智能体​

控制智能体可以加入哪些群组​

群组中是否需要 @提及才回复​

配置多个 Zalo 账号​

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

常见问题​