Zalo 个人版 - 个人账号接入

除了 Zalo Official Account（OA）集成外，OpenClaw 还支持通过个人 Zalo 账号直接接入。此方式使用 Cookie-based Session（基于 Cookie 的会话）认证，适合个人用途和快速测试。

前置要求

• 一个 Zalo 个人账号
• 可登录 Zalo Web 的浏览器
• OpenClaw Gateway（网关）已安装并运行

安装插件

openclaw plugins install @openclaw/zalouser

OA 版 vs 个人版

特性	Zalo OA	Zalo 个人版
认证方式	OAuth API Token	Cookie Session
消息限制	按 OA 等级	较高（个人账号限制）
需要 OA	✅ 是	❌ 否
稳定性	高（官方 API）	中等（Cookie 可能过期）
群聊支持	有限	完全支持
适用场景	企业/商业	个人/测试

非官方集成

个人版集成基于 Web Cookie，不使用 Zalo 官方 API。Cookie 可能因会话超时、密码变更或 Zalo 安全策略更新而失效。

接入步骤

第一步：获取 Cookie

1. 使用浏览器登录 Zalo Web
2. 打开 Developer Tools（开发者工具，F12）
3. 切换到 Application > Cookies 标签
4. 找到 chat.zalo.me 域下的所有 Cookie
5. 复制完整的 Cookie 字符串

Chrome / Edge

# Developer Tools > Application > Cookies > chat.zalo.me
# 右键 > Copy all cookies 或手动拼接

使用扩展

# 安装 "Cookie Editor" 等浏览器扩展
# 导出 chat.zalo.me 的完整 Cookie

安全提示

Cookie 等同于你的 Zalo 登录凭证，请勿泄露或分享。建议使用专用的 Zalo 账号，不要使用日常使用的主账号。

第二步：配置 OpenClaw

{
  channels: {
    zalouser: {
      enabled: true,
      cookie: "YOUR_COOKIE_STRING",         // 完整的 Cookie 字符串
      dmPolicy: "pairing"                   // DM Policy（私信策略）
    }
  }
}

也可以通过 Environment Variable（环境变量）设置：

export ZALO_USER_COOKIE="your-cookie-string"

第三步：重启 Gateway 并配对

openclaw gateway restart

使用另一个 Zalo 账号向 Bot 账号发送消息，获取 Pairing Code（配对码）后批准：

openclaw pairing approve zalouser <pairing-code>

Session 持久化

Cookie Session 可能过期，OpenClaw 支持自动持久化和续期：

{
  channels: {
    zalouser: {
      session: {
        persistPath: "~/.openclaw/zalo-session.json",   // Session 存储路径
        autoRefresh: true,                                // 自动刷新 Session
        refreshInterval: 3600000                          // 刷新间隔（毫秒，1小时）
      }
    }
  }
}

Session 过期

如果 Session 过期，Gateway 日志中会出现认证错误。此时需要重新从浏览器获取 Cookie 并更新配置。

群聊支持

个人版支持 Zalo 群聊（Group Chat）：

{
  channels: {
    zalouser: {
      groups: {
        allowAll: false,
        allowGroups: ["group-id-xxx"],       // 允许的群聊 ID
        requireMention: true                  // 需要 @ 机器人
      }
    }
  }
}

DM Policy（私信策略）

策略	说明
pairing	用户需先获取 Pairing Code（配对码）验证
allowlist	仅允许指定 Zalo 用户私聊
open	所有好友均可私聊（谨慎使用）

与 OA 版的选择建议

• 商业用途：推荐使用 Zalo OA，API 更稳定、功能更完整
• 个人测试：个人版足够使用，设置更简单
• 群聊需求：个人版对群聊支持更好

常见问题

Cookie 频繁失效

1. 确认浏览器中 Zalo Web 保持登录状态（不要登出）
2. 启用 autoRefresh 自动续期
3. 避免在多个设备上同时登录同一账号

消息收发异常

1. 检查 Cookie 是否完整（包含所有必要字段）
2. 确认 Zalo Web 版本未更新导致 Cookie 格式变化
3. 查看 Gateway 日志中的详细错误信息

账号被限制

1. 避免短时间内发送大量消息
2. Zalo 可能对异常行为的账号进行限制
3. 如被限制，等待 24 小时后重试

🇨🇳 中国用户须知

同 Zalo OA 版，Zalo 个人版主要面向越南和东南亚市场。

网络访问：Zalo Web 在中国大陆可访问，但速度可能不稳定。建议 Gateway 部署在东南亚区域。

注册要求：Zalo 个人账号注册需要越南手机号（+84）。

适用场景：个人跨境沟通、越南市场快速测试、小规模自动化需求。如需正式商业用途，请使用 Zalo OA 方案。