8.14 Zalo集成 - OpenClaw中文社区

通过官方 Zalo Bot API 集成企业机器人功能。

概述

Zalo 集成通过 @openclaw/zalo 插件提供支持,使用官方 Zalo Bot API (也称为 Zalo OA - Official Account)。这是面向企业的官方机器人解决方案，适用于客户服务、营销和自动化场景。

状态

实验性功能，由插件提供。基于官方 API。

重要区别

Zalo vs Zalo Personal:

zalo: 官方 Bot API（本页面），用于企业机器人，需要 Zalo OA 账号
zalouser: 个人账号自动化（非官方），使用 zca-cli 工具

前置要求

Zalo Official Account (OA): 需要注册企业官方账号
Bot Token: 从 Zalo OA 平台获取
企业认证（某些功能可能需要）

创建 Zalo Official Account

1. 注册 OA

访问 Zalo OA 平台
使用 Zalo 账号登录
创建新的 Official Account
完成企业信息认证

2. 获取 Bot Token

在 OA 管理后台进入 "开发者工具"
找到 "Bot API" 或 "应用配置" 部分
生成或复制 Bot Token
妥善保管令牌

安装插件

openclaw plugins install @openclaw/zalo

OpenClaw 配置

基础配置

{
  channels: {
    zalo: {
      enabled: true,
      botToken: process.env.ZALO_BOT_TOKEN
    }
  }
}

环境变量

export ZALO_BOT_TOKEN="your-bot-token-here"

直接消息支持

DM 会话管理

Zalo Bot API 的直接消息与代理的主会话共享：

{
  channels: {
    zalo: {
      enabled: true,
      botToken: process.env.ZALO_BOT_TOKEN,
      dmPolicy: "pairing"  // 推荐：需要配对审批
    }
  }
}

会话共享

Zalo 的 DM 消息会与代理的主会话合并，不同于其他通道的隔离会话模式。

配对审批

当用户首次发送消息时：

# 查看待审批的配对请求
openclaw pairing list

# 批准用户（使用 Zalo 用户 ID）
openclaw pairing approve zalo:user_id_123

# 撤销配对
openclaw pairing revoke zalo:user_id_123

访问控制

DM 策略选项

dmPolicy 可选值：

"pairing"（推荐）：需要手动审批
"allowlist"：仅允许指定用户
"open"：接受所有消息
"disabled"：禁用直接消息

允许列表配置

{
  channels: {
    zalo: {
      enabled: true,
      botToken: process.env.ZALO_BOT_TOKEN,
      dmPolicy: "allowlist",
      allowFrom: [
        "zalo_user_id_1",
        "zalo_user_id_2"
      ]
    }
  }
}

Webhook 配置

Webhook 模式（推荐）

使用 webhook 接收实时消息更新：

{
  channels: {
    zalo: {
      enabled: true,
      botToken: process.env.ZALO_BOT_TOKEN,
      mode: "webhook",
      webhookUrl: "https://your-domain.com/zalo/webhook",
      webhookSecret: process.env.ZALO_WEBHOOK_SECRET,  // 8-256字符
      webhookPath: "/zalo/webhook",  // 默认路径
      webhookPort: 3000              // OpenClaw 网关端口
    }
  }
}

Webhook Secret 要求

Webhook secret 必须满足：

长度：8-256 字符
建议使用强随机字符串

# 生成安全的 secret
openssl rand -base64 32

# 设置环境变量
export ZALO_WEBHOOK_SECRET="your-generated-secret"

配置 Zalo OA Webhook

在 Zalo OA 管理后台进入 "Webhook 设置"
设置 Webhook URL: https://your-domain.com/zalo/webhook
输入 Secret（与 OpenClaw 配置中的一致）
启用需要的事件类型（消息、关注等）
保存并测试连接

HTTPS 要求

Zalo Webhook 要求使用 HTTPS。本地开发可使用 ngrok 等隧道工具。

Polling 模式（备选）

如果无法使用 webhook，可以使用轮询模式：

{
  channels: {
    zalo: {
      enabled: true,
      botToken: process.env.ZALO_BOT_TOKEN,
      mode: "polling",
      pollingInterval: 3000  // 毫秒
    }
  }
}

消息功能

支持的消息类型

✅ 文本消息
✅ 图片
✅ 文件
✅ 模板消息（需要预先配置）
⚠️ 受 Zalo OA 政策限制

消息限制

{
  channels: {
    zalo: {
      enabled: true,
      botToken: process.env.ZALO_BOT_TOKEN,
      textChunkLimit: 2000,  // 单条消息最大字符
      rateLimitPerMinute: 60 // 每分钟消息限制
    }
  }
}

多账号配置

同时管理多个 Zalo OA：

{
  channels: {
    zalo: {
      accounts: {
        customer_service: {
          enabled: true,
          botToken: process.env.ZALO_BOT_TOKEN_CS,
          dmPolicy: "open"
        },
        marketing: {
          enabled: true,
          botToken: process.env.ZALO_BOT_TOKEN_MKT,
          dmPolicy: "allowlist",
          allowFrom: ["subscriber_1", "subscriber_2"]
        }
      }
    }
  }
}

本地开发（使用 ngrok）

1. 安装 ngrok

# macOS
brew install ngrok

# 或访问: https://ngrok.com/download

2. 启动隧道

# 假设 OpenClaw 在 3000 端口运行
ngrok http 3000

3. 配置 Webhook URL

使用 ngrok 生成的 HTTPS URL：

https://xxxx-xx-xx-xxx-xxx.ngrok-free.app/zalo/webhook

在 Zalo OA 后台和 OpenClaw 配置中更新此 URL。

注意

免费版 ngrok URL 每次重启会变化。生产环境应使用固定域名和 SSL 证书。

故障排查

机器人无法连接

验证 ZALO_BOT_TOKEN 正确
确认 OA 状态正常（未被暂停）
检查 OpenClaw 网关运行状态

Webhook 验证失败

确认 Webhook URL 使用 HTTPS
验证 webhookSecret 与 Zalo OA 后台一致
检查 Secret 长度在 8-256 字符之间
确认端口和路径正确

消息未接收

检查 Webhook 事件订阅是否启用
验证用户是否已关注 OA
查看 OpenClaw 日志：openclaw logs --follow
测试 Webhook 连接性

无法发送消息

确认用户在 24 小时互动窗口内（Zalo 政策限制）
检查 OA 是否有发送消息权限
验证消息格式符合 API 要求
检查是否超出速率限制

配对不工作

确认 dmPolicy 设置为 "pairing"
检查用户 ID 格式正确
查看待审批列表：openclaw pairing list

Zalo OA 限制和政策

消息窗口限制

用户互动后 24 小时内可主动发送消息
超出窗口需使用模板消息（需审批）
不同 OA 类型有不同限制

内容政策

遵守 Zalo 社区准则
禁止垃圾信息和骚扰
某些行业需要特殊认证

速率限制

每分钟请求数限制（具体取决于 OA 等级）
建议实现重试机制
监控 API 响应状态码

安全最佳实践

安全建议

使用环境变量存储 Bot Token，不要硬编码
使用强随机 Webhook Secret（至少 32 字符）
启用 HTTPS 和有效 SSL 证书
使用 pairing 或 allowlist DM 策略
定期轮换 Bot Token
监控异常访问和速率限制
限制 OA 权限到最小必需范围

完整配置示例

{
  channels: {
    zalo: {
      enabled: true,
      botToken: process.env.ZALO_BOT_TOKEN,
      
      // Webhook 配置
      mode: "webhook",
      webhookUrl: "https://bot.example.com/zalo/webhook",
      webhookSecret: process.env.ZALO_WEBHOOK_SECRET,
      webhookPath: "/zalo/webhook",
      webhookPort: 3000,
      
      // 访问控制
      dmPolicy: "pairing",
      
      // 消息限制
      textChunkLimit: 2000,
      rateLimitPerMinute: 60,
      
      // 重试配置
      retry: {
        maxAttempts: 3,
        backoff: "exponential"
      }
    }
  }
}

与 Zalo Personal 的区别

特性	Zalo (官方 Bot API)	Zalo Personal (非官方)
官方支持	✅ 官方 API	❌ 非官方工具
账号类型	Official Account (OA)	个人账号
账号风险	✅ 安全合规	⚠️ 可能被封禁
企业认证	✅ 需要	❌ 不需要
功能稳定性	✅ 稳定	⚠️ 可能随时失效
适用场景	企业客服、营销	个人使用、测试

提示

更多详细信息和 API 参考，请访问官方文档和 Zalo 开发者中心。