Zalo (Bot API)

状态：实验性功能。目前仅支持私信，群组功能即将推出（根据 Zalo 官方文档）。

需要安装 Plugin

Zalo 以 Plugin 形式提供，不包含在核心安装包中。

• 通过 CLI 安装：openclaw plugins install @openclaw/zalo
• 或者在引导过程中选择 Zalo 并确认安装提示
• 详情：Plugins

快速设置（新手向）

1. 安装 Zalo Plugin：
   • 从源码安装：openclaw plugins install ./extensions/zalo
   • 从 npm 安装（如果已发布）：openclaw plugins install @openclaw/zalo
   • 或者在引导过程中选择 Zalo 并确认安装提示
2. 设置 token：
   • 环境变量：ZALO_BOT_TOKEN=...
   • 或配置文件：channels.zalo.botToken: "..."
3. 重启 Gateway（或完成引导流程）。
4. DM 访问默认使用 Pairing 模式；首次联系时需要批准配对码。

最小配置示例：

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

这是什么

Zalo 是一款面向越南市场的即时通讯应用；它的 Bot API 让 Gateway 可以运行一个用于 1 对 1 对话的机器人。 适合用于客服支持或通知场景，消息会确定性地路由回 Zalo。

• 一个由 Gateway 管理的 Zalo Bot API Channel。
• 确定性 Routing：回复会返回到 Zalo；模型不会选择 Channel。
• DM 共享 Agent 的主 Session。
• 暂不支持群组（Zalo 官方文档表示”即将推出”）。

设置（快速通道）

1) 创建 bot token（Zalo Bot Platform）

1. 访问 https://bot.zaloplatforms.com 并登录。
2. 创建一个新的 bot 并配置其设置。
3. 复制 bot token（格式：12345689:abc-xyz）。

2) 配置 token（环境变量或配置文件）

示例：

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

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

多账户支持：使用 channels.zalo.accounts，为每个账户配置 token 和可选的 name。

3. 重启 Gateway。当 token 被解析（环境变量或配置文件）时，Zalo 会自动启动。
4. DM 访问默认使用 Pairing 模式。当机器人首次被联系时，需要批准配对码。

工作原理（行为）

• 入站消息会被标准化为共享的 Channel 信封格式，包含媒体占位符。
• 回复总是路由回同一个 Zalo 聊天。
• 默认使用长轮询；可通过 channels.zalo.webhookUrl 启用 Webhook 模式。

限制

• 出站文本会被分块为 2000 字符（Zalo API 限制）。
• 媒体下载/上传受 channels.zalo.mediaMaxMb 限制（默认 5 MB）。
• Streaming 默认被禁用，因为 2000 字符限制使得流式传输不太实用。

访问控制（DM）

DM 访问

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

长轮询 vs Webhook

• 默认：长轮询（不需要公网 URL）。
• Webhook 模式：设置 channels.zalo.webhookUrl 和 channels.zalo.webhookSecret。
  • Webhook secret 必须是 8-256 个字符。
  • Webhook URL 必须使用 HTTPS。
  • Zalo 发送事件时会带上 X-Bot-Api-Secret-Token 请求头用于验证。
  • Gateway HTTP 在 channels.zalo.webhookPath 处理 Webhook 请求（默认为 Webhook URL 的路径）。

注意： getUpdates（轮询）和 Webhook 是互斥的（根据 Zalo API 文档）。

支持的消息类型

• 文本消息：完全支持，会分块为 2000 字符。
• 图片消息：下载和处理入站图片；通过 sendPhoto 发送图片。
• 贴纸：会记录但不完全处理（Agent 不会响应）。
• 不支持的类型：会记录（例如，来自受保护用户的消息）。

功能支持

投递目标（CLI/定时任务）

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

故障排除

机器人没有响应：

• 检查 token 是否有效：openclaw channels status --probe
• 验证发送者是否已批准（Pairing 或 allowFrom）
• 查看 Gateway 日志：openclaw logs --follow

Webhook 没有接收到事件：

• 确保 Webhook URL 使用 HTTPS
• 验证 secret token 是 8-256 个字符
• 确认 Gateway HTTP 端点在配置的路径上可访问
• 检查 getUpdates 轮询是否未运行（它们是互斥的）

配置参考（Zalo）

完整配置：Configuration

Provider 选项：

• channels.zalo.enabled：启用/禁用 Channel 启动。
• channels.zalo.botToken：来自 Zalo Bot Platform 的 bot token。
• channels.zalo.tokenFile：从文件路径读取 token。
• channels.zalo.dmPolicy：pairing | allowlist | open | disabled（默认：pairing）。
• channels.zalo.allowFrom：DM 白名单（用户 ID）。open 需要 "*"。向导会要求输入数字 ID。
• channels.zalo.mediaMaxMb：入站/出站媒体上限（MB，默认 5）。
• channels.zalo.webhookUrl：启用 Webhook 模式（需要 HTTPS）。
• channels.zalo.webhookSecret：Webhook secret（8-256 字符）。
• channels.zalo.webhookPath：Gateway HTTP 服务器上的 Webhook 路径。
• channels.zalo.proxy：API 请求的代理 URL。

多账户选项：

• channels.zalo.accounts.<id>.botToken：每个账户的 token。
• channels.zalo.accounts.<id>.tokenFile：每个账户的 token 文件。
• channels.zalo.accounts.<id>.name：显示名称。
• channels.zalo.accounts.<id>.enabled：启用/禁用账户。
• channels.zalo.accounts.<id>.dmPolicy：每个账户的 DM 策略。
• channels.zalo.accounts.<id>.allowFrom：每个账户的白名单。
• channels.zalo.accounts.<id>.webhookUrl：每个账户的 Webhook URL。
• channels.zalo.accounts.<id>.webhookSecret：每个账户的 Webhook secret。
• channels.zalo.accounts.<id>.webhookPath：每个账户的 Webhook 路径。
• channels.zalo.accounts.<id>.proxy：每个账户的代理 URL。