Zalo ClawBot

OpenClaw kết nối với Zalo ClawBot thông qua Plugin bên ngoài @zalo-platforms/openclaw-zaloclawbot có trong danh mục. Quá trình đăng nhập sử dụng mã QR của Zalo Mini App; ID Plugin trong cấu hình là openclaw-zaloclawbot.

Khả năng tương thích

Điều kiện tiên quyết

• Node.js >= 22
• Đã cài đặt OpenClaw (có thể sử dụng CLI openclaw)
• Một tài khoản Zalo trên thiết bị di động để quét mã QR đăng nhập

Cài đặt bằng quy trình thiết lập ban đầu (khuyến nghị)

openclaw onboard

Chọn Zalo ClawBot trong trình đơn kênh. Trình hướng dẫn sẽ cài đặt Plugin từ danh mục chính thức (đã xác minh tính toàn vẹn), hiển thị mã QR đăng nhập trong terminal và hoàn tất thiết lập kênh sau khi bạn quét mã bằng ứng dụng Zalo.

Cài đặt thủ công

Để thêm kênh vào một Gateway đã hoàn tất thiết lập ban đầu:

1. Cài đặt Plugin

openclaw plugins install "@zalo-platforms/openclaw-zaloclawbot@0.1.4"

Hãy sử dụng chính xác phiên bản cố định này để OpenClaw xác minh gói dựa trên hàm băm toàn vẹn trong danh mục khi cài đặt.

2. Bật Plugin trong cấu hình

openclaw config set plugins.entries.openclaw-zaloclawbot.enabled true

3. Tạo mã QR và đăng nhập

openclaw channels login --channel openclaw-zaloclawbot

Quét mã QR hiển thị trong terminal bằng ứng dụng Zalo trên thiết bị di động, chấp nhận Điều khoản sử dụng bên trong Zalo Mini App và cấp quyền cho phiên.

4. Khởi động lại Gateway

openclaw gateway restart

Cách thức hoạt động

Không giống kênh Zalo tiêu chuẩn, vốn yêu cầu bạn đăng ký Zalo Official Account (OA) riêng và cấu hình thông tin xác thực tĩnh dành cho nhà phát triển, Zalo ClawBot là một trợ lý cá nhân gắn với chủ sở hữu trên hạ tầng chính thức dùng chung:

1. Thiết lập ban đầu: mã QR dẫn đến một Zalo Mini App, ứng dụng này liên kết trực tiếp một bot riêng tư mới được cấp phát dưới một OA chính thức dùng chung với ID người dùng Zalo của bạn.
2. Quyền riêng tư gắn với chủ sở hữu: bot chỉ giao tiếp với chủ sở hữu. Tin nhắn từ người dùng khác bị loại bỏ ở cấp nền tảng.
3. Đường dẫn API chính thức: Plugin sử dụng API của Zalo Bot Platform, không sử dụng tự động hóa trình duyệt hoặc phiên web.

Cơ chế bên trong

Plugin giao tiếp với Zalo qua một vòng lặp long-polling liên tục (getUpdates). Webhook mặc định bị vô hiệu hóa đối với các phiên chạy Gateway cục bộ trên máy tính hoặc terminal. Tin nhắn được xử lý ở phía máy khách và ánh xạ đến môi trường thực thi tác tử cục bộ của bạn.

Plugin quản lý thông tin xác thực của bot trong thư mục trạng thái OpenClaw. Hãy coi thư mục này là dữ liệu nhạy cảm và áp dụng cho nó cùng chính sách kiểm soát truy cập và sao lưu như phần còn lại của trạng thái OpenClaw.

Môi trường thực thi của Plugin này nằm hoàn toàn trong gói bên ngoài @zalo-platforms/openclaw-zaloclawbot; các chi tiết hành vi bên dưới ngoài phạm vi cài đặt/cấu hình được trình bày theo thông tin từ những người bảo trì Plugin và chưa được xác minh dựa trên mã nguồn lõi OpenClaw.

Khắc phục sự cố

• Hết thời gian đăng nhập bằng mã QR: vì lý do bảo mật, mã thông báo đăng nhập (zbsk) hết hạn sau 5 phút. Nếu mã QR hết hạn trước khi bạn quét, hãy chạy lại lệnh đăng nhập để tạo mã mới.
• Gateway không tải được: hãy xác nhận phiên bản máy chủ OpenClaw của bạn là 2026.4.10 trở lên. Các phiên bản cũ hơn không hỗ trợ sổ theo dõi cài đặt Plugin npm bên ngoài mà ID này yêu cầu.

Nội dung liên quan

• Tổng quan về các kênh - tất cả các kênh được hỗ trợ
• Zalo - kênh Zalo Bot Creator / Marketplace được đóng gói sẵn
• Ghép nối - quy trình xác thực tin nhắn trực tiếp và ghép nối
• Plugin - cài đặt và quản lý các Plugin