Zalo（Bot API）

状态：实验性。支持私信；群组处理可通过显式群组策略控制。

需要安装插件

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

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

快速开始

安装 Zalo 插件：
- 从源码安装：openclaw plugins install ./extensions/zalo
- 从 npm 安装（如已发布）：openclaw plugins install @openclaw/zalo
- 或在引导中选择 Zalo 并确认安装提示
设置令牌：
- 环境变量：ZALO_BOT_TOKEN=...
- 或配置：channels.zalo.botToken: "..."。
重启 Gateway（或完成引导）。
私信默认使用配对模式；首次联系时审批配对码。

最小配置：

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

简介

Zalo 是越南流行的即时通讯应用；其 Bot API 让 Gateway 可以运行一个机器人处理一对一对话。适合需要将回复确定性路由回 Zalo 的客服或通知场景。

Gateway 管理的 Zalo Bot API 频道。
确定性路由：回复始终返回 Zalo；模型不会自行选择频道。
私信共享代理的主会话。
支持群组策略控制（groupPolicy + groupAllowFrom），默认为关闭式白名单行为。

设置（快速路径）

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

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

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

示例：

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

环境变量选项：ZALO_BOT_TOKEN=...（仅对默认账户生效）。

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

重启 Gateway。当令牌被解析（环境变量或配置）时 Zalo 即启动。
私信默认使用配对模式。机器人首次被联系时审批配对码。

工作原理

入站消息被标准化为共享频道信封，带媒体占位符。
回复始终路由回同一个 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>
配对是默认的令牌交换机制。详情：配对
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 头的事件用于验证。
- Gateway HTTP 在 channels.zalo.webhookPath（默认为 webhook URL 路径）处理 webhook 请求。
- 请求须使用 Content-Type: application/json（或 +json 媒体类型）。
- 重复事件（event_name + message_id）在短暂的重放窗口内被忽略。
- 突发流量按路径/来源限速，可能返回 HTTP 429。

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

支持的消息类型

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

功能支持

功能	状态
私信	✅ 已支持
群组	⚠️ 支持策略控制（默认白名单）
媒体（图片）	✅ 已支持
表情回应	不支持
线程	不支持
投票	不支持
原生命令	不支持
流式传输	⚠️ 已阻止（2000 字符限制）

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

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

故障排查

机器人不响应：

检查令牌是否有效：openclaw channels status --probe
确认发送者已审批（配对或 allowFrom）
检查 Gateway 日志：openclaw logs --follow

Webhook 未接收事件：

确保 webhook URL 使用 HTTPS
确认密钥令牌为 8-256 个字符
确认 Gateway 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 密钥（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>.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。