Zalo 个人版插件

Zalo User Plugin（Zalo 个人版插件）允许 OpenClaw Agent 通过个人 Zalo 账号与用户进行消息交互。这是一种非官方 API 的接入方式，适用于轻量级场景。

与 Zalo OA 插件的区别

特性	Zalo User（个人版）	Zalo OA（官方账号版）
认证方式	Cookie 登录	OAuth 2.0
API 类型	非官方	官方 API
消息限制	无官方限制	受 API 配额限制
稳定性	中等，可能受 Zalo 更新影响	高，官方支持
适用场景	个人使用、测试	企业正式部署
好友限制	仅能与好友通信	关注者均可通信

稳定性提示

Zalo 个人版插件依赖非官方接口，Zalo 平台更新可能导致功能失效。生产环境建议使用 Zalo OA 插件。

安装

openclaw plugins install @openclaw/zalouser

配置

获取 Cookie

1. 在浏览器中登录 chat.zalo.me
2. 打开浏览器开发者工具（F12）
3. 进入 Application → Cookies → chat.zalo.me
4. 复制所需的 Cookie 值

配置文件

plugins:
  - name: '@openclaw/zalouser'
    enabled: true
    config:
      # Cookie 认证信息
      cookies:
        zpw_sek: 'YOUR_ZPW_SEK_VALUE'
        zpw_sekey: 'YOUR_ZPW_SEKEY_VALUE'
        zpsid: 'YOUR_ZPSID_VALUE'

      # 可选配置
      options:
        selfListen: false       # 是否监听自己发送的消息
        reconnectDelay: 5000    # 重连延迟（毫秒）
        maxRetries: 10          # 最大重试次数
        typingIndicator: true   # 显示输入状态

Cookie 安全

Cookie 等同于账号密码，请妥善保管。建议使用环境变量存储：

cookies:
  zpw_sek: ${ZALO_ZPW_SEK}
  zpw_sekey: ${ZALO_ZPW_SEKEY}
  zpsid: ${ZALO_ZPSID}

功能特性

支持的功能

• ✅ 接收和发送文本消息
• ✅ 接收和发送图片
• ✅ 接收和发送文件
• ✅ 群组消息（Group Chat）
• ✅ 输入状态指示
• ✅ 已读回执
• ✅ 消息撤回通知

不支持的功能

• ❌ 语音消息
• ❌ 视频通话
• ❌ 小程序（Mini App）
• ❌ 朋友圈（Moments）

使用示例

Agent 通过 Zalo 个人号与用户通信的完整配置：

# openclaw.config.yaml
agents:
  - name: zalo-assistant
    model: gpt-4o
    channels:
      - type: zalouser
        config:
          cookies:
            zpw_sek: ${ZALO_ZPW_SEK}
            zpw_sekey: ${ZALO_ZPW_SEKEY}

plugins:
  - name: '@openclaw/zalouser'
    enabled: true

事件处理

// 监听 Zalo 特有事件
gateway.on('zalouser:friend_request', (event) => {
  console.log(`收到好友请求: ${event.fromName}`)
})

gateway.on('zalouser:message_recall', (event) => {
  console.log(`消息被撤回: ${event.messageId}`)
})

故障排查

问题	原因	解决方案
Cookie 失效	Zalo 登录过期	重新获取 Cookie 并更新配置
无法接收消息	WebSocket 连接断开	检查网络并重启网关
发送频率受限	Zalo 反垃圾机制	降低发送频率，添加随机延迟
账号被封禁	异常操作被检测	更换账号，减少自动化行为频率

保持 Cookie 有效

定期（每 1-2 周）刷新 Cookie，或使用自动化脚本维持登录状态。