🦞 OpenClaw Zalo Connect

Kết nối nhiều tài khoản Zalo cá nhân với nhiều AI agent trong cùng một OpenClaw

Mỗi tài khoản có session, API client, listener và tuyến phản hồi riêng — đăng nhập QR, chạy đồng thời, không cần Zalo OA.

Một Zalo cho bán hàng, một Zalo cho vận hành, một Zalo cho cộng đồng — mỗi tài khoản có thể gắn với một agent, tính cách và workspace khác nhau nhưng vẫn chạy chung một OpenClaw Gateway.

✨ Vì sao có OpenClaw Zalo Connect?

Các plugin Zalo cá nhân ban đầu đã chứng minh zca-js có thể kết nối Zalo với OpenClaw. OpenClaw Zalo Connect tiếp tục nền tảng đó theo hướng một channel runtime được duy trì lâu dài cho hệ sinh thái OpenClaw, tập trung vào vận hành đa agent, cài đặt ổn định và khả năng phối hợp với plugin khác.

Những cải tiến nổi bật trong v3.0.0

• 👥 Multi-account thật, phục vụ multi-agent — chạy nhiều tài khoản Zalo cá nhân cùng lúc trong một gateway. Mỗi accountId có credential, API instance, listener, keepalive và outbound route riêng.
• 🧭 Định tuyến đúng agent — binding channel + accountId → agentId bảo đảm tin nhắn của từng tài khoản đi vào đúng agent/workspace, không dùng chung ngữ cảnh hoặc gửi nhầm từ tài khoản khác.
• 📦 Bản cài self-contained — zca-js và các thư viện JavaScript cần thiết được bundle vào dist; cài từ Git không còn phải chạy npm install bổ sung hay gặp lỗi thiếu module lúc gateway khởi động.
• ⚡ Bridge service v6 cho plugin sibling — Zalo Mod và các plugin OpenClaw khác có thể đọc trạng thái, thực thi action, nhận inbound event và đổi group policy trực tiếp mà không patch file runtime.
• 🕘 Kéo lịch sử chat về, kể cả tin nhắn riêng — Zalo đẩy lại tin cũ qua WebSocket (request-old-messages), phát trên kênh bridge riêng để hàng trăm tin cũ không lọt vào đường dispatch và khiến bot trả lời hàng loạt tin cũ.
• ⌨️ Kênh "đang soạn tin" — sự kiện typing được phát cho plugin tiêu thụ, đủ để dựng chỉ báo giống Zalo Web mà không phải hỏi liên tục.
• 🕊️ Free / Silent / Mute trước model — runtime group policy có thể chặn tin không phù hợp ngay tại inbound pipeline, trước khi dispatch tới AI và trước khi tốn token.
• 🧠 Passive context cho hội thoại nhóm — thu thập ngữ cảnh nhóm zero-token; khi người dùng gọi bot sau một đoạn chat im lặng, plugin tích hợp có thể đưa phần liên quan vào lượt trả lời thay vì để agent “mới thức dậy”.
• 🏷️ Mention Zalo native — nhận biết mention bot, reply mention đúng UID và chuyển @Tên/@[Tên đầy đủ] thành mention thật khi gửi vào nhóm.
• 🧵 Inbound ổn định hơn — queue theo từng cuộc trò chuyện, chống message trùng, giới hạn concurrency, timeout, bỏ message quá cũ và keepalive riêng cho từng tài khoản.
• 🛡️ Kiểm soát truy cập nhiều lớp — DM/group policy, allow/deny theo user, mention gate, injection guard, URL validation và sandbox cho file local.
• 🧰 149 Zalo actions — nhắn tin, media, reaction, bạn bè, nhóm, poll, reminder, profile, quick message, auto-reply, catalog và nhiều thao tác khác.

Khác gì so với nền tảng zaloclaw tại thời điểm fork?

Bảng trên mô tả khác biệt tại thời điểm dự án được fork và phát triển thành v3.0.1. Dự án gốc có thể tiếp tục thay đổi độc lập.

🚀 Cài đặt nhanh

Cách 1 — Dùng OpenClaw Setup (khuyên dùng)

OpenClaw Setup tự tải đúng release, tạo channel/binding và hiển thị QR đăng nhập ngay trên giao diện:

npx create-openclaw-bot

Trong dashboard, chọn Zalo cá nhân khi tạo bot hoặc bấm Đăng nhập Zalo. Nếu plugin đã có, Setup sẽ dùng lại thay vì tải lại mỗi lần login/restart.

Cách 2 — Cài trực tiếp release từ Git

Yêu cầu máy đã có Git, Node.js 22+ và OpenClaw:

git clone --depth 1 --branch v3.1.0 \
  https://github.com/tuanminhhole/openclaw-zalo-connect.git

openclaw plugins install ./openclaw-zalo-connect
openclaw gateway restart
openclaw channels login --channel zalo-connect --account default

Không cần chạy npm install: release chứa sẵn bundle runtime hoàn chỉnh.

Cách 3 — Link source để phát triển

git clone https://github.com/tuanminhhole/openclaw-zalo-connect.git
cd openclaw-zalo-connect
npm install
npm run build
openclaw plugins install --link .
openclaw gateway restart

Đăng nhập QR

1. Chạy lệnh login hoặc mở QR trong OpenClaw Setup.
2. Trên Zalo mobile, mở Trang cá nhân → biểu tượng QR.
3. Quét mã và xác nhận đăng nhập trên điện thoại.
4. Restart gateway nếu OpenClaw yêu cầu.

# Tài khoản mặc định
openclaw channels login --channel zalo-connect --account default

# Tài khoản thứ hai
openclaw channels login --channel zalo-connect --account mkt

👥 Chạy nhiều Zalo cá nhân với nhiều agent

Ví dụ hai tài khoản Zalo chạy đồng thời và đi vào hai agent khác nhau:

{
  "channels": {
    "zalo-connect": {
      "enabled": true,
      "defaultAccount": "default",
      "dmPolicy": "open",
      "groupPolicy": "open",
      "accounts": {
        "default": { "enabled": true, "name": "Williams 2" },
        "mkt":     { "enabled": true, "name": "MKT" }
      }
    }
  },
  "bindings": [
    {
      "agentId": "williams-2",
      "match": { "channel": "zalo-connect", "accountId": "default" }
    },
    {
      "agentId": "mkt",
      "match": { "channel": "zalo-connect", "accountId": "mkt" }
    }
  ]
}

Credential được lưu tách biệt:

~/.openclaw/zalo-connect-credentials.json       # account default
~/.openclaw/zalo-connect-credentials-mkt.json   # account mkt

Kiểm tra trạng thái:

openclaw channels status --json

Mỗi account phải hiện configured: true, running: true và không có lastError.

⚙️ Cấu hình channel

File ~/.openclaw/openclaw.json:

{
  "channels": {
    "zalo-connect": {
      "enabled": true,
      "dmPolicy": "pairing",       // pairing | allowlist | open | disabled
      "allowFrom": [],
      "groupPolicy": "allowlist", // allowlist | open | disabled
      "groups": {
        "*":          { "enabled": false, "requireMention": true },
        "<group_id>": { "enabled": true,  "requireMention": true }
      }
    }
  }
}

Khuyến nghị khi mới cài:

• Dùng dmPolicy: "pairing" thay vì mở toàn bộ DM.
• Dùng groupPolicy: "allowlist" và chỉ bật các group cần thiết.
• Bật requireMention nếu bot không cần phản hồi mọi tin nhắn nhóm.
• Không chia sẻ file credential hoặc commit nó lên Git.

🧠 Passive Collector — nhớ ngữ cảnh nhóm mà không tốn token

Passive Collector ghi message nhóm vào JSONL local. Việc thu thập không gọi model và không cần Elasticsearch hay dịch vụ bên ngoài:

{
  "plugins": {
    "entries": {
      "zalo-connect": {
        "config": {
          "passiveCollector": { "enabled": true }
        }
      }
    }
  }
}

~/.openclaw/workspace/zalo-connect/passive/<groupId>.jsonl

Agent có thể đọc lại bằng action recall-group-history, hỗ trợ groupId, query và count.

Khi dùng cùng OpenClaw Zalo Mod, inbound bridge còn có thể giữ đoạn chat khi group ở Silent Mode và bổ sung phần liên quan vào lượt người dùng tag bot sau đó.

🧰 Tính năng và 149 actions

Danh sách tham số và ví dụ đầy đủ: docs/actions.md

Hướng dẫn chi tiết: docs/guide.md

🔌 Bridge service v6

Zalo Connect expose một contract nhỏ cho plugin cùng process:

getStatus(accountId)
listActions(accountId)
executeAction(accountId, action)
setGroupPolicy(accountId, groupId, mode)
getGroupPolicy(accountId, groupId)
clearGroupPolicy(accountId, groupId)
subscribeInbound(handler)
subscribeHistory(handler)   // v5 — lô tin cũ kéo về từ Zalo, kèm `fromSelf`
subscribeTyping(handler)    // v6 — "đang soạn tin", sống ~3 giây

Ba kênh tách rời chứ không phải một luồng kèm cờ phân loại. Lịch sử và inbound đi chung đường thì một lần kéo lịch sử — hàng trăm tin — sẽ chạy qua mention gate rồi dispatch cho model, tức là bot trả lời hàng loạt tin từ tuần trước, gửi thật vào nhóm khách. Tách kênh khiến sự cố đó không thể xảy ra do sơ ý.

Bên tiêu thụ nên kiểm typeof svc.subscribeHistory === 'function' lúc gọi, không phải lúc khởi tạo: thứ tự nạp giữa hai plugin không được đảm bảo.

Handler inbound có thể trả true hoặc { handled: true } để xác nhận đã xử lý tin nhắn trước mention gate. Nhờ đó slash command chạy tức thì, không gọi model và không phát sinh câu trả lời trùng từ agent.

Bridge giúp OpenClaw Zalo Mod thực hiện moderation và đổi Free/Silent/Mute tức thời mà không import file bundle, không patch zca-js và không sửa config cho mỗi lần toggle.

🏗️ Kiến trúc

Zalo account: default ─┐
                       ├─ Zalo Connect ─ account router ─ OpenClaw bindings ─ agent/workspace
Zalo account: mkt ─────┘        │
                                ├─ access policy + mention gate
                                ├─ thread queue + dedup + timeout
                                ├─ passive collector
                                ├─ bridge service v6
                                └─ 149 actions + outbound sender

index.ts                    Plugin + channel + tool registration
src/channel/monitor.ts      Inbound pipeline và listener từng account
src/channel/send.ts         Outbound, media, markdown và native mention
src/client/zalo-client.ts   API client map theo accountId
src/client/credentials.ts   Credential riêng cho từng accountId
src/runtime/bridge.ts       Contract tích hợp plugin sibling
src/tools/tool.ts           149 Zalo actions

🧪 Phát triển và kiểm thử

npm install
npm run typecheck
npm test
npm run build

Bản v3.1.0 hiện có 175 automated tests cho parsing, send, bridge, media, credential và các thành phần an toàn. Multi-account cũng đã được kiểm tra thực tế với hai Zalo cá nhân chạy đồng thời và tự kết nối lại sau gateway restart.

Xem CONTRIBUTING.md nếu muốn gửi PR.

⚠️ Lưu ý và giới hạn

• Đây là tích hợp không chính thức, không liên kết với Zalo hoặc VNG.
• Zalo không cung cấp public API cho tự động hóa tài khoản cá nhân. Plugin dùng thư viện reverse-engineered zca-js; việc sử dụng có thể không phù hợp với điều khoản Zalo và có nguy cơ hạn chế tài khoản.
• Protocol, cookie hoặc QR flow có thể thay đổi khi Zalo cập nhật.
• Gửi quá nhanh hoặc tự động hóa quá mức có thể bị rate limit. Hãy dùng tài khoản thử nghiệm, giới hạn tần suất và luôn có người giám sát.

🙏 Nguồn gốc và ghi công

OpenClaw Zalo Connect bắt đầu từ mã nguồn MIT của monas-team/zaloclaw. Cảm ơn monas-team, các contributor của dự án gốc và đội ngũ zca-js đã xây dựng nền tảng kết nối ban đầu.

Từ nhánh fork, dự án được thiết kế và duy trì lại bởi tuanminhhole (Kent) với định danh package, channel, multi-account runtime, bridge service, inbound pipeline, passive context, tài liệu và quy trình phát hành riêng cho hệ sinh thái OpenClaw.

Giấy phép MIT và thông báo bản quyền của dự án gốc tiếp tục được giữ trong LICENSE.

🦞 Hệ sinh thái OpenClaw cùng tác giả

🚀 Cài đặt và nền tảng

• openclaw-setup — Web UI tạo, triển khai và vận hành bot OpenClaw trên Docker.
• vietbrain — Bộ khung “Bộ Não Thứ Hai” tiếng Việt cho Obsidian và AI agent.

🔌 Channel và runtime plugin

• openclaw-zalo-connect — repo này; channel Zalo cá nhân đa account/đa agent.
• openclaw-zalo-mod — quản trị nhóm Zalo zero-token, slash command, anti-spam, warn và memory.
• openclaw-fb-messenger — channel Facebook Messenger qua webhook và Graph API.
• openclaw-telegram-multibot-relay — relay, delegation và cron cho đội bot Telegram.
• openclaw-browser-automation — Smart Search và Browser Automation.
• openclaw-facebook-crawler — thu thập dữ liệu Facebook phục vụ agent workflow.
• openclaw-n8n-facebook-poster — tự động đăng Facebook qua n8n.

🧩 Skill

• openclaw-skill-learning-memory — bộ nhớ dài hạn và khả năng tự đóng gói kỹ năng cho agent.
• openclaw-skill-infographic — tạo infographic bằng AI.

📄 Giấy phép

MIT — mã nguồn mở, giữ đầy đủ ghi công và thông báo bản quyền gốc.

Nếu dự án hữu ích, hãy ⭐ repo để nhiều người trong cộng đồng OpenClaw tìm thấy hơn.

_{🦞 <b>OpenClaw Zalo Connect</b> · một phần của hệ sinh thái <a href="https://github.com/tuanminhhole">tuanminhhole (Kent)</a> · không liên kết với Zalo/VNG}