学了个寂寞

Appearance

Zalo（Bot API） ​

状态：实验性。支持私信。功能支持情况部分反映了当前 Marketplace 机器人的实际行为。

需要安装插件 ​

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

  • 通过 CLI 安装：openclaw plugins install @openclaw/zalo
  • 或在设置时选择 Zalo 并确认安装提示
  • 详情：插件系统

快速配置（新手上路） ​

  1. 安装 Zalo 插件：
    • 从源码 checkout：openclaw plugins install ./extensions/zalo
    • 从 npm（如已发布）：openclaw plugins install @openclaw/zalo
    • 或在设置时选择 Zalo 并确认安装提示
  2. 设置 token：
    • 环境变量：ZALO_BOT_TOKEN=...
    • 或配置文件：channels.zalo.accounts.default.botToken: "..."
  3. 重启 Gateway（或完成设置流程）。
  4. 私信访问默认为配对模式，首次联系时批准配对码。

最小配置示例：

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

产品定位 ​

Zalo 是面向越南市场的通讯应用，其 Bot API 可让 Gateway 运行 1:1 对话机器人，适合支持或通知场景，回复路由确定性强。

本页反映 Zalo Bot Creator / Marketplace 机器人在 OpenClaw 中的当前行为。Zalo Official Account (OA) 机器人是不同的产品形态，行为可能有差异。

  • Gateway 独占的 Zalo Bot API 渠道。
  • 确定性路由：回复发回 Zalo，模型不选择渠道。
  • 私信共用 Agent 主会话。

创建 Bot Token（Zalo Bot Platform） ​

  1. 前往 https://bot.zaloplatforms.com 并登录。
  2. 创建新机器人并配置相关设置。
  3. 复制完整的机器人 token（通常格式为 numeric_id:secret）。对于 Marketplace 机器人，可用的运行时 token 可能在机器人创建后的欢迎消息中出现。

配置 Token ​

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

如后续迁移到支持群组的 Zalo 机器人形态，可以显式添加 groupPolicy 和 groupAllowFrom 等群组配置。当前 Marketplace 机器人行为请参见功能支持情况。

环境变量选项：ZALO_BOT_TOKEN=...（仅限默认账号）。

多账号支持：使用 channels.zalo.accounts 配置每账号 token，可设置可选的 name。

配置完成后重启 Gateway。Zalo 在 token 解析后（环境变量或配置）即启动。

工作原理 ​

  • 入站消息规范化为共享渠道信封，包含媒体占位符。
  • 回复始终路由回相同的 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>
  • 配对是默认 token 交换机制。详情：配对机制
  • channels.zalo.allowFrom 接受数字用户 ID（无用户名查询）。

群组访问控制 ​

对于 Zalo Bot Creator / Marketplace 机器人，实际上群组支持不可用，因为机器人根本无法加入群组。

以下群组相关配置键在 schema 中存在，但对 Marketplace 机器人不可用：

  • channels.zalo.groupPolicy：控制群组入站处理：open | allowlist | disabled。
  • channels.zalo.groupAllowFrom：限制哪些发送方 ID 可在群组中触发机器人。
  • 未设置 groupAllowFrom 时回退到 allowFrom。
  • 运行时说明：即使 channels.zalo 完全缺失，运行时也会安全回退到 groupPolicy="allowlist"。

如果你使用的是其他 Zalo 机器人产品形态并已验证群组功能正常，请单独记录，而不要假设与 Marketplace 机器人流程相同。

长轮询 vs Webhook ​

  • 默认： 长轮询（无需公网 URL）。
  • Webhook 模式： 设置 channels.zalo.webhookUrl 和 channels.zalo.webhookSecret。
    • webhook secret 必须为 8-256 个字符。
    • Webhook URL 必须使用 HTTPS。
    • Zalo 通过 X-Bot-Api-Secret-Token 请求头进行验证。
    • Gateway HTTP 在 channels.zalo.webhookPath 处理 webhook 请求（默认为 webhook URL 路径）。
    • 请求必须使用 Content-Type: application/json（或 +json 媒体类型）。
    • 重复事件（event_name + message_id）在短暂的重放窗口内被忽略。
    • 突发流量按路径/来源限速，可能返回 HTTP 429。

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

功能支持情况 ​

下表总结 Zalo Bot Creator / Marketplace 机器人在 OpenClaw 中的当前行为：

功能状态
私信支持
群组Marketplace 机器人不可用
媒体（入站图片）有限/请在你的环境中验证
媒体（出站图片）Marketplace 机器人未重新测试
文本中的普通 URL支持
链接预览Marketplace 机器人不稳定
反应不支持
StickerMarketplace 机器人无 Agent 回复
语音/音频/视频Marketplace 机器人无 Agent 回复
文件附件Marketplace 机器人无 Agent 回复
线程不支持
投票不支持
原生命令不支持
流式输出被屏蔽（2000 字符限制）

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

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

故障排查 ​

机器人不响应：

  • 检查 token 是否有效：openclaw channels status --probe
  • 确认发送方已批准（配对或 allowFrom）
  • 检查 Gateway 日志：openclaw logs --follow

Webhook 收不到事件：

  • 确认 webhook URL 使用 HTTPS
  • 验证 secret token 为 8-256 个字符
  • 确认 Gateway HTTP 端点在配置路径上可访问
  • 检查 getUpdates 轮询是否在运行（两者互斥）

配置参考（Zalo） ​

完整配置文档：Gateway 配置

顶层平铺键（channels.zalo.botToken、channels.zalo.dmPolicy 等）是旧版单账号简写。新配置建议使用 channels.zalo.accounts.<id>.*，两种形式均有文档说明。

主要配置项：

  • channels.zalo.enabled：启用/禁用渠道。
  • channels.zalo.botToken：来自 Zalo Bot Platform 的机器人 token。
  • channels.zalo.tokenFile：从普通文件路径读取 token（拒绝符号链接）。
  • 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 secret（8-256 个字符）。
  • channels.zalo.webhookPath：Gateway HTTP 服务器上的 webhook 路径。
  • channels.zalo.proxy：API 请求代理 URL。

多账号配置项：

  • channels.zalo.accounts.<id>.botToken：每账号 token。
  • channels.zalo.accounts.<id>.tokenFile：每账号普通 token 文件（拒绝符号链接）。
  • 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 secret。
  • channels.zalo.accounts.<id>.webhookPath：每账号 webhook 路径。
  • channels.zalo.accounts.<id>.proxy：每账号代理 URL。

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 地豆 蜀ICP备2021007188号 | 关于本站 | 隐私政策