Zalo（Bot API）

适用范围

当你需要：

• 处理 Zalo 功能或 webhooks

状态：实验性。仅支持直接消息；群组功能即将推出（根据 Zalo 文档）。

需要插件

Zalo 以插件形式提供，不随核心安装一起打包。

• 通过 CLI 安装：clawdbot plugins install @clawdbot/zalo
• 或在初始化期间选择 Zalo 并确认安装提示
• 详情：/docs/plugin/

快速配置（入门）

1. 安装 Zalo 插件：
   • 从源码检出：clawdbot plugins install ./extensions/zalo
   • 从 npm（如已发布）：clawdbot plugins install @clawdbot/zalo
   • 或在初始化时选择 Zalo 并确认安装提示
2. 设置 token：
   • 环境变量：ZALO_BOT_TOKEN=...
   • 或配置：channels.zalo.botToken: "..."。
3. 重启网关（或完成初始化）。
4. DM 访问默认为 pairing；首次联系时批准配对码。

最小配置：

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

它是什么

Zalo 是一个面向越南的即时通讯应用；其 Bot API 让网关可以为 1:1 对话运行 bot。 它适合用于支持或通知场景，希望确定性地路由回 Zalo。

• 由网关拥有的 Zalo Bot API 渠道。
• 确定性路由：回复回到 Zalo；模型从不选择渠道。
• DMs 与智能体的主会话共享。
• 群组尚不支持（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. 重启网关。Zalo 在解析到 token 时启动（环境变量或配置）。
4. DM 访问默认为 pairing。当 bot 首次被联系时批准配对码。

工作原理（行为）

• 入站消息被规范化为共享渠道信封，带有媒体占位符。
• 回复总是路由回同一个 Zalo 聊天。
• 默认使用长轮询；通过 channels.zalo.webhookUrl 可用 webhook 模式。

限制

• 出站文本被分块为 2000 个字符（Zalo API 限制）。
• 媒体下载/上传上限为 channels.zalo.mediaMaxMb（默认 5）。
• 由于 2000 字符限制，流式传输默认被阻止。

访问控制（DMs）

DM 访问

• 默认：channels.zalo.dmPolicy = "pairing"。未知发送者收到配对码；在批准前消息被忽略（配对码 1 小时后过期）。
• 通过以下方式批准：
  • clawdbot pairing list zalo
  • clawdbot pairing approve zalo <CODE>
• Pairing 是默认的 token 交换。详情：/docs/start/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 标头的事件用于验证。
  • 网关 HTTP 在 channels.zalo.webhookPath（默认为 webhook URL 路径）处理 webhook 请求。

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

支持的消息类型

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

功能

传递目标（CLI/cron）

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

故障排除

Bot 不响应：

• 检查 token 是否有效：clawdbot channels status --probe
• 验证发送者是否已批准（pairing 或 allowFrom）
• 检查网关日志：clawdbot logs --follow

Webhook 未接收事件：

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

配置参考（Zalo）

完整配置：/docs/gateway/configuration/

Provider 选项：

• channels.zalo.enabled：启用/禁用渠道启动。
• 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：网关 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。