openclaw-zalo-setup

Kết nối tài khoản Zalo cá nhân với OpenClaw chỉ với 3 lệnh đơn giản.

🌐 English version — This README starts with Vietnamese because most Zalo users are in Vietnam. English content follows below.

Cài đặt nhanh

npm install -g openclaw-zalo-setup

Hướng dẫn sử dụng

Bước 1: Đăng nhập Zalo

openclaw-zalo login

Lệnh này sẽ:

• Tạo QR code thành file ảnh và tự mở bằng app mặc định
• Chờ bạn quét bằng ứng dụng Zalo trên điện thoại
• Tự động lưu credentials vào ~/.openclaw/credentials/zalouser/

Tuỳ chọn:

openclaw-zalo login --account personal     # Chỉ định tên account

Bước 2: Cấu hình OpenClaw

openclaw-zalo setup

Lệnh này sẽ:

• Kiểm tra credentials đã tồn tại
• Tự động cấu hình channels.zalouser trong openclaw.json
• Bật plugin zalouser
• Thêm binding để định tuyến tin nhắn Zalo tới agent của bạn
• Tự động backup config gốc trước khi thay đổi

Tuỳ chọn:

openclaw-zalo setup --account personal --name "Zalo của tôi" --agent lumis

Bước 3: Kiểm tra trạng thái

openclaw-zalo status

Hiển thị:

• Thư mục và file credentials
• Trạng thái file config
• Cấu hình channel, plugin, và binding
• Tổng quan tình trạng setup

Bước 4: Khởi động lại Gateway

Sau khi setup xong, cần restart gateway:

systemctl --user restart openclaw-gateway.service

Bắt đầu nhanh (3 bước)

# Bước 1: Cài đặt
npm install -g openclaw-zalo-setup

# Bước 2: Đăng nhập & Cấu hình
openclaw-zalo login
openclaw-zalo setup

# Bước 3: Khởi động lại
systemctl --user restart openclaw-gateway.service

Tính năng

• QR Login: Đăng nhập Zalo qua QR code ảnh, tự động mở bằng app mặc định
• Quản lý credentials: Tự động lưu vào đúng thư mục
• Auto-Config: Tự động cập nhật openclaw.json với cấu hình channel, plugin, binding
• Kiểm tra trạng thái: Xem tình trạng setup bất cứ lúc nào
• Dễ sử dụng: Interactive prompts và thông báo lỗi rõ ràng

Cách hoạt động

CLI này sử dụng zca-js (thư viện đăng nhập Zalo) để:

1. Tạo QR code đăng nhập Zalo
2. Lưu credentials vào ~/.openclaw/credentials/zalouser/
3. Tự động cấu hình openclaw.json

Yêu cầu

• Node.js >= 18.0.0
• OpenClaw đã cài đặt và khởi tạo

Xử lý sự cố

"Không tìm thấy credentials"

Chạy openclaw-zalo login trước để tạo credentials.

Config errors

Tool tự động backup config với timestamp trước khi thay đổi (file dạng openclaw.backup.YYYY-MM-DDTHH-mm-ss.json). Khôi phục từ bản backup mới nhất:

ls -t ~/.openclaw/openclaw.json.backup.*.json | head -1 | xargs cp {} ~/.openclaw/openclaw.json

Ảnh QR không tự mở

Một số môi trường không có GUI (SSH/headless) sẽ không tự mở được. Hãy mở thủ công file QR theo đường dẫn tool in ra.

English Version

Easy Zalo personal account setup for OpenClaw. Connect your Zalo account to an OpenClaw agent in 3 simple commands.

Quick Start

npm install -g openclaw-zalo-setup
openclaw-zalo login
openclaw-zalo setup
systemctl --user restart openclaw-gateway.service

When running openclaw-zalo login, the tool:

• Saves the QR code as an image file and opens it with your default app
• Waits for scanning from the Zalo app
• Automatically saves credentials to ~/.openclaw/credentials/zalouser/

How It Works

This CLI wraps zca-js (Zalo login library) to:

1. Generate a QR image for Zalo login and auto-open it
2. Save credentials to ~/.openclaw/credentials/zalouser/
3. Auto-configure openclaw.json with the correct channel, plugin, and binding structure

Commands

| Command | Description | |---------|-------------| | openclaw-zalo login | Login to Zalo via QR code | | openclaw-zalo setup | Auto-configure openclaw.json for Zalo channel | | openclaw-zalo status | Check Zalo setup status |

Requirements

• Node.js >= 18.0.0
• OpenClaw installed and initialized

Troubleshooting

• "No credentials found" — Run openclaw-zalo login first
• Config errors — Tool creates timestamped backups (openclaw.json.backup.TIMESTAMP.json). Restore from the latest one:

  ls -t ~/.openclaw/openclaw.json.backup.*.json | head -1 | xargs cp {} ~/.openclaw/openclaw.json

• QR image does not open automatically — Open the printed QR file path manually on your device

License

MIT