OpenClaw + Zalo: tự động hóa Zalo cá nhân và Zalo OA bằng AI agent

Zalo là kênh chat số 1 ở Việt Nam nhưng gần như không có giải pháp AI assistant ngon nào hỗ trợ tử tế. OpenClaw là một trong số ít công cụ mã nguồn mở hỗ trợ cả Zalo Official Account (OA) chính thống lẫn Zalo Personal qua zca-js. Bài này hướng dẫn cài đặt cả hai, kèm cảnh báo về TOS và lý do nên đặt gateway ở datacenter VN.

Hai loại Zalo channel trong OpenClaw - khác nhau hoàn toàn

Trước khi cấu hình, phải phân biệt rõ:

Hai cái này không thay thế lẫn nhau. Zalo OA dùng cho business (auto-reply khách, broadcast, chatbot). Zalo Personal dùng cho cá nhân (tự động hóa chat của chính bạn, summarize group, schedule message gửi từ số mình). Bạn có thể chạy song song cả hai trong cùng một OpenClaw gateway.

Phần 1: Cài Zalo Official Account (OA) - hợp pháp, dài hạn

Bước 1.1: Tạo Zalo OA

Vào oa.zalo.me, đăng nhập bằng số Zalo của bạn, tạo OA. Có hai tier:

• OA thường (miễn phí): gửi tin nhắn miễn phí cho user đã follow OA trong 7 ngày từ tương tác cuối.
• OA Premium: hết giới hạn 7 ngày, có template message, broadcast - tốn phí theo gói.

Bước 1.2: Tạo Zalo App và lấy credentials

Vào developers.zalo.me, tạo Application loại Official Account. Trong tab Official Account, link OA vừa tạo ở bước 1.1.

Trong Settings -> Advanced Settings -> API, tạo API key. Bạn cần 3 thứ:

• app_id
• app_secret
• access_token (refresh được, lifetime ngắn 25h)
• refresh_token (lifetime 90 ngày)

Bước 1.3: Cấu hình webhook

Zalo OA dùng webhook (không có long-polling như Telegram). Bắt buộc VPS phải có HTTPS public. Setup nhanh bằng Caddy:

sudo apt install -y caddy
sudo tee /etc/caddy/Caddyfile << 'EOF'
zalo.yourdomain.com {
    reverse_proxy localhost:7301
}
EOF
sudo systemctl reload caddy

Trong Zalo developer console, set Callback URL về https://zalo.yourdomain.com/webhook/zalo.

Bước 1.4: Thêm channel zalo vào OpenClaw

{
  "channels": {
    "zalo": {
      "enabled": true,
      "appId": "1234567890123456789",
      "appSecret": "AbCdEfGhIjKlMnOp",
      "oaAccessToken": "...",
      "oaRefreshToken": "...",
      "webhookPath": "/webhook/zalo",
      "webhookPort": 7301
    }
  }
}

Restart gateway, message một user follow OA của bạn - bot sẽ nhận event và reply qua LLM.

Phần 2: Cài Zalo Personal (zalouser) - tự động hóa số cá nhân

Phần này dùng plugin native zca-js (đã built-in OpenClaw, không cần external binary). Bạn dùng QR scan giống đăng nhập Zalo Web.

Bước 2.1: Bật channel zalouser

{
  "channels": {
    "zalouser": {
      "enabled": true,
      "imei": "auto",
      "sessionPath": "~/.openclaw/zalo-session.json",
      "dmPolicy": "pairing"
    }
  }
}

Restart gateway, gateway sẽ log một QR code ASCII to đùng:

journalctl --user -u openclaw-gateway -f | grep -A 30 "Scan QR"

Mở Zalo trên điện thoại -> menu -> Quét QR -> quét QR đó. Session lưu vào ~/.openclaw/zalo-session.json, lần sau gateway không cần scan lại.

Bước 2.2: Pair owner để bot biết bạn là chủ

Sau khi đăng nhập, gateway giờ là "phiên bản web" của số bạn. Bất kỳ ai nhắn cho bạn đều bị bot can thiệp. Để bot chỉ trả lời theo dmPolicy:

# Trên Zalo, tự gửi tin nhắn cho chính mình (Lưu trữ cá nhân)
# Bot sẽ trả lại mã pairing
openclaw pairing approve zalouser ABC123

Bước 2.3: Discover peers và group IDs

openclaw zalo directory list-friends
openclaw zalo directory list-groups

Output là JSON với userId, displayName, groupId. Lưu lại - bạn cần nó để target message chính xác trong skill.

Use case thực tế cho dân VN

Auto-reply khách hàng ngoài giờ (OA)

Skill business-hours-reply: lúc 0h-7h, bot tự nhận tin và trả lời theo template "Em ghi nhận, em sẽ phản hồi trong giờ hành chính", đẩy ticket vào Notion/Trello. Khi user nhắn lại trong giờ làm, bot escalate cho human agent.

Summarize Zalo group đông người (zalouser)

Group công ty 200 người chat ngộp suốt ngày. Skill zalo-summary mỗi cuối ngày grep tin nhắn trong group, gọi LLM tóm tắt 5 bullet, gửi vào "Lưu trữ cá nhân" của bạn:

---
name: zalo-daily-summary
description: Tóm tắt tin nhắn group Zalo công ty mỗi 18h hằng ngày
---

# Khi nào dùng
Skill này chạy tự động bởi scheduler lúc 18:00 ICT hằng ngày.

# Cách hoạt động
1. Lấy tin nhắn group ID 1234567890 từ 09:00 đến 18:00 hôm nay
2. Gọi LLM tóm tắt 5 ý chính, highlight @mention liên quan đến tôi
3. Gửi vào Lưu trữ cá nhân (Self chat) qua zalouser

Schedule gửi tin nhắn (zalouser)

"Gửi 8h sáng mai cho anh Tuấn câu chúc sinh nhật" - bot lên lịch, gửi từ chính số bạn. Hữu ích cho người bán hàng có hàng trăm khách cần follow-up đúng giờ.

Filter spam / chat nhóm KTX (zalouser)

Skill auto-mute group không quan trọng giờ đêm, nhưng vẫn alert nếu có message chứa keyword "khẩn", "shop", "hàng về".

Vì sao latency VPS VN quan trọng với Zalo

Zalo backbone đặt ở VN. Nếu gateway của bạn ở Singapore hay US, mỗi tin nhắn round-trip thêm 100-200ms. Bot trả chậm, user cảm nhận rõ. Đặt VPS ở datacenter VN, latency tới openapi.zalo.me và chat.zalo.me chỉ 5-15ms.

Test thực tế từ datacenter VN:

ping -c 5 openapi.zalo.me
# rtt min/avg/max = 4.2/5.1/6.8 ms

ping -c 5 chat.zalo.me
# rtt min/avg/max = 8.1/10.3/13.5 ms

Trong khi đó từ Singapore:

ping -c 5 openapi.zalo.me
# rtt min/avg/max = 52/58/68 ms

Khác biệt 50ms x 2 leg (in + out) là 100ms gain. Nhân với 4-5 round-trip (gateway -> LLM -> tool -> gateway -> Zalo) là gần 1 giây. Đó là khác biệt giữa bot "snappy" và bot "lag".

VPS sizing cho Zalo

Bảo mật session

zalo-session.json giữ session token tương đương login Zalo Web - rò rỉ là attacker chiếm cả tài khoản Zalo của bạn. Bắt buộc:

chmod 600 ~/.openclaw/zalo-session.json
# Nếu backup, encrypt
age -e -p ~/.openclaw/zalo-session.json > backup.age

Không bao giờ commit session lên git, không bao giờ share VPS root cho người lạ khi đã pair zalouser.

Gotchas Zalo trong thực tế

• OA quota: free tier 1000 message/tháng cho user ngoài 7 ngày tương tác. Vượt bị reject, không có warning rõ.
• Webhook signature: Zalo gửi header X-Zalo-Signature. OpenClaw verify mặc định, nhưng nếu bạn proxy qua Cloudflare có khi header bị strip - tắt cờ proxy cho subdomain webhook.
• zalouser ban: dùng nhiều IP khác nhau trong ngày = nghi vấn. Đặt static IP một VPS là an toàn nhất.
• QR session timeout: zca-js session có thể bị revoke khi bạn login Zalo Web ở chỗ khác. Khi gateway báo session expired, scan QR lại từ đầu.
• Tiếng Việt có dấu: một số terminal SSH render QR sai. Dùng tmux + UTF-8 locale (en_US.UTF-8 hoặc vi_VN.UTF-8).

Logging và debug Zalo channel

Khi bot Zalo không trả lời, thứ tự debug:

1. journalctl --user -u openclaw-gateway -f | grep zalo - xem có event vào không.
2. Nếu không có event: webhook URL sai, signature fail, hoặc Caddy chưa expose port. Test bằng curl -X POST https://zalo.yourdomain.com/webhook/zalo -d 'test', phải thấy 401 (signature missing) chứ không 502/504.
3. Nếu có event nhưng không reply: LLM provider down, hoặc rate limit hit. Check openclaw model status.
4. Nếu reply lỗi tiếng Việt loạn: check encoding terminal và locale trên VPS. LANG=vi_VN.UTF-8 là an toàn nhất.

Bật verbose log tạm:

OPENCLAW_LOG_LEVEL=debug systemctl --user restart openclaw-gateway

Log debug rất verbose, nhớ tắt khi xong (info) để tránh đầy ổ.

Chuyển dữ liệu Zalo ra ngoài

Nếu bạn muốn dùng AI assistant xử lý content Zalo sang nơi khác (Notion, Google Sheet, CRM), skill zalo-export:

• Mỗi tin khách nhắn OA, parse intent (đặt hàng / hỏi giá / khiếu nại), tạo ticket trong CRM.
• Mỗi cuối ngày, export chat của khách "hot" sang Google Sheet để sales follow-up.
• Schedule push notification ngược lại (qua OA broadcast) cho user đặt hàng nhưng chưa thanh toán sau 2 ngày.

OpenClaw cho phép chain skill: zalo-message-in -> nlp-intent -> crm-create-ticket -> zalo-reply. Cấu hình trong ~/.openclaw/workflows/customer-intake.yaml.

Tóm lại

OpenClaw là một trong số ít stack cho người Việt tự host được AI assistant chạy trên Zalo. Bắt đầu với OA (an toàn pháp lý) cho use case business, dùng zalouser cho cá nhân với số phụ. Đặt VPS ở datacenter VN để latency thấp - đây là channel mà user VN cảm nhận tốc độ rất rõ.

Đọc thêm bài giới thiệu OpenClaw là gì và cách self-host trên VPS nếu bạn chưa setup gateway. Bài tổng VPS cho vibe-coder có thêm context về stack toàn cảnh cho dev VN.