Zalo Personal（zalouser）是 OpenClaw 的实验性插件，通过自动化个人 Zalo 账号实现 AI 助手功能。与官方 Zalo Bot API 不同，它使用 zca-js 原生库在进程内直接操控个人账号。
⚠️ 风险警告：这是非官方集成，使用个人账号自动化可能导致账号被封禁或限制。请自行评估风险，并优先考虑使用官方 Zalo Bot API（
zalo频道） 替代方案。
安装插件
# 从 npm 安装
openclaw plugins install @openclaw/zalouser
# 或从源码安装
openclaw plugins install ./extensions/zalouser无需安装任何外部 zca 或 openzca CLI 二进制文件，插件内嵌 zca-js 完整运行时。
快速配置（5 步完成）
第一步：安装插件
见上方安装命令。
第二步：扫码登录
在 Gateway 机器上执行登录命令，会显示二维码：
openclaw channels login --channel zalouser用 Zalo 手机 App 扫描二维码完成授权。
第三步：配置频道
{
"channels": {
"zalouser": {
"enabled": true,
"dmPolicy": "pairing"
}
}
}第四步：重启 Gateway
openclaw gateway restart第五步：批准第一次配对
有人首次发 DM 时，用以下命令查看并批准：
openclaw pairing list zalouser
openclaw pairing approve zalouser <配对码>Zalo Personal vs Zalo Bot API
| 维度 | Zalo Personal（zalouser） | Zalo Bot（zalo） |
|---|---|---|
| 账号类型 | 个人账号 | 官方 Bot 账号 |
| 官方支持 | ❌ 非官方，有封号风险 | ✅ 官方支持，合规 |
| 申请门槛 | 无需申请，直接登录 | 需要向 Zalo OA 申请 |
| 稳定性 | 较低（依赖逆向工程） | 高 |
| 适用场景 | 个人使用、小规模测试 | 企业级部署、公开服务 |
建议：如果有条件申请官方 Zalo OA Bot，优先使用 zalo 频道。zalouser 更适合个人使用场景或官方 API 无法满足需求时的临时方案。
访问控制
DM 访问策略
{
"channels": {
"zalouser": {
"dmPolicy": "pairing"
}
}
}| 策略 | 说明 |
|---|---|
pairing | 默认，首次联系需配对审批 |
allowlist | 仅允许 allowFrom 中列出的用户 ID 或名称 |
open | 允许任何 Zalo 用户发送 DM |
disabled | 完全禁用 DM 功能 |
白名单配置
{
"channels": {
"zalouser": {
"dmPolicy": "allowlist",
"allowFrom": ["朋友名字", "123456789"]
}
}
}allowFrom 中可以填用户名称或 ID，启动时 OpenClaw 会自动将名称解析为 ID。
群组访问控制
默认情况下，群组消息是开放的（groupPolicy: "open"）。
{
"channels": {
"zalouser": {
"groupPolicy": "allowlist",
"groups": {
"工作群": { "requireMention": true },
"家庭群": { "requireMention": false }
}
}
}
}| 群组策略 | 说明 |
|---|---|
open | 允许所有群组（默认） |
allowlist | 仅允许 groups 中列出的群组 |
disabled | 禁用所有群组响应 |
requireMention: true 表示群组中必须 @Bot 账号才会响应。
查找联系人和群组 ID
# 查看自己的账号信息
openclaw directory self --channel zalouser
# 搜索联系人
openclaw directory peers list --channel zalouser --query "朋友姓名"
# 搜索群组
openclaw directory groups list --channel zalouser --query "群名关键词"多账号配置
如需同时运行多个 Zalo 个人账号，使用多实例配置：
{
"channels": {
"zalouser": { "enabled": true, "dmPolicy": "pairing" },
"zalouser2": {
"plugin": "@openclaw/zalouser",
"enabled": true,
"dmPolicy": "allowlist",
"allowFrom": ["special-user-id"]
}
}
}每个账号独立登录：
openclaw channels login --channel zalouser2功能限制
| 功能 | 支持情况 | 备注 |
|---|---|---|
| 文本消息 | ✅ | 单次最多约 2000 字符 |
| 媒体/图片 | ✅ | 通过 JS API 发送 |
| 链接分享 | ✅ | 支持富文本链接 |
| 流式响应 | ❌ | 默认禁用 |
| 消息撤回 | ❌ | 暂不支持 |
| 贴纸/表情 | ❌ | 暂不支持 |
常见问题
二维码扫描后无响应？
确认 openclaw channels login 命令是在 Gateway 所在机器上执行，远程 SSH 执行时确保终端支持二维码显示。
账号被限制？ 减少消息频率，避免短时间内大量发送消息。考虑切换到官方 Zalo Bot API 方案。
群组中不响应？
检查 groupPolicy 是否为 allowlist 且未将该群组加入白名单，或确认群组中已正确设置 requireMention。
原文：Zalo Personal - OpenClaw | 来源：OpenClaw 官方文档