OpenClaw从入门到应用——频道：Zalo
通过OpenClaw实现副业收入：《OpenClaw赚钱实录：从“养龙虾“到可持续变现的实践指南》
Quick setup (beginner)
安装 Zalo 插件：
- 从源码检出安装：
openclaw plugins install ./extensions/zalo - 从 npm 安装（如果已发布）：
openclaw plugins install @openclaw/zalo - 或者在新手引导中选择Zalo并确认安装提示
- 从源码检出安装：
设置令牌：
- 环境变量：
ZALO_BOT_TOKEN=... - 或者配置文件：
channels.zalo.botToken: "..."
- 环境变量：
重启网关（或完成新手引导）。
私聊默认需要配对；首次联系时需批准配对码。
最小配置示例：
{ channels: { zalo: { enabled: true, botToken: "12345689:abc-xyz", dmPolicy: "pairing", }, }, }What it is
Zalo 是一款以越南市场为主的消息应用；其机器人 API 允许网关运行机器人进行一对一对话。它非常适合需要确定性路由回 Zalo 的场景，例如支持或通知。
- 由网关拥有的 Zalo 机器人 API 通道。
- 确定性路由：回复会回到 Zalo；模型不会选择其他通道。
- 私聊共享智能体的主会话。
- 群组支持策略控制（
groupPolicy+groupAllowFrom），默认为 fail‑closed 的允许列表模式。
Setup (fast path)
1) 创建机器人令牌（Zalo 机器人平台）
- 访问 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。
重启网关。当令牌解析成功（来自环境变量或配置文件）后，Zalo 通道即启动。
私聊默认需要配对。首次联系机器人时批准配对码。
How it works (behavior)
- 入站消息被标准化为共享的通道信封，包含媒体占位符。
- 回复总是路由回同一个 Zalo 聊天。
- 默认使用长轮询；可通过
channels.zalo.webhookUrl启用 Webhook 模式。
Limits
- 出站文本被分块为 2000 个字符（Zalo API 限制）。
- 媒体下载/上传大小受
channels.zalo.mediaMaxMb限制（默认 5 MB）。 - 由于 2000 字符限制使流式传输作用不大，默认禁用流式传输。
Access control (DMs)
私聊访问
- 默认：
channels.zalo.dmPolicy = "pairing"。未知发送者会收到配对码；消息在被批准前会被忽略（配对码一小时后过期）。 - 批准方式：
openclaw pairing list zaloopenclaw pairing approve zalo <用户ID>
- 配对是默认的令牌交换机制。详情：配对 → 实际链接已替换为 https://blog.csdn.net/hy592070616/article/details/81707766
channels.zalo.allowFrom接受数字用户 ID（不支持用户名查找）。
Access control (Groups)
channels.zalo.groupPolicy控制群组入站处理：open | allowlist | disabled。- 默认行为是 fail‑closed：
allowlist。 channels.zalo.groupAllowFrom限制哪些发送者 ID 可以在群组中触发机器人。- 如果未设置
groupAllowFrom，Zalo 会回退到allowFrom进行发送者检查。 groupPolicy: "disabled"阻止所有群组消息。groupPolicy: "open"允许任何群组成员（需要 @提及）。- 运行时注意：如果
channels.zalo完全缺失，运行时会出于安全考虑回退到groupPolicy="allowlist"。
Long-polling 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 URL 的路径）处理 Webhook 请求。 - 请求必须使用
Content-Type: application/json（或+json媒体类型）。 - 在短时间防重窗口内，重复事件（
event_name + message_id）会被忽略。 - 突发流量会按路径/源进行速率限制，可能返回 HTTP 429。
注意：根据 Zalo API 文档，getUpdates（轮询）和 Webhook 互斥。
Supported message types
- 文本消息：完全支持，自动分块为 2000 字符。
- 图片消息：下载并处理入站图片；通过
sendPhoto发送图片。 - 贴纸：记录日志但不完全处理（智能体不会响应）。
- 不支持的类型：记录日志（例如来自受保护用户的消息）。
Capabilities
| 功能 | 状态 |
|---|---|
| 私聊 | ✅ 支持 |
| 群组 | ⚠️ 支持，带策略控制（默认为允许列表） |
| 媒体（图片） | ✅ 支持 |
| 消息回应 | ❌ 不支持 |
| 消息线程 | ❌ 不支持 |
| 投票 | ❌ 不支持 |
| 原生命令 | ❌ 不支持 |
| 流式传输 | ⚠️ 已屏蔽（2000 字符限制） |
Delivery targets (CLI/cron)
- 使用聊天 ID 作为目标。
- 示例：
openclaw message send --channel zalo --target 123456789 --message "hi"
Troubleshooting
机器人没有响应：
- 检查令牌是否有效：
openclaw channels status --probe - 确认发送者已获批准（配对或 allowFrom）
- 查看网关日志：
openclaw logs --follow
Webhook 收不到事件：
- 确保 Webhook URL 使用 HTTPS
- 确认密钥长度为 8‑256 个字符
- 确认网关 HTTP 端点可在配置的路径上访问
- 检查 getUpdates 轮询是否未运行（两者互斥）
Configuration reference (Zalo)
完整配置：配置 → 实际链接已替换为 https://blog.csdn.net/hy592070616/article/details/81707766
提供方选项：
channels.zalo.enabled：启用/禁用通道启动。channels.zalo.botToken：来自 Zalo 机器人平台的机器人令牌。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：网关 HTTP 服务器上的 Webhook 路径。channels.zalo.proxy：API 请求的代理 URL。
多账户选项：
channels.zalo.accounts.<name>.botToken：每个账户的令牌。channels.zalo.accounts.<name>.tokenFile：每个账户的普通令牌文件。拒绝符号链接。channels.zalo.accounts.<name>.name：显示名称。channels.zalo.accounts.<name>.enabled：启用/禁用账户。channels.zalo.accounts.<name>.dmPolicy：每个账户的私聊策略。channels.zalo.accounts.<name>.allowFrom：每个账户的允许列表。channels.zalo.accounts.<name>.groupPolicy：每个账户的群组策略。channels.zalo.accounts.<name>.groupAllowFrom：每个账户的群组发送者允许列表。channels.zalo.accounts.<name>.webhookUrl：每个账户的 Webhook URL。channels.zalo.accounts.<name>.webhookSecret：每个账户的 Webhook 密钥。channels.zalo.accounts.<name>.webhookPath：每个账户的 Webhook 路径。channels.zalo.accounts.<name>.proxy：每个账户的代理 URL。