Zalo

状态：实验性。直接消息和群组聊天均已实现。下方的功能表格反映了在 Zalo Bot Creator / Marketplace 机器人上已验证的行为。

捆绑插件¶

Zalo 在当前 OpenClaw 发行版中作为捆绑插件提供，因此打包构建无需单独安装。

在较旧的构建版本或不包含 Zalo 的自定义安装中，请直接安装 npm 包：

• 安装：openclaw plugins install @openclaw/zalo
• 固定版本：openclaw plugins install @openclaw/zalo@<version>（仅用于可重现安装时固定版本）
• 从本地代码库安装：openclaw plugins install ./path/to/local/zalo-plugin
• 详情：插件

快速设置¶

1. 在 https://bot.zaloplatforms.com 创建机器人令牌（登录、创建机器人、配置设置）。令牌格式为 numeric_id:secret。对于 Marketplace 机器人，可用的运行时令牌可能出现在机器人的欢迎消息中。
2. 设置令牌，可以设置为环境变量 ZALO_BOT_TOKEN=...（仅限默认账户）或在配置中设置。
3. 运行 openclaw channels status --probe 进行检查；如果 Gateway 离线，请启动它。配置更改遵循热重载。如果你更改了服务环境，请重启 Gateway 以加载更改。
4. 在首次 DM 联系时批准配对码（默认 DM 策略为 pairing）。

最小配置：

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

多账户：在 channels.zalo.accounts.<id> 下添加更多条目，每个条目拥有自己的 botToken/name。channels.zalo.botToken（扁平结构，不含 accounts）是旧版单账户简写。新配置建议使用 accounts.<id>.*。

这是什么¶

Zalo 是一款面向越南市场的消息应用。其 Bot API 允许 Gateway 为 1:1 对话和群组聊天运行机器人。回传至 Zalo 的路由是确定性的。模型永远不会选择渠道。

本页面介绍 Zalo Bot Creator / Marketplace 机器人。Zalo 官方账号（OA）机器人是另一种产品形态，行为可能有所不同。本页面不涵盖它们。

工作原理¶

• 入站消息会被规范化为带有媒体占位符的共享渠道信封。
• 回复始终路由回同一个 Zalo 聊天。不使用引用回复（replyToMode 固定为关闭）。
• 默认使用长轮询（getUpdates）。可通过 channels.zalo.webhookUrl 使用 Webhook 模式。
• 群组需要 @提及 才能触发机器人。此行为无法按渠道配置。

限制¶

访问控制¶

直接消息¶

• channels.zalo.dmPolicy：pairing（默认）| allowlist | open | disabled。
• 配对：未知发送者会获得配对码。消息在获得批准前会被忽略。配对码 1 小时后过期。
• openclaw pairing list zalo
• openclaw pairing approve zalo <CODE>
• 详情：配对
• channels.zalo.allowFrom 接受数字形式的 Zalo 用户 ID（不支持用户名查找）。open 需要 "*"。

群组¶

群组聊天受插件支持（chatTypes: ["direct", "group"]），并通过提及和群组策略进行控制：

• channels.zalo.groupPolicy：open | allowlist | disabled。
• channels.zalo.groupAllowFrom 限制哪些发送者 ID 可以在群组中触发机器人。未设置时回退到 allowFrom。
• 默认解析规则：当配置了 channels.zalo 时，未设置的 groupPolicy 解析为 open。当 channels.zalo 完全缺失时，运行时以失败关闭（fail closed）的方式回退到 allowlist。
• 实际使用中报告的注意事项：在某些 Marketplace 机器人配置中，机器人根本无法被添加到群组。如果遇到这种情况，请通过你的机器人的 Zalo Bot 平台设置进行确认。这是平台侧的限制，而非 OpenClaw 策略。

长轮询与 Webhook¶

• 默认：长轮询（无需公网 URL）。
• Webhook 模式：设置 channels.zalo.webhookUrl 和 channels.zalo.webhookSecret。
• Webhook URL 必须使用 HTTPS。
• Webhook 密钥长度必须为 8-256 个字符。
• Zalo 通过 X-Bot-Api-Secret-Token 标头发送事件，并使用恒定时间比较进行校验。
• Gateway HTTP 在 channels.zalo.webhookPath 处处理 Webhook 请求（默认为 Webhook URL 的路径）。
• 请求必须使用 Content-Type: application/json（或 +json 媒体类型）。
• OpenClaw 仅在持久化存储原始事件后才返回 HTTP 200。存储失败时返回 HTTP 500。持久化的 200 响应携带 x-openclaw-delivery-accepted: durable 标头。反向代理可以要求该标头，以区分 OpenClaw 的接受与普通的 200 响应。身份验证、验证和存储错误的响应不包含该标头。
• 根据 Zalo API 文档，getUpdates 轮询和 Webhook 是互斥的。

支持的消息类型¶

• 文本：完全支持，按 2000 个字符分块。
• 媒体：入站/出站，受 mediaMaxMb 限制。
• 照片说明：截断以符合 2000 字符限制，包括轮询回复。
• 表情回应、话题、投票、原生命令：插件不支持。
• 流式传输：插件声明了分块流式传输能力。与某些其他区域渠道不同，Zalo 没有专门的出站队列/文本合并调优参数。如果这对你的用例很重要，请在你的环境中验证当前行为。

功能¶

投递目标（CLI/cron）¶

使用聊天 ID 作为目标：

openclaw message send --channel zalo --target 123456789 --message "hi"

故障排除¶

机器人无响应：

• 检查 token：openclaw channels status --probe
• 验证发送者已获批准（配对或 allowFrom）
• 检查网关日志：openclaw logs --follow

Webhook 未接收事件：

• 确认 Webhook URL 使用 HTTPS
• 确认密钥为 8-256 个字符
• 确认网关 HTTP 端点在配置的路径上可访问
• 确认 getUpdates 轮询未同时运行（二者互斥）
• 请求突发可能返回 HTTP 429（每个路径+IP 为 120 次请求 / 60 秒）。退避并重试

配置参考¶

完整配置：配置

channels.zalo.botToken、channels.zalo.dmPolicy 以及其他扁平顶层键是上述字段的旧版单账户简写。两种形式均受支持。

环境变量选项：ZALO_BOT_TOKEN=... 仅解析默认账户的 token。

相关¶

• 频道概览 - 所有支持的频道
• 配对 - DM 身份验证和配对流程
• 群组 - 群聊行为和提及门控
• 频道路由 - 消息的会话路由
• 安全 - 访问模型和加固