🦞 zaloclaw

Unofficial OpenClaw plugin — Zalo Personal Account Channel

Connect your personal Zalo account to an AI agent with 147 full-featured actions.

Cài đặt · Tính năng · Cấu hình · 147 Actions · Cộng đồng

⚠️ Disclaimer — Dự án không chính thức

Dự án này không có liên kết, không được phê duyệt và không được tài trợ bởi Zalo hoặc VNG Corporation.

Zalo không cung cấp API chính thức cho tài khoản cá nhân và không cho phép tự động hóa tài khoản cá nhân theo Điều khoản dịch vụ. Plugin hoạt động thông qua thư viện reverse-engineered zca-js và có thể vi phạm ToS Zalo, dẫn đến tài khoản bị khóa hoặc đình chỉ.

Được cung cấp "as-is" cho mục đích nghiên cứu và tự động hóa cá nhân. Người dùng tự chịu toàn bộ rủi ro.

Tại sao zaloclaw?

Zalo (~75 triệu người dùng tại Việt Nam) không có API bot cho tài khoản cá nhân — chỉ có Zalo OA dành cho doanh nghiệp với nhiều hạn chế. ZaloClaw lấp khoảng trống đó bằng cách bridge tài khoản Zalo cá nhân với OpenClaw, cho phép hội thoại AI và tự động hóa toàn diện qua Zalo.

Cài đặt

Cách 1 — ClawHub (khuyến nghị)

openclaw plugins install clawhub:zaloclaw
openclaw gateway restart
openclaw channels login --channel zaloclaw
# → Quét QR code bằng app Zalo

Cách 2 — Clone thủ công

git clone https://github.com/monas-team/zaloclaw.git /path/to/zaloclaw
cd /path/to/zaloclaw && npm install
openclaw plugins install --link /path/to/zaloclaw
openclaw gateway restart
openclaw channels login --channel zaloclaw

Kiểm tra

openclaw status
# ✓ zaloclaw → ON

Yêu cầu: OpenClaw ≥ 2026.2.0 · Node.js ≥ 22 · Tài khoản Zalo cá nhân

Tính năng

Chi tiết nổi bật

• Mention gating — Bot chỉ phản hồi khi được @mention trong nhóm; có thể tắt per-group
• Image buffering — Nhớ ảnh từ tin nhắn không mention, dùng làm context khi được @tag sau
• Rich text — Markdown tự chuyển sang bold/italic/gạch chân/màu sắc Zalo
• Urgency levels — 1 = quan trọng 🔶, 2 = khẩn cấp 🔴
• Quote reply — AI nhận đầy đủ context tin nhắn được trích dẫn + người gửi

Cấu hình

File: ~/.openclaw/openclaw.json → key channels.zaloclaw

{
  "channels": {
    "zaloclaw": {
      "accounts": {
        "default": {
          "enabled": true,

          // Chính sách DM: open | pairing | allowlist | disabled
          "dmPolicy": "open",
          "allowFrom": ["*"],
          "denyFrom": [],

          // Chính sách nhóm: open | allowlist | disabled
          "groupPolicy": "open",

          // Override theo từng nhóm (dùng group ID hoặc "*" cho mặc định)
          "groups": {
            "*":          { "requireMention": true },
            "<group_id>": { "allow": true, "requireMention": false }
          }
        }
      }
    }
  }
}

DM Policy

147 Actions

Plugin expose một tool zaloclaw duy nhất với 147 actions. Tên người dùng và tên nhóm tự động resolve thành Zalo numeric ID. Xem đầy đủ tại docs/agent-help.md.

create-poll · vote-poll · lock-poll · get-poll-detail · add-poll-options · share-poll

Hỗ trợ: đa lựa chọn, thêm tùy chọn mới, ẩn danh, thời hạn tùy chỉnh.

create-reminder · edit-reminder · remove-reminder · list-reminders · get-reminder · get-reminder-responses

Quản lý hội thoại (16): Mute/unmute, pin/unpin, ẩn/hiện, tự xóa (1/7/14 ngày), lưu trữ, đánh dấu chưa đọc.

Tin nhắn nhanh & Auto-reply (8): CRUD quick messages + auto-reply rules (phạm vi: tất cả / người lạ / bạn bè cụ thể).

Hồ sơ & Tài khoản (14): me, update-profile, change-avatar, get-qr, last-online, get-biz-account, quản lý lịch sử avatar, v.v.

Danh mục & Sản phẩm (8): CRUD catalog và product — dành cho tài khoản shop/doanh nghiệp.

Tiện ích & Cài đặt (5): get/update-settings, update-active-status, parse-link, search-stickers, tra cứu hàng loạt SĐT.

Block/unblock user toàn cục và theo nhóm, allowlist, require-mention config per-group, trust management.

Kiến trúc

zaloclaw/
├── index.ts                    ← Entry point & tool registration
├── src/
│   ├── channel/
│   │   ├── channel.ts          ← Plugin lifecycle (start / stop / dock)
│   │   ├── monitor.ts          ← Inbound router & access control
│   │   ├── send.ts             ← Outbound dispatcher & markdown converter
│   │   ├── onboarding.ts       ← QR login flow
│   │   └── image-downloader.ts ← Media handler
│   ├── client/
│   │   ├── zalo-client.ts      ← zca-js wrapper (login, getApi, reconnect)
│   │   ├── credentials.ts      ← Credential persistence
│   │   └── accounts.ts         ← Multi-account resolver
│   ├── config/                 ← Schema validation & runtime config
│   ├── tools/tool.ts           ← 147 action handlers
│   └── features/               ← sticker · quote-reply · reaction-ack · …
└── docs/
    ├── agent-help.md           ← Full 147-action reference
    └── agent-install.md        ← Install guide

Message flow:

Zalo WS → zca-js → monitor.ts
                       │
                       ├─ Access control (block/allow/policy)
                       ├─ Mention gate  (skip → buffer image)
                       ├─ Media download
                       ├─ Context build (sender · quote · media)
                       └─ OpenClaw agent → send.ts → Zalo

Phát triển

npm run typecheck          # TypeScript check
npm run test               # Vitest test suite
npm run build              # esbuild → dist/index.js

# Dev — link trực tiếp, không cần build lại
openclaw plugins install --link .
openclaw gateway restart

Thêm action mới: Handler trong src/tools/tool.ts → wire vào monitor.ts / send.ts nếu cần → typecheck → restart.

Hạn chế đã biết

Ủng hộ đồng bào 🇻🇳

Nếu ZaloClaw có ích với bạn, hãy cân nhắc đóng góp cho Quỹ Cứu trợ Trung ương — Ủy ban MTTQ Việt Nam để hỗ trợ đồng bào bị thiên tai, lũ lụt.

Ngân hàng	Số tài khoản	Tên tài khoản	Chi nhánh	QR
Vietcombank	666.666.1010	Ủy ban TW MTTQ Việt Nam	Hà Nội
VietinBank	55102025	Ban Vận động Cứu trợ TW	—
BIDV	1200979797	Ủy ban TW MTTQ Việt Nam	Sở Giao dịch 1

⚠️ MTTQ đã cảnh báo về nhiều tài khoản giả mạo — chỉ chuyển vào 3 STK trên. Nguồn chính thức: mattran.org.vn

Giấy phép

MIT © monas-team