Zalo
Zalo Bot：支持状态、能力与配置
状态：实验性。当前仅支持私信（1:1）；按 Zalo 文档，群聊支持"即将推出"。
需要安装插件
Zalo 以插件形式提供，不随 core 安装打包。
- CLI 安装：openclaw plugins install @openclaw/zalo
- 或在 onboarding 里选择 Zalo 并确认安装提示
- 详情：''/plugin''
新手快速配置
1. 安装 Zalo 插件：
- 从源码 checkout：openclaw plugins install ./extensions/zalo
- 从 npm（若已发布）：openclaw plugins install @openclaw/zalo
- 或在 onboarding 里选择 Zalo 并确认安装提示
2. 设置 token：
- Env：ZALO_BOT_TOKEN=...
- 或 config：channels.zalo.botToken: "..."。
3. 重启 gateway（或完成 onboarding）。
4. 私信默认 pairing：首次联系会收到配对码，批准后才会处理消息。
最小配置：
{
channels: {
zalo: {
enabled: true,
botToken: "12345689:abc-xyz",
dmPolicy: "pairing",
},
},
}这是什么
Zalo 是越南常用的消息应用；Bot API 允许 Gateway 运行一个 1:1 bot。适用于支持/通知等场景（需要确定性路由回 Zalo）。
- 一个由 Gateway 管理的 Zalo Bot API 通道。
- 确定性路由：回复只回到 Zalo，模型不会选择通道。
- 私信共享 agent 主会话。
- 群聊暂不支持（Zalo 文档称"coming soon"）。
设置（快速路径）
#
1）创建 bot token（Zalo Bot Platform）
1. 打开 https://bot.zaloplatforms.com 并登录。
2. 创建一个新 bot 并完成设置。
3. 复制 bot token（格式：12345689:abc-xyz）。
#
2）配置 token（env 或 config）
示例：
{
channels: {
zalo: {
enabled: true,
botToken: "12345689:abc-xyz",
dmPolicy: "pairing",
},
},
}环境变量方式：ZALO_BOT_TOKEN=...（仅对 default account 生效）。
多账号：使用 channels.zalo.accounts 配置每个账号的 token（可选 name）。
3. 重启 gateway。token 可解析时（env 或 config）Zalo 会启动。
4. 私信默认 pairing：第一次联系时批准配对码。
工作方式（行为）
- 入站消息会被归一化到通用的 channel envelope（带媒体占位符）。
- 回复始终回到同一个 Zalo chat。
- 默认 long-polling；可通过 channels.zalo.webhookUrl 启用 webhook 模式。
限制
- 出站文本按 2000 字符分段（Zalo API 限制）。
- 媒体下载/上传上限：channels.zalo.mediaMaxMb（默认 5MB）。
- 由于 2000 字符上限使流式意义不大，默认禁用 streaming。
访问控制（私信）
#
私信访问
- 默认：channels.zalo.dmPolicy = "pairing"。未知发送者会收到配对码；批准前消息会被忽略（配对码 1 小时过期）。
- 批准：
- openclaw pairing list zalo
- openclaw pairing approve zalo <CODE>
- pairing 是默认 token exchange。详情：''/start/pairing''
- channels.zalo.allowFrom 只接受数值 user IDs（没有 username lookup）。
Long-polling vs webhook
- 默认：long-polling（不需要公网 URL）。
- Webhook 模式：设置 channels.zalo.webhookUrl 与 channels.zalo.webhookSecret。
- secret 必须为 8–256 个字符。
- webhook URL 必须为 HTTPS。
- Zalo 使用 X-Bot-Api-Secret-Token header 做校验。
- Gateway 在 channels.zalo.webhookPath 处理 webhook（默认使用 webhook URL 的 path）。
注意： 按 Zalo API 文档，getUpdates（polling）与 webhook 互斥。
支持的消息类型
- 文本：完全支持（2000 字符分段）。
- 图片：支持下载/处理入站图片；出站通过 sendPhoto 发送图片。
- 贴纸：会记录日志，但不会完整处理（通常不触发 agent 回复）。
- 不支持类型：仅记录日志（例如来自受保护用户的消息）。
能力
| 功能 | 状态 |
| -- |
| 私信 | ✅ 支持 |
| 群聊 | ❌ Zalo 文档称即将支持 |
| 媒体（图片） | ✅ 支持 |
| Reactions | ❌ 不支持 |
| Threads | ❌ 不支持 |
| Polls | ❌ 不支持 |
| 原生命令 | ❌ 不支持 |
| Streaming | ⚠️ 默认禁用（2000 字符限制） |
投递目标（CLI/cron）
- target 使用 chat id。
- 示例：openclaw message send --channel zalo --target 123456789 --message "hi"。
排障
Bot 不回复：
- 用 openclaw channels status --probe 检查 token 是否有效
- 确认发送者已被批准（pairing 或 allowFrom）
- 看日志：openclaw logs --follow
Webhook 收不到事件：
- 确认 webhook URL 为 HTTPS
- 确认 secret 长度为 8–256 字符
- 确认 gateway 的 HTTP endpoint 在配置的路径上可达
- 确认没有在跑 getUpdates polling（两者互斥）
配置参考（Zalo）
完整配置：''/gateway/configuration''
Provider 选项：
- channels.zalo.enabled
- channels.zalo.botToken
- channels.zalo.tokenFile（从文件读取）
- channels.zalo.dmPolicy：pairing | allowlist | open | disabled（默认 pairing）
- channels.zalo.allowFrom：私信 allowlist（user IDs）；open 需要 "*"；向导会要求填数值 ID
- channels.zalo.mediaMaxMb：入站/出站媒体上限（MB，默认 5）
- channels.zalo.webhookUrl：启用 webhook 模式（需要 HTTPS）
- channels.zalo.webhookSecret：webhook secret（8–256 字符）
- channels.zalo.webhookPath：gateway 的 webhook path
- 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
- channels.zalo.accounts.<id>.webhookSecret
- channels.zalo.accounts.<id>.webhookPath
- channels.zalo.accounts.<id>.proxy