Zalo (Bot API)

状态:实验性。仅支持私聊;根据 Zalo 文档,群组功能即将推出。

需要插件

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: "..."。
重启网关(或完成初始化)。
私聊访问默认使用配对方式;首次联系时批准配对码。

最小配置:

json5

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

它是什么

Zalo 是一款专注于越南的消息应用;其 Bot API 允许网关运行用于 1:1 对话的机器人。它非常适合需要确定性路由回 Zalo 的支持或通知场景。

由网关拥有的 Zalo Bot API 频道。
确定性路由:回复返回到 Zalo;模型从不选择频道。
私聊共享代理的主会话。
暂不支持群组(Zalo 文档说明"即将推出")。

设置(快速路径)

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

访问 https://bot.zaloplatforms.com 并登录。
创建新机器人并配置其设置。
复制机器人令牌(格式:12345689:abc-xyz)。

2) 配置令牌(环境变量或配置)

示例:

json5

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

环境变量选项:ZALO_BOT_TOKEN=...(仅适用于默认账户)。

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

重启网关。当令牌被解析(环境变量或配置)时 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(无用户名查找功能)。

长轮询 vs webhook

默认:长轮询(无需公共 URL)。
Webhook 模式:设置 channels.zalo.webhookUrl 和 channels.zalo.webhookSecret。
- Webhook 密钥必须为 8-256 字符。
- Webhook URL 必须使用 HTTPS。
- Zalo 发送带有 X-Bot-Api-Secret-Token 标头的事件用于验证。
- 网关 HTTP 在 channels.zalo.webhookPath 处理 webhook 请求(默认为 webhook URL 路径)。

注意: 根据 Zalo API 文档,getUpdates(轮询)和 webhook 互斥。

支持的消息类型

文本消息:完全支持,2000 字符分块。
图片消息:下载和处理入站图片;通过 sendPhoto 发送图片。
贴纸:已记录但未完全处理(无代理响应)。
不支持的类型:已记录(例如,来自受保护用户的消息)。

功能

功能	状态
私聊	✅ 支持
群组	❌ 即将推出(根据 Zalo 文档)
媒体(图片)	✅ 支持
反应	❌ 不支持
线程	❌ 不支持
投票	❌ 不支持
原生命令	❌ 不支持
流式传输	⚠️ 已阻止(2000 字符限制)

投递目标(CLI/cron)

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

故障排除

机器人不响应:

检查令牌是否有效:openclaw channels status --probe
验证发送者已批准(配对或 allowFrom)
检查网关日志:openclaw logs --follow

Webhook 未收到事件:

确保 webhook URL 使用 HTTPS
验证密钥令牌为 8-256 字符
确认网关 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.mediaMaxMb:入站/出站媒体上限(MB,默认 5)。
channels.zalo.webhookUrl:启用 webhook 模式(需要 HTTPS)。
channels.zalo.webhookSecret:webhook 密钥(8-256 字符)。
channels.zalo.webhookPath:网关 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。

Zalo (Bot API) ​

需要插件 ​

快速设置(入门) ​

它是什么 ​

设置(快速路径) ​

1) 创建机器人令牌(Zalo Bot Platform) ​

2) 配置令牌(环境变量或配置) ​

工作原理(行为) ​

限制 ​

访问控制(私聊) ​

私聊访问 ​

长轮询 vs webhook ​

支持的消息类型 ​

功能 ​

投递目标(CLI/cron) ​

故障排除 ​

配置参考(Zalo) ​