Zalo（Bot API�?

状态：实验性。支持私聊；群组处理可通过明确的群组策略控制获得�?

需要插�?

Zalo 作为插件提供，不随核心安装一起打包�?

  • 通过 CLI 安装：openclaw plugins install @openclaw/zalo
  • 或在入职期间选择 Zalo 并确认安装提�?
  • 详情：Plugins

快速设置（入门�?

  1. 安装 Zalo 插件�?
    • 从源代码检出：openclaw plugins install ./extensions/zalo
    • �?npm（如已发布）：openclaw plugins install @openclaw/zalo
    • 或在入职期间选择 Zalo 并确认安装提�?
  2. 设置令牌�?
    • 环境变量：ZALO_BOT_TOKEN=...
    • 或配置：channels.zalo.botToken: "..."�?
  3. 重启网关（或完成入职）�?
  4. 私聊访问默认是配对；在首次联系时批准配对代码�?

最小配置：

{
  channels: {
    zalo: {
      enabled: true,
      botToken: "12345689:abc-xyz",
      dmPolicy: "pairing",
    },
  },
}

它是什�?

Zalo 是一款面向越南的消息应用；其 Bot API 让网关可以运行用于一对一对话的机器人�? 它非常适合支持或通知场景，在这些场景中你希望确定性路由回�?Zalo�?

  • 网关拥有�?Zalo Bot API 频道�?
  • 确定性路由：回复返回 Zalo；模型从不选择频道�?
  • 私聊共享智能体的主会话�?
  • 群组通过策略控制（groupPolicy + groupAllowFrom）支持，默认失败关闭的允许列表行为�?

设置（快速路径）

1) 创建机器人令牌（Zalo Bot Platform�?

  1. 转到 https://bot.zaloplatforms.com 并登录�?
  2. 创建一个新机器人并配置其设置�?
  3. 复制机器人令牌（格式：12345689:abc-xyz）�?

2) 配置令牌（环境变量或配置�?

示例�?

{
  channels: {
    zalo: {
      enabled: true,
      botToken: "12345689:abc-xyz",
      dmPolicy: "pairing",
    },
  },
}

环境变量选项：ZALO_BOT_TOKEN=...（仅适用于默认账户）�?

多账户支持：使用 channels.zalo.accounts 为每个账户提供令牌和可选名称�?

  1. 重启网关。Zalo 在解析令牌（环境变量或配置）时启动�?
  2. 私聊访问默认为配对。机器人在首次联系时批准代码�?

工作原理（行为）

  • 入站消息规范化为共享频道信封，带有媒体占位符�?
  • 回复始终路由回相同的 Zalo 聊天�?
  • 默认长轮询；Webhook 模式可通过 channels.zalo.webhookUrl 启用�?

限制

  • 出站文本分块�?2000 个字符（Zalo API 限制）�?
  • 媒体下载/上传�?channels.zalo.mediaMaxMb 限制（默�?5）�?
  • 由于 2000 字符限制使流式传输不太有用，默认阻止流式传输�?

访问控制（私聊）

私聊访问

  • 默认：channels.zalo.dmPolicy = "pairing"。未知发送者收到配对代码；消息被忽略直到被批准（代�?1 小时后过期）�?
  • 通过以下方式批准�?
    • openclaw pairing list zalo
    • openclaw pairing approve zalo <CODE>
  • 配对是默认的令牌交换。详情：Pairing
  • channels.zalo.allowFrom 接受数字用户 ID（无用户名查找）�?

访问控制（群组）

  • channels.zalo.groupPolicy 控制群组入站处理：open | allowlist | disabled�?
  • 默认行为是失败关闭：allowlist�?
  • channels.zalo.groupAllowFrom 限制哪些发送�?ID 可以在群组中触发机器人�?
  • 如果 groupAllowFrom 未设置，Zalo 回退�?allowFrom 进行发送者检查�?
  • groupPolicy: "disabled" 阻止所有群组消息�?
  • groupPolicy: "open" 允许任何群组成员（提及门控）�?
  • 运行时注意：如果完全缺少 channels.zalo，运行时仍然回退�?groupPolicy="allowlist" 以确保安全�?

长轮�?vs webhook

  • 默认：长轮询（无需公共 URL）�?
  • Webhook 模式：设�?channels.zalo.webhookUrl �?channels.zalo.webhookSecret�?
    • Webhook 密钥必须�?8-256 个字符�?
    • Webhook URL 必须使用 HTTPS�?
    • Zalo 发送带�?X-Bot-Api-Secret-Token 标头的事件进行验证�?
    • 网关 HTTP �?channels.zalo.webhookPath 处理 webhook 请求（默认为 webhook URL 路径）�?
    • 请求必须使用 Content-Type: application/json（或 +json 媒体类型）�?
    • 重复事件（event_name + message_id）在短回放窗口中被忽略�?
    • 突发流量按路�?源速率限制，可能返�?HTTP 429�?

*注意�? 根据 Zalo API 文档，getUpdates（轮询）�?webhook 是互斥的�?

支持的消息类�?

  • 文本消息：完全支持，2000 字符分块�?
  • 图片消息：下载和处理入站图片；通过 sendPhoto 发送图片�?
  • 贴纸：记录但未完全处理（无智能体回复）�?
  • 不支持的类型：记录（例如来自受保护用户的消息）�?

功能

功能状�?
私聊�?支持
群组⚠️ 支持但需策略控制（默认允许列表）
媒体（图片）�?支持
反应�?不支�?
主题�?不支�?
投票�?不支�?
原生命令�?不支�?
流式传输⚠️ 阻止�?000 字符限制�?

传递目标（CLI/cron�?

  • 使用聊天 ID 作为目标�?
  • 示例：openclaw message send --channel zalo --target 123456789 --message "hi"�?

故障排除

*机器人不回复�?

  • 检查令牌是否有效：openclaw channels status --probe
  • 验证发送者已批准（配对或 allowFrom�?
  • 检查网关日志：openclaw logs --follow

Webhook 不接收事件：

  • 确保 webhook URL 使用 HTTPS
  • 验证密钥令牌�?8-256 个字�?
  • 确认网关 HTTP 端点在配置的路径上可访问
  • 检�?getUpdates 轮询未运行（它们是互斥的�?

配置参考（Zalo�?

完整配置：配置

提供商选项�?

  • channels.zalo.enabled：启�?禁用频道启动�?
  • channels.zalo.botToken：来�?Zalo Bot Platform 的机器人令牌�?
  • channels.zalo.tokenFile：从文件路径读取令牌�?
  • channels.zalo.dmPolicy：pairing | allowlist | open | disabled（默认：pairing）�?
  • channels.zalo.allowFrom：私聊允许列表（用户 ID）。open 需�?"*"。向导会询问数字 ID�?
  • channels.zalo.groupPolicy：open | allowlist | disabled（默认：allowlist）�?
  • channels.zalo.groupAllowFrom：群组发送者允许列表（用户 ID）。未设置时回退�?allowFrom�?
  • channels.zalo.mediaMaxMb：入�?出站媒体上限（MB，默�?5）�?
  • channels.zalo.webhookUrl：启�?webhook 模式（需�?HTTPS）�?
  • channels.zalo.webhookSecret：webhook 密钥�?-256 个字符）�?
  • channels.zalo.webhookPath：网�?HTTP 服务器上�?webhook 路径�?
  • channels.zalo.proxy：API 请求的代�?URL�?

多账户选项�?

  • channels.zalo.accounts.<id>.botToken：每个账户的令牌�?
  • channels.zalo.accounts.<id>.tokenFile：每个账户的令牌文件�?
  • channels.zalo.accounts.<id>.name：显示名称�?
  • channels.zalo.accounts.<id>.enabled：启�?禁用账户�?
  • channels.zalo.accounts.<id>.dmPolicy：每个账户的私聊策略�?
  • channels.zalo.accounts.<id>.allowFrom：每个账户的允许列表�?
  • channels.zalo.accounts.<id>.groupPolicy：每个账户的群组策略�?
  • channels.zalo.accounts.<id>.groupAllowFrom：每个账户的群组发送者允许列表�?
  • channels.zalo.accounts.<id>.webhookUrl：每个账户的 webhook URL�?
  • channels.zalo.accounts.<id>.webhookSecret：每个账户的 webhook 密钥�?
  • channels.zalo.accounts.<id>.webhookPath：每个账户的 webhook 路径�?
  • channels.zalo.accounts.<id>.proxy：每个账户的代理 URL�?