OpenClaw Zalo 个人号插件 (Zalo Personal Plugin) 指南

⚠️ 重要风险提示： 本插件通过非官方协议 (zca-js) 模拟普通用户行为，并非 Zalo 官方 API。 使用自动化脚本操作个人账号可能导致账号被限制、封禁或永久冻结。 请谨慎使用，后果自负。 建议仅用于测试账号或非关键业务场景。

🧐 一、核心概念与命名

为什么叫 zalouser？

• zalouser：明确标识这是针对个人用户账号 (Personal User Account) 的非官方自动化方案。
• zalo (保留)：预留给未来可能出现的 Zalo 官方企业 API (Official API) 集成。

运行架构

• 运行位置：插件直接运行在 OpenClaw Gateway 进程内部。
• 依赖：内置 zca-js 库，无需安装外部的 zca 或 openzca 命令行二进制文件。
• 部署注意：如果你使用远程 Gateway，必须将插件安装并配置在运行 Gateway 的那台机器上，然后重启 Gateway。

🛠️ 二、安装步骤

方式 A：从 NPM 安装 (推荐)

openclaw plugins install @openclaw/zalouser

安装完成后，务必重启 Gateway：

openclaw gateway restart

方式 B：本地开发模式

# 安装插件链接
openclaw plugins install ./extensions/zalouser
# 进入目录安装依赖
cd ./extensions/zalouser && pnpm install

同样需要重启 Gateway。

⚙️ 三、配置指南

Zalo 个人号作为通讯通道，其配置位于 channels 层级，而非 plugins.entries。

基础配置 (openclaw.json)

{
  "channels": {
    "zalouser": {
      // 启用通道
      "enabled": true,
      
      // 私聊策略：
      // "pairing": 仅回复已配对/好友的用户 (推荐，更安全)
      // "all": 尝试回复所有消息 (高风险，易被封)
      "dmPolicy": "pairing"
    }
  }
}

💡 提示：dmPolicy 设置为 pairing 可以有效降低被系统判定为骚扰机器人的风险。

🔑 四、登录与管理 (CLI)

由于是非官方协议，登录通常需要通过扫码认证。所有操作通过 openclaw channels 命令完成。

1. 扫码登录

启动登录流程，终端会显示二维码或提示扫码：

openclaw channels login --channel zalouser

操作流程：

1. 运行命令。
2. 使用手机 Zalo App 扫描终端显示的二维码。
3. 在手机端确认登录。
4. 登录成功后，凭证会自动保存（通常加密存储在本地）。

2. 退出登录

清除本地保存的凭证：

openclaw channels logout --channel zalouser

3. 查看状态

检查当前连接状态和账号信息：

openclaw channels status --probe

4. 发送测试消息

手动测试通道是否正常工作：

openclaw message send --channel zalouser --target <threadId> --message "Hello from OpenClaw"

注：<threadId> 通常是好友的 ID 或群聊 ID。

5. 查询好友/群组

列出联系人或群组：

# 查询好友
openclaw directory peers list --channel zalouser --query "name"

# 查询群组 (如果支持)
# openclaw directory groups list --channel zalouser

🤖 五、Agent 工具能力 (zalouser)

安装后，OpenClaw 的智能体 (Agent) 将自动获得 zalouser 工具包，可以自主执行以下操作：

场景示例

用户指令：“把上周的销售报表图片发给‘华东区销售群’，并@所有人。” Agent 执行逻辑：

1. 调用 zalouser.groups 找到“华东区销售群”的 ID。
2. 调用 zalouser.image 上传图片。
3. 调用 zalouser.send 发送文本“@everyone 请查收周报”。

⚠️ 六、安全与风控最佳实践

鉴于非官方协议的风险，请务必遵守以下原则：

1. 频率限制：
   • 不要在短时间内发送大量消息。
   • 在 Agent 配置中设置合理的 rateLimit，避免触发 Zalo 的风控机制。
2. 内容合规：
   • 严禁发送垃圾广告、敏感政治内容或违规链接。
   • 尽量模拟真人的说话语气和节奏。
3. 账号隔离：
   • 不要使用你的主用私人账号运行此插件。
   • 专门注册一个“工作号”用于自动化，即使被封也不影响个人生活。
4. 监控日志：
   • 定期查看 openclaw logs，关注是否有登录失败、发送被拒等异常信号。一旦频繁报错，立即停止运行并冷却账号。
5. IP 稳定性：
   • 尽量保持运行 Gateway 的服务器 IP 地址相对固定。频繁切换 IP 容易触发异地登录保护。

🆘 七、常见问题排查

🎯 总结

@openclaw/zalouser 插件为 OpenClaw 打开了越南最大社交平台 Zalo 的大门，使得构建 Zalo 客服机器人、私域流量助手成为可能。

核心口诀：

专用小号保平安，扫码登录最方便。 频率控制是关键，风控警报即刻停。

在享受自动化便利的同时，请始终对平台规则保持敬畏之心。