Zalo

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

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. 重启 Gateway（或完成引导）。
4. 私信访问默认需要配对；在首次联系时批准配对码。

最小配置：

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

Zalo 是一个以越南为中心的即时通讯应用；其 Bot API 允许 Gateway 运行一个机器人进行 1:1 对话。 它非常适合需要确定性路由回 Zalo 的支持或通知场景。

• 一个由 Gateway 拥有的 Zalo Bot API 通道。
• 确定性路由：回复总是返回到 Zalo；模型从不选择通道。
• 私信共享代理的主会话。
• 群组尚不支持（Zalo 文档称“即将推出”）。

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

示例：

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

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

多账户支持：使用 channels.zalo.accounts 进行每个账户的令牌配置和可选的 name。

3. 重启 Gateway。Zalo 会在令牌解析后启动（环境变量或配置）。
4. 私信访问默认为配对。当机器人首次被联系时批准代码。

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

• 出站文本分块限制为 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（无法查找用户名）。

• 默认：长轮询（无需公共 URL）。
• Webhook 模式：设置 channels.zalo.webhookUrl 和 channels.zalo.webhookSecret。
  • Webhook 密钥必须是 8-256 个字符。
  • Webhook URL 必须使用 HTTPS。
  • Zalo 发送带有 X-Bot-Api-Secret-Token 头的事件进行验证。
  • Gateway HTTP 在 channels.zalo.webhookPath 处理 webhook 请求（默认为 webhook URL 路径）。

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

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

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

机器人不响应：

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

Webhook 未收到事件：

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

完整配置：配置

提供商选项：

• 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.mediaMaxMb: 入站/出站媒体上限 (MB, 默认 5)。
• channels.zalo.webhookUrl: 启用 webhook 模式（需要 HTTPS）。
• channels.zalo.webhookSecret: webhook 密钥（8-256 字符）。
• channels.zalo.webhookPath: Gateway 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>.webhookUrl: 每个账户的 webhook URL。
• channels.zalo.accounts.<id>.webhookSecret: 每个账户的 webhook 密钥。
• channels.zalo.accounts.<id>.webhookPath: 每个账户的 webhook 路径。
• channels.zalo.accounts.<id>.proxy: 每个账户的代理 URL。