OpenClaw

OpenClaw Zalo 渠道

即时通讯
中等

通过 Zalo Bot Platform 将 OpenClaw 连接到 Zalo。此集成让你的 AI 助手可以在越南最受欢迎的即时通讯应用上收发消息。只需设置 Bot Token，配置私聊策略，即可开始聊天——支持长轮询和 Webhook 两种消息接收模式。

快速信息
难度中等
分类即时通讯
支持功能数1 / 6

Zalo 支持的功能

文本消息

支持

媒体与文件

不支持

消息反应

不支持

消息线程

不支持

语音消息

不支持

群聊

不支持

Zalo 前置条件

  • 拥有 Zalo 账号并可访问 Zalo Bot Platform（bot.zaloplatforms.com）
  • 从 Zalo Bot Platform 控制台获取的 Bot Token
  • OpenClaw Gateway 已运行并配置完成
  • 若使用 Webhook 模式：需要一个可公开访问的 HTTPS 端点

Zalo 快速设置

1

创建 Zalo Bot 并获取 Token

前往 bot.zaloplatforms.com，使用 Zalo 账号登录，创建一个新的 Bot。从控制台复制 Bot Token（格式如：12345689:abc-xyz）。

2

添加 Zalo 渠道配置

将 Zalo 渠道配置添加到 ~/.openclaw/openclaw.json。设置 botToken、dmPolicy（pairing、allowlist、open 或 disabled），并可选择配置 Webhook 设置。

3

启动 Gateway 并测试

使用 'openclaw start' 启动 Gateway。默认通过长轮询模式连接。在 Zalo 上向你的 Bot 发送一条消息以验证连接是否正常。

Zalo 配置示例

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

Zalo 深入了解

架构概览

OpenClaw 通过 Zalo Bot Platform API 发送和接收消息。Gateway 使用长轮询（默认）或 Webhook 模式与 Zalo 服务器通信。 在长轮询模式下，Gateway 定期检查新消息——无需公网 URL 或 HTTPS 证书。在 Webhook 模式下，Zalo 会直接将事件推送到你的服务器，这需要一个可公开访问的 HTTPS 端点。 Zalo 用户的消息由 Gateway 接收，交由 AI 处理，然后通过 Zalo Bot API 发送回复。每个对话按用户独立跟踪，因此多个用户可以同时与同一个 Bot 交互。
长轮询无需任何网络配置即可使用。适合开发环境或没有公网 URL 的场景。
Webhook 模式延迟更低，推荐在拥有稳定 HTTPS 端点的生产环境中使用。

创建 Zalo Bot

要将 OpenClaw 连接到 Zalo，你需要从 Zalo Bot Platform 获取 Bot Token： 1. 前往 bot.zaloplatforms.com，使用 Zalo 账号登录。 2. 点击\"创建 Bot\"并填写必要信息（名称、描述、分类）。 3. 创建完成后，进入 Bot 设置页面并复制 Bot Token。 Bot Token 是连接所需的唯一凭证。你可以通过配置文件、环境变量（ZALO_BOT_TOKEN）或使用 tokenFile 选项从文件读取。
openclaw.json
{
  "channels": {
    "zalo": {
      "enabled": true,
      "botToken": "12345689:abc-xyz"
    }
  }
}
将 Bot Token 存储在环境变量（ZALO_BOT_TOKEN）或单独文件（tokenFile）中，避免将密钥提交到版本控制系统。

私聊策略

私聊策略控制谁可以与你的 AI 助手互动。OpenClaw 支持四种策略： • pairing（默认）— 新用户首次发消息时会收到配对码。你可以通过 'openclaw pairing approve zalo <code>' 批准或拒绝。配对码在 1 小时后过期。 • allowlist — 只有 allowFrom 列表中的数字用户 ID 可以与 Bot 交互。其他人将被静默忽略。 • open — 任何向 Bot 发消息的人都会收到回复。请谨慎使用。 • disabled — 完全关闭私聊处理。
openclaw.json
{
  "channels": {
    "zalo": {
      "dmPolicy": "allowlist",
      "allowFrom": ["123456789", "987654321"]
    }
  }
}
'open' 策略允许任何人与你的 Bot 互动。如果你的 Bot 在 Zalo 上是公开可发现的，这可能会消耗大量 AI 配额。

Webhook 配置

默认情况下，OpenClaw 使用长轮询接收消息。要切换到 Webhook 模式，请在配置中设置 webhookUrl。这需要一个可公开访问的 HTTPS 端点。 启用 Webhook 模式后，长轮询会自动禁用。Zalo 会直接将消息事件发送到你的 Webhook URL。验证通过 Secret Token 完成——Zalo 会在每个请求的 X-Bot-Api-Secret-Token HTTP 头中包含该 Token。 webhookPath 选项允许你自定义 Gateway HTTP 服务器上接收 Zalo 事件的路径。
openclaw.json
{
  "channels": {
    "zalo": {
      "botToken": "12345689:abc-xyz",
      "webhookUrl": "https://your-server.com/zalo/webhook",
      "webhookSecret": "your-secret-string-8-to-256-chars",
      "webhookPath": "/zalo/webhook"
    }
  }
}
webhookSecret 的长度必须在 8 到 256 个字符之间。
Webhook 和长轮询是互斥的——设置 webhookUrl 会自动禁用轮询。

消息处理

OpenClaw 在 Zalo 上支持文本消息和图片消息。文本消息会按照 Zalo 的限制自动在 2,000 个字符处分段。 用户发送的图片会被下载并处理。向外发送的图片通过 Zalo sendPhoto API 发送。用户发送的贴纸消息会被记录但不会交由 AI 处理。 mediaMaxMb 设置控制接收媒体文件的最大大小（默认：5 MB）。
较长的 AI 回复会自动在 2,000 字符边界处拆分为多条消息。
由于字符限制，Zalo 不支持流式响应。

多账号设置

OpenClaw 支持同时运行多个 Zalo Bot 账号。每个账号有独立的 Bot Token、私聊策略和可选的 Webhook 配置。 如果你想在同一个 Gateway 实例下运行不同用途的 Bot（例如客服 Bot 和内部团队 Bot），这非常有用。
openclaw.json
{
  "channels": {
    "zalo": {
      "accounts": {
        "support-bot": {
          "botToken": "token-for-support-bot",
          "dmPolicy": "open"
        },
        "team-bot": {
          "botToken": "token-for-team-bot",
          "dmPolicy": "allowlist",
          "allowFrom": ["111222333"]
        }
      }
    }
  }
}

主动发送消息

你可以通过 CLI 向特定 Zalo 用户发送消息。消息会确定性地路由回原始 Zalo 聊天，因此回复始终发送给正确的用户。 要向特定用户发送手动消息，使用 target 参数并指定其数字 Zalo 用户 ID。
terminal
openclaw message send --channel zalo --target 123456789

代理配置

如果你的服务器需要通过代理进行出站连接，可以为 Zalo 渠道配置代理。代理 URL 将用于所有发往 Zalo 服务器的 API 请求。 这在企业环境或直接访问 Zalo API 端点受限的地区非常有用。
openclaw.json
{
  "channels": {
    "zalo": {
      "proxy": "http://proxy.example.com:8080"
    }
  }
}

Zalo 配置参考

enabled
Type: booleanDefault: false

启用或禁用 Zalo 渠道

botToken
Type: stringDefault: ""

来自 Zalo Bot Platform（bot.zaloplatforms.com）的 Bot Token

tokenFile
Type: stringDefault: ""

从文件路径读取 Bot Token，替代内联配置

dmPolicy
Type: stringDefault: "pairing"

控制谁可以与 Bot 私聊。选项：pairing、allowlist、open、disabled

allowFrom
Type: string[]Default: []

允许与 Bot 交互的数字 Zalo 用户 ID 列表（当 dmPolicy 为 allowlist 时使用）

mediaMaxMb
Type: numberDefault: 5

接收媒体文件的最大大小（MB）

webhookUrl
Type: stringDefault: ""

Webhook 模式的 HTTPS URL。设置后将禁用长轮询

webhookSecret
Type: stringDefault: ""

用于 Webhook 验证的密钥字符串（8-256 个字符），通过 X-Bot-Api-Secret-Token 头传递

webhookPath
Type: stringDefault: ""

Gateway HTTP 服务器上的自定义 Webhook 路径

proxy
Type: stringDefault: ""

发往 Zalo 的出站 API 请求使用的代理 URL

accounts.<id>.botToken
Type: stringDefault: ""

多账号模式下特定账号的 Bot Token

accounts.<id>.dmPolicy
Type: stringDefault: "pairing"

特定账号的私聊策略覆盖

accounts.<id>.webhookUrl
Type: stringDefault: ""

特定账号的 Webhook URL 覆盖

Zalo 常见问题

Zalo 故障排查

Bot 收不到任何消息

Bot Token 可能无效、已过期，或 Gateway 未运行。在 Webhook 模式下，HTTPS 端点可能无法访问。

在 bot.zaloplatforms.com 验证你的 Bot Token。检查 Gateway 日志中的连接错误。如果使用 Webhook，确认端点可通过 HTTPS 公开访问，且 webhookSecret 匹配。
消息延迟或批量到达

长轮询相比 Webhook 模式存在固有延迟。网络不稳定也可能导致消息批量到达。

切换到 Webhook 模式以获得更低延迟。确保服务器网络连接稳定。检查 Gateway 日志中的轮询间隔信息。
新用户未收到配对码

dmPolicy 可能未设置为 'pairing'，或 Bot 未正确连接到 Zalo。

确认配置中 dmPolicy 已设置为 'pairing'。检查 Gateway 日志确认 Zalo 渠道已上线。运行 'openclaw pairing list zalo' 查看待处理的配对请求。
图片消息发送失败

图片文件可能超过 mediaMaxMb 限制，或 Zalo API 暂时不可用。

检查图片文件大小是否在 mediaMaxMb 限制内（默认：5 MB）。查看 Gateway 日志中的具体 API 错误信息。先尝试发送文本消息以确认连接正常。
Webhook 验证失败

配置中的 webhookSecret 与 Zalo 预期的不匹配，或端点未返回正确响应。

确保 webhookSecret 长度在 8 到 256 个字符之间。验证 HTTPS 证书是否有效（不接受自签名证书）。检查 webhookPath 是否与服务器的路由配置匹配。
查看完整文档返回所有渠道

相关渠道

WhatsApp

Medium

OpenClaw 通过 Baileys 协议扫码连接

配置指南

Telegram

Easy

OpenClaw 通过 grammY 框架的 Bot API 集成

配置指南

Discord

Easy

OpenClaw 使用 discord.js 的 Bot Token 集成

配置指南