Zalo Bot Connect

安装指南

1. ClawHub CLI 从源直接安装技能的最快方式。
   npx clawhub@latest install ent-zalo-connect
2. 手动安装 将技能文件夹复制到以下位置之一
   全局模式
   ~/.openclaw/skills/
   工作区
   /skills/
   优先级：工作区 > 本地 > 内置
3. 提示词安装 将此提示词复制到 OpenClaw 即可自动安装。
   请帮我使用 Clawhub 安装 ent-zalo-connect。如果尚未安装 Clawhub，请先安装（npm i -g clawhub）。
   更倾向于下载？
   获取包含原生技能文件的ZIP压缩包。
   下载技能 (.zip)

什么是

Zalo Bot Connect 是一项 OpenClaw 代理技能，可从零开始连接 Zalo Bot Platform，无需高级技术知识。用户提供 bot 令牌和群组聊天 ID，代理会验证 bot、将凭据保存到网关环境中、发送真实测试消息并报告结果。
此技能有意仅限于基本消息操作：使用 sendMessage 发送消息；仅当未配置 webhook 时，才使用 getUpdates 读取更新。它不会修改或删除数据、访问未指定的群组，也不会声称支持原生用户提及。Openclaw Skills 用户可用它可靠地发送 Zalo 提醒、警报和运营通知。

应用场景

仅使用令牌和群组聊天 ID，将新的 Zalo Bot 连接到 OpenClaw 网关。
向 Zalo 群组发送任务提醒、截止日期通知、预算警报和紧急消息。
保存配置前验证 bot 令牌是否有效。
通过发送真实测试消息，确认 bot 能否联系特定群组。
当 bot 未使用 webhook 时，通过基本轮询读取传入的更新。
通过引导式聊天流程，帮助非技术用户配置 Zalo 消息功能。
排查无效令牌、错误的聊天 ID、缺少群组成员身份、webhook 冲突和计划限制。

工作原理

代理检测到连接或配置 Zalo Bot 的请求，并从用户消息中提取 ZALO_BOT_TOKEN 和 ZALO_CHAT_ID，接受 token、Zalo token、group 和 chat ID 等常见标签。
它会确认请求者是代理所有者或机器所有者。如果所有权不明确，则会在保存配置前要求确认。
它会检查两个必需值是否齐全。如果缺少任一值，只会询问缺少的值，不会猜测。
它会调用 Zalo getMe 端点，验证令牌是否有效以及 bot 是否可用。若发生错误，流程将停止。
它会将两个 Zalo 变量合并到现有网关环境中，不覆盖无关的环境设置。
它会重启网关，以加载新的环境值。
它会调用 sendMessage，向已配置的聊天发送简短的连接成功消息。
它会报告令牌验证、配置保存和消息发送是否成功，并在可用时附上返回的 message_id。
对于传入消息，仅当未配置 webhook 时才可调用 getUpdates；基于 webhook 的 bot 必须通过 webhook 接收更新。

配置指南

前提条件
在 bot.zaloplatforms.com 的 Zalo Bot Platform 中创建 bot，并获取格式为 : 的令牌。
手动将 bot 添加到目标 Zalo 群组。
获取目标群组聊天 ID（通常以 zgr- 开头），或者使用一对一聊天的数字 ID。
将令牌和聊天 ID 提供给获得所有者授权的代理。
环境变量
使用以下值配置网关，不要将其硬编码到应用程序源代码中：
export ZALO_BOT_TOKEN=':'
export ZALO_CHAT_ID=''
验证 bot
curl -s "https://bot-api.zaloplatforms.com/bot$ZALO_BOT_TOKEN/getMe" \ -H "Content-Type: application/json" 仅当响应表明 ok: true 时才继续。
发送测试消息
curl -s -X POST "https://bot-api.zaloplatforms.com/bot$ZALO_BOT_TOKEN/sendMessage" \ -H "Content-Type: application/json" \ -d "{\"chat_id\":\"$ZALO_CHAT_ID\",\"text\":\"Connection successful\"}" 响应中包含 message_id 即可确认消息已送达。合并环境值后重启网关，必要时再次执行测试。
可选的更新轮询
仅当 bot 未配置 webhook 时才使用轮询：
curl -s "https://bot-api.zaloplatforms.com/bot$ZALO_BOT_TOKEN/getUpdates"
切勿在聊天或日志中输出令牌、将其提交到 Git，或与其他机器或代理共享。

数据架构

环境配置
Key Purpose Format
ZALO_BOT_TOKEN 对 Zalo Bot API 的请求进行身份验证 :
ZALO_CHAT_ID 标识已批准的目标聊天 群组通常为 zgr-...，一对一聊天则为数字 ID
API 结构
Operation Method Endpoint Payload
验证 bot GET /bot/getMe 无
发送消息 POST /bot/sendMessage {chat_id, text}
读取更新 GET /bot/getUpdates 无；仅在未使用 webhook 时调用
配置行为
通过合并操作保留现有网关环境值。
仅添加或更新 ZALO_BOT_TOKEN 和 ZALO_CHAT_ID。
此技能不需要消息数据库、生成的项目文件或持久化内容架构。
发送结果可能包含 Zalo message_id，用于确认。
消息模板可以包含收件人姓名、提醒状态、截止日期、预算值和紧急程度标记。
此工作流不支持 Zalo 原生姓名提及；@Name 字符串只是普通文本。
发送消息前，必须先将 bot 添加到目标群组。

高级特性

仅所有者可执行，防止未经授权存储凭据或更改配置。
安全处理凭据，确保令牌不会出现在聊天回复、日志、源代码或 Git 历史记录中。
合并环境设置，保护无关的网关配置，而不是替换整个环境。
getMe
自动验证令牌，在保存无效凭据之前停止流程。
通过真实的
sendMessage
请求端到端验证消息送达，并报告返回的消息 ID。
可复用的提醒、紧急情况、预算和连接成功消息模板支持运营自动化。
同时支持群组聊天和数字格式的一对一聊天 ID。
清楚区分使用
getUpdates
轮询与通过 webhook 投递，并说明错误地同时使用二者会导致的 400 错误。
为无效令牌、错误的聊天 ID、bot 未加入群组、URL 路径格式错误、webhook 冲突和每月 BASIC 计划限制提供实用诊断。
当需要将传入的 Zalo 消息接入 OpenClaw 时，可搭配外部 webhook bridge；该 bridge 不属于此技能的范围。

name: "ent-zalo-connect" description: "Kết nối Zalo Bot 1 câu: dán token bot + chat_id, agent tự lưu env, test gửi tin, báo kết quả. Kèm hướng dẫn gửi tin nhắc/cảnh báo vào nhóm Zalo."

ent-zalo-connect — Kết nối Zalo Bot trong 1 câu

Skill này giúp agent kết nối Zalo Bot Platform từ số 0: nhận token bot + id nhóm từ người dùng, lưu vào env, gửi tin thử và báo kết quả. Dành cho người dùng không rành kỹ thuật — chỉ cần dán token + id nhóm vào chat.

⚠️ Skill này CHỈ gửi tin nhắn (sendMessage) + đọc cập nhật (getUpdates khi chưa set webhook). KHÔNG xoá/sửa dữ liệu, KHÔNG đụng nhóm khác ngoài đích đã chỉ định.

0. KÍCH HOẠT — câu lệnh người dùng chỉ cần nhập

Khi người dùng gửi tin dạng:

Kết nối Zalo Bot giúp tôi.
Token bot:
Nhóm:

hoặc

Cấu hình Zalo Bot: token ..., nhóm ...

Agent PHẢI hiểu là: kết nối Zalo Bot với token + id nhóm đã cung cấp.

Quy trình tự động khi nhận câu lệnh trên
Trích xuất ZALO_BOT_TOKEN và ZALO_CHAT_ID từ tin nhắn (chấp nhận ghi lệch như "token", "Zalo token", "nhóm", "chat id").
Kiểm tra token sống — gửi thử getMe (mục 3.1). Lỗi → DỪNG, báo token sai.
Lưu vào env của gateway: ZALO_BOT_TOKEN + ZALO_CHAT_ID (giữ nguyên env cũ, merge — mục 4).
Test gửi tin thật vào nhóm (mục 3.2) — nội dung ngắn kiểu "✅ Em đã kết nối Zalo Bot thành công."
Báo kết quả ngắn gọn: token hợp lệ, đã lưu, gửi tin OK (kèm message_id nếu có).

⚠️ Thiếu token hoặc chat_id → hỏi lại đúng cái thiếu, KHÔNG tự đoán. ⚠️ Chỉ thực thi khi người gửi là owner. Không chắc → hỏi xác nhận trước khi lưu config.

1. Cần chuẩn bị (người dùng) Thứ Lấy ở đâu
   Bot Token Tạo bot tại Zalo Bot Platform (bot.zaloplatforms.com) → lấy token dạng :
   Chat ID nhóm id nhóm người dùng (nhóm thường bắt đầu zgr-...; chat 1-1 là id số)
   Bot đã vào nhóm Phải add bot vào nhóm Zalo đích thủ công trước khi gửi được
2. Cấu trúc API Zalo Bot

Base https://bot-api.zaloplatforms.com/bot
Gửi tin POST {base}/sendMessage — JSON {"chat_id": "...", "text": "..."}
Kiểm tra bot GET {base}/getMe
Nhận tin (chưa webhook) GET {base}/getUpdates

⚠️ Token nằm ngay trong path URL (khác Meta). Vẫn KHÔNG echo token ra chat/log.

3. Các lệnh (BẮT BUỘC dùng cách này)

Env: ZALO_BOT_TOKEN, ZALO_CHAT_ID.

3.1 Kiểm tra bot còn sống

curl -s "https://bot-api.zaloplatforms.com/bot$ZALO_BOT_TOKEN/getMe" \

-H "Content-Type: application/json"

ok: true → token hợp lệ, đi tiếp.
Lỗi / ok: false → DỪNG, báo token sai hoặc bot bị khoá. 3.2 Gửi tin vào nhóm

curl -s -X POST "https://bot-api.zaloplatforms.com/bot$ZALO_BOT_TOKEN/sendMessage" \

-H "Content-Type: application/json"
-d "{"chat_id":"$ZALO_CHAT_ID","text":"Nội dung tin"}"

Trả JSON có message_id → gửi OK.
Lỗi chat not found → bot chưa vào nhóm, hoặc sai chat_id. 3.3 Đọc tin nhắn đến (chỉ khi CHƯA set webhook)

curl -s "https://bot-api.zaloplatforms.com/bot$ZALO_BOT_TOKEN/getUpdates"

Nếu bot đã set webhook → API này báo lỗi 400. Khi đó tin đến đẩy về webhook, không dùng getUpdates. 3.4 Mẫu gửi tin Python (tái dùng) import os, json, urllib.request

TOKEN = os.environ["ZALO_BOT_TOKEN"]
CHAT_ID = os.environ["ZALO_CHAT_ID"]

def send_zalo(text):
url = f"https://bot-api.zaloplatforms.com/bot{TOKEN}/sendMessage"
body = json.dumps({"chat_id": CHAT_ID, "text": text}).encode()
req = urllib.request.Request(url, data=body, headers={"Content-Type": "application/json"})
with urllib.request.urlopen(req, timeout=20) as r:
return json.loads(r.read().decode())

4. Lưu vào env gateway (không hardcode) Đọc config hiện tại, giữ nguyên toàn bộ env cũ, chỉ thêm/cập nhật:
   ZALO_BOT_TOKEN
   ZALO_CHAT_ID
   Dùng merge (không ghi đè cả file). Nếu mục env chưa có → tạo mới chỉ với 2 khoá.
   Sau khi lưu → restart gateway để env nạp lại, rồi test lại mục 3.2.
   KHÔNG echo token ra chat/log, KHÔNG commit token vào git.
5. Mẫu tin nhắc/cảnh báo (gợi ý — tái dùng) Nhắc việc: 📌 {TÊN} — NHẮC VIỆC: Còn 2 ngày tới hạn
   Khẩn cấp: 🚨 {TÊN} — KHẨN CẤP: CÒN DƯỚI 24H, CHƯA HOÀN THÀNH 🚨
   Cảnh báo ngân sách: 🚨 {TÊN} — ĐÃ HẾT/TIÊU LỐ — ngân sách {X}đ, đã tiêu {Y}đ, còn {Z}đ. Cần xử lý ngay.
   Kết nối thành công: ✅ Em đã kết nối Zalo Bot thành công.

💡 Mẹo quan trọng: đưa tên người lên đầu tin — vì Zalo Bot KHÔNG tag được tên (xem mục 6).

6. GIỚI HẠN Zalo Bot — BẮT BUỘC NHỚ (đừng hứa sai) Giới hạn Chi tiết
   KHÔNG tag/mention tên người @Tên chỉ là chữ thường, KHÔNG tạo thông báo như Telegram. Cách bù: đẩy tên lên đầu tin.
   Trần gói BASIC 3 bot · 50 người dùng/bot · 3.000 tin/tháng · 3 nhóm chat (beta)
   Gói Pro 129.000đ/tháng — trần cao hơn (Zalo chưa công bố số)
   Enterprise Khuyên dùng Zalo OA
   Webhook vs getUpdates Set webhook thì getUpdates không dùng được (lỗi 400)
   Bot phải vào nhóm Phải add bot vào nhóm Zalo thủ công trước
   Không moi tin cũ Bot không đọc được tin trước khi vào nhóm
   Rate limit Zalo chưa công bố số tin/giây, tin/phút — cần tra lại
7. Xử lý sự cố Lỗi Nguyên nhân Cách xử lý
   getMe trả lỗi Token sai / bot bị khoá Kiểm tra lại token trên dashboard Zalo Bot
   chat not found Bot chưa vào nhóm, hoặc sai chat_id Add bot vào nhóm; xác nhận lại chat_id
   Gửi được nhưng nhóm không thấy Sai chat_id Lấy lại id nhóm đúng
   getUpdates lỗi 400 Bot đã set webhook Dùng webhook thay vì getUpdates
   Lỗi 4xx "giả" Token nhét sai cách Token nằm trong path: /bot/... (không dùng -G --data-urlencode)
   Quá 3.000 tin/tháng Chạm trần BASIC Nâng gói Pro
8. Bảo mật — BẮT BUỘC Chỉ nhận token từ owner của agent/máy.
   KHÔNG ghi token ra file log, KHÔNG echo token ra chat.
   KHÔNG chia sẻ token sang máy/agent khác.
   Token trong lịch sử chat là rủi ro → cân nhắc rotate sau khi dùng.
9. Ghi chú kỹ thuật Token dạng :, ví dụ 1872836222002838814:xxxx.
   Endpoint gửi tin: POST /bot/sendMessage, body JSON {chat_id, text}.
   Nhóm thường có id bắt đầu zgr-...; chat 1-1 là id số.
   Nếu cần nhận tin vào OpenClaw: cần bridge webhook chạy như service (ngoài phạm vi skill này) — skill này lo phần gửi và kết nối cơ bản.
   PB-Runner 跑步教练

OKF Index