Zalo 个人
状态:实验性。此集成通过原生 zca-js 在进程内自动化个人 Zalo 账户,无需外部 CLI 二进制文件。
Warning
这是一个非官方集成,可能导致账户被停用或封禁。请自行承担使用风险。
安装¶
Zalo Personal 是一个官方外部插件,未随核心捆绑提供。使用前请先安装:
- 固定版本:
openclaw plugins install @openclaw/zalouser@<version> - 从源代码检出安装:
openclaw plugins install ./path/to/local/zalouser-plugin - 详情:插件
快速设置¶
- 安装插件(见上文)。
- 登录(在 Gateway 机器上扫描二维码):
openclaw channels login --channel zalouser- 使用 Zalo 手机应用扫描二维码。
- 启用该通道:
- 检查
openclaw channels status --probe;如果 Gateway 离线,请启动它。配置更改遵循热重载。 - 私信访问默认为配对模式;首次联系时批准配对码。
这是什么¶
- 完全通过
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 zalouseropenclaw 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 登录凭据。解析顺序:
- 配置中显式指定的
profile。 ZALOUSER_PROFILE。ZCA_PROFILE。- 非默认账号的账号 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