Zalo

Trạng thái: thử nghiệm. Cả tin nhắn trực tiếp và trò chuyện nhóm đều đã được triển khai; bảng Khả năng bên dưới phản ánh hành vi đã được xác minh trên bot Zalo Bot Creator / Marketplace.

Plugin đi kèm

Zalo được cung cấp dưới dạng Plugin đi kèm trong các bản phát hành OpenClaw hiện tại, vì vậy các bản dựng đóng gói không cần cài đặt riêng.

Trên bản dựng cũ hơn hoặc bản cài đặt tùy chỉnh không bao gồm Zalo, hãy cài đặt trực tiếp gói npm:

• Cài đặt: openclaw plugins install @openclaw/zalo
• Phiên bản cố định: openclaw plugins install @openclaw/zalo@2026.6.11
• Từ bản mã nguồn cục bộ: openclaw plugins install ./path/to/local/zalo-plugin
• Chi tiết: Plugin

Thiết lập nhanh

1. Tạo mã thông báo bot tại https://bot.zaloplatforms.com (đăng nhập, tạo bot, cấu hình các thiết lập). Mã thông báo có dạng numeric_id:secret; đối với bot Marketplace, mã thông báo thời gian chạy có thể sử dụng có thể xuất hiện trong tin nhắn chào mừng của bot.
2. Đặt mã thông báo qua biến môi trường ZALO_BOT_TOKEN=... (chỉ dành cho tài khoản mặc định) hoặc trong cấu hình.
3. Khởi động lại Gateway.
4. Phê duyệt mã ghép nối khi có liên hệ qua tin nhắn trực tiếp lần đầu (chính sách tin nhắn trực tiếp mặc định là ghép nối).

Cấu hình tối thiểu:

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

Nhiều tài khoản: thêm các mục khác dưới channels.zalo.accounts.<id>, mỗi mục có botToken/name riêng. channels.zalo.botToken (dạng phẳng, không có accounts) là dạng viết tắt cũ cho một tài khoản; với cấu hình mới, nên dùng accounts.<id>.*.

Tổng quan

Zalo là ứng dụng nhắn tin tập trung vào thị trường Việt Nam. Bot API của Zalo cho phép Gateway vận hành bot cho cả cuộc trò chuyện 1:1 và trò chuyện nhóm, với định tuyến xác định trở lại Zalo (mô hình không bao giờ chọn kênh).

Trang này đề cập đến bot Zalo Bot Creator / Marketplace. Bot Zalo Official Account (OA) thuộc một bề mặt sản phẩm khác và có thể hoạt động khác; trang này không đề cập đến chúng.

Cách hoạt động

• Tin nhắn đến được chuẩn hóa thành phong bì kênh dùng chung cùng các phần giữ chỗ cho phương tiện.
• Phản hồi luôn được định tuyến trở lại cùng cuộc trò chuyện Zalo; không sử dụng trả lời trích dẫn (replyToMode được cố định ở trạng thái tắt).
• Theo mặc định sử dụng thăm dò dài (getUpdates); chế độ Webhook khả dụng qua channels.zalo.webhookUrl.
• Trong nhóm, bot chỉ được kích hoạt khi được @đề cập; không thể cấu hình hành vi này theo từng kênh.

Giới hạn

Kiểm soát truy cập

Tin nhắn trực tiếp

• channels.zalo.dmPolicy: pairing (mặc định) | allowlist | open | disabled.
• Ghép nối: người gửi không xác định nhận được mã ghép nối; tin nhắn bị bỏ qua cho đến khi được phê duyệt. Mã hết hạn sau 1 giờ.
  • openclaw pairing list zalo
  • openclaw pairing approve zalo <CODE>
  • Chi tiết: Ghép nối
• channels.zalo.allowFrom chấp nhận mã người dùng Zalo dạng số (không tra cứu tên người dùng). open yêu cầu "*".

Nhóm

Plugin hỗ trợ trò chuyện nhóm (chatTypes: ["direct", "group"]) và kiểm soát bằng yêu cầu đề cập cùng chính sách nhóm:

• channels.zalo.groupPolicy: open | allowlist | disabled.
• channels.zalo.groupAllowFrom giới hạn những mã người gửi có thể kích hoạt bot trong nhóm; dùng allowFrom làm phương án dự phòng khi chưa đặt.
• Cách phân giải mặc định: khi channels.zalo được cấu hình, groupPolicy chưa đặt sẽ được phân giải thành open. Khi hoàn toàn không có channels.zalo, thời gian chạy sẽ đóng an toàn về allowlist.
• Lưu ý đã được báo cáo trong thực tế: với một số thiết lập bot Marketplace, hoàn toàn không thể thêm bot vào nhóm. Nếu gặp trường hợp này, hãy xác minh bằng các thiết lập Zalo Bot Platform của bot; đây là hạn chế từ phía nền tảng, không phải chính sách của OpenClaw.

Thăm dò dài so với Webhook

• Mặc định: thăm dò dài (không yêu cầu URL công khai).
• Chế độ Webhook: đặt channels.zalo.webhookUrl và channels.zalo.webhookSecret.
  • URL Webhook phải sử dụng HTTPS.
  • Bí mật Webhook phải dài từ 8 đến 256 ký tự.
  • Zalo gửi sự kiện kèm tiêu đề X-Bot-Api-Secret-Token, được kiểm tra bằng phép so sánh thời gian hằng định.
  • HTTP của Gateway xử lý yêu cầu Webhook tại channels.zalo.webhookPath (mặc định là đường dẫn của URL Webhook).
  • Yêu cầu phải sử dụng Content-Type: application/json (hoặc loại phương tiện +json).
  • Theo tài liệu API của Zalo, thăm dò getUpdates và Webhook loại trừ lẫn nhau.

Các loại tin nhắn được hỗ trợ

• Văn bản: hỗ trợ đầy đủ, được chia thành các đoạn 2000 ký tự.
• Phương tiện: cả chiều đến và chiều đi, bị giới hạn bởi mediaMaxMb.
• Cảm xúc, luồng thảo luận, cuộc thăm dò ý kiến, lệnh gốc: Plugin không hỗ trợ.
• Truyền phát: Plugin khai báo khả năng truyền phát theo khối, nhưng Zalo không có các nút điều chỉnh chuyên biệt cho hàng đợi gửi đi/hợp nhất văn bản (không giống một số kênh khu vực khác); nếu điều này quan trọng đối với trường hợp sử dụng của bạn, hãy xác minh hành vi hiện tại trong môi trường của bạn.

Khả năng

Đích phân phối (CLI/Cron)

Sử dụng mã cuộc trò chuyện làm đích:

openclaw message send --channel zalo --target 123456789 --message "hi"

Khắc phục sự cố

Bot không phản hồi:

• Kiểm tra mã thông báo: openclaw channels status --probe
• Xác minh người gửi đã được phê duyệt (ghép nối hoặc allowFrom)
• Kiểm tra nhật ký Gateway: openclaw logs --follow

Webhook không nhận được sự kiện:

• Xác nhận URL Webhook sử dụng HTTPS
• Xác nhận bí mật dài từ 8 đến 256 ký tự
• Xác nhận điểm cuối HTTP của Gateway có thể truy cập được trên đường dẫn đã cấu hình
• Xác nhận thăm dò getUpdates không đồng thời chạy (chúng loại trừ lẫn nhau)
• Một đợt yêu cầu dồn dập có thể trả về HTTP 429 (120 yêu cầu / 60 giây cho mỗi đường dẫn+IP); hãy giãn nhịp và thử lại

Tham chiếu cấu hình

Cấu hình đầy đủ: Cấu hình

channels.zalo.botToken, channels.zalo.dmPolicy và các khóa cấp cao nhất dạng phẳng khác là dạng viết tắt cũ cho một tài khoản của các trường bên trên; cả hai dạng đều được hỗ trợ.

Tùy chọn môi trường: ZALO_BOT_TOKEN=... chỉ phân giải mã thông báo của tài khoản mặc định.

Liên quan

• Tổng quan về kênh - tất cả các kênh được hỗ trợ
• Ghép nối - quy trình xác thực và ghép nối tin nhắn trực tiếp
• Nhóm - hành vi trò chuyện nhóm và yêu cầu đề cập
• Định tuyến kênh - định tuyến phiên cho tin nhắn
• Bảo mật - mô hình truy cập và tăng cường bảo mật