zaloclaw

Plugin kênh OpenClaw kết nối tài khoản Zalo cá nhân của bạn thành một kênh nhắn tin đầy đủ tính năng — sử dụng zca-js.

🤖 Dành cho AI Agent: Xem docs/agent-help.md — hướng dẫn đầy đủ sử dụng 147 actions với tham số, ví dụ, quy trình cập nhật và hướng dẫn lưu trữ. Tham khảo nhanh: TOOLS.md. Cài đặt: docs/agent-install.md.

🚀 Tham gia cộng đồng Zalo. Nhận plugin, cập nhật, và các use case tự động hóa thực tế. https://zalo.me/g/gigr4cnahvidpewxk74z

Tại sao cần zaloclaw?

Zalo là nền tảng nhắn tin phổ biến nhất Việt Nam (~75 triệu người dùng) nhưng không có API bot chính thức cho tài khoản cá nhân. Plugin này giải quyết vấn đề đó bằng cách kết nối tài khoản Zalo cá nhân với framework agent của OpenClaw — cho phép hội thoại AI, thực thi công cụ và tự động hóa trực tiếp qua Zalo chat.

Tính năng

Cốt lõi

• 147 Zalo API actions được mở ra dưới dạng công cụ agent — nhắn tin, bạn bè, nhóm, bình chọn, nhắc nhở, hồ sơ, danh mục sản phẩm, ghi chú, cài đặt, v.v.
• Đăng nhập QR code — xác thực qua terminal hoặc bảng điều khiển, thông tin đăng nhập tự động lưu
• Hỗ trợ DM & Nhóm — chính sách theo tài khoản: open, pairing, allowlist, disabled
• Mention gating — trong nhóm, bot chỉ phản hồi khi được @mention (cấu hình theo nhóm)
• Xử lý hình ảnh — tải và phân tích ảnh gửi kèm @mention; đệm ảnh từ tin nhắn không mention để sẵn sàng làm ngữ cảnh khi bot được mention sau

Tính năng tin nhắn

• Rich text — gửi tin nhắn có định dạng: đậm, nghiêng, gạch chân, gạch ngang, màu sắc (markdown tự động chuyển đổi)
• Mức độ khẩn cấp — đánh dấu tin nhắn quan trọng (urgency: 1) hoặc khẩn cấp (urgency: 2)
• Ngữ cảnh trả lời/trích dẫn — khi người dùng trả lời tin nhắn, AI nhận được nội dung và người gửi tin nhắn được trích dẫn
• Gửi file — gửi mọi loại file (PDF, doc, v.v.) qua đường dẫn local hoặc URL
• Xác nhận bằng reaction — react vào tin nhắn đến (cấu hình: heart, like, haha, v.v.)
• Trả lời trích dẫn — trả lời tin nhắn cụ thể với context threading
• Xác nhận đã đọc — đánh dấu tin nhắn đã đọc
• Hỗ trợ sticker — tìm kiếm và gửi sticker Zalo gốc qua agent tool calls
• Tự động thu hồi — thu hồi tin nhắn đã gửi
• Chỉ báo đang nhập — hiển thị trạng thái đang nhập khi xử lý

Kiểm soát truy cập

• Danh sách cho phép/chặn theo người dùng — toàn cục và theo nhóm
• Chế độ ghép nối — xác thực DM bằng mã cho người dùng chưa biết
• Chính sách nhóm — open, allowlist, hoặc disabled theo nhóm
• Phân quyền lệnh — giới hạn lệnh điều khiển cho người dùng được phép

Bắt đầu nhanh

Yêu cầu

• OpenClaw ≥ 2026.2.0
• Node.js ≥ 22
• Tài khoản Zalo cá nhân

Cài đặt

# Clone plugin
git clone https://github.com/monasprox/zaloclaw.git /path/to/zaloclaw

# Cài đặt dependencies
cd /path/to/zaloclaw && npm install

# Đăng ký với OpenClaw
openclaw plugins install --link /path/to/zaloclaw

# Khởi động lại gateway
openclaw gateway restart

Đăng nhập

# Hiển thị QR code trên terminal — quét bằng ứng dụng Zalo
openclaw channels login --channel zaloclaw

Sau khi quét, thông tin đăng nhập được lưu tự động. Các lần khởi động gateway sau sẽ tự động đăng nhập.

Xác minh

openclaw status

Bạn sẽ thấy zaloclaw trong danh sách channels với trạng thái ON.

Cấu hình

Toàn bộ cấu hình nằm trong ~/.openclaw/openclaw.json tại channels.zaloclaw.

Cấu hình tối thiểu

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

Ví dụ cấu hình đầy đủ

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

          // Chính sách truy cập DM
          "dmPolicy": "open",           // open | pairing | allowlist | disabled
          "allowFrom": ["*"],           // Zalo user IDs hoặc "*" cho tất cả
          "denyFrom": [],               // Chặn người dùng cụ thể

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

          // Ghi đè theo nhóm (key = group ID, tên nhóm, hoặc "*" cho mặc định)
          "groups": {
            "*": {
              "requireMention": true    // Mặc định: chỉ phản hồi khi được @mention
            },
            "123456789": {
              "allow": true,
              "requireMention": false,  // Luôn phản hồi trong nhóm này
              "allowUsers": [],         // Rỗng = cho phép tất cả
              "denyUsers": []
            }
          },

          // Hiển thị
          "markdown": {
            "tables": "bullets"         // off | bullets | code | block
          },
          "messagePrefix": "",
          "responsePrefix": ""
        }
      }
    }
  }
}

Tham chiếu cấu hình

Cài đặt tài khoản

Cài đặt theo nhóm (groups.<id>)

Chính sách DM

Công cụ Agent

Plugin cung cấp 147 actions dưới dạng một tool zaloclaw duy nhất. Agent chọn action bằng tên. Tên người dùng và tên nhóm tự động được chuyển đổi thành Zalo numeric IDs.

Nhắn tin (16 actions)

Bạn bè (16 actions)

Nhóm (22 actions)

Bình chọn (6 actions)

Nhắc nhở (6 actions)

Quản lý hội thoại (16 actions)

Tin nhắn nhanh & Tự động trả lời (8 actions)

Hồ sơ & Tài khoản (14 actions)

Cài đặt (3 actions)

Sticker & Khác (3 actions)

Ghi chú & Nhãn (4 actions)

Danh mục & Sản phẩm (8 actions)

Chặn Zalo (2 actions)

Cấu hình Bot — Lớp OpenClaw (13 actions)

Tiện ích (3 actions)

Kiến trúc

zaloclaw/
├── index.ts                    → Điểm vào plugin & đăng ký tool
├── package.json
├── openclaw.plugin.json        → Manifest plugin (JSON Schema cho cấu hình)
│
├── src/
│   ├── channel/                → Vòng đời kênh & luồng tin nhắn
│   │   ├── channel.ts          → Định nghĩa plugin, khởi động/dừng tài khoản, dock
│   │   ├── monitor.ts          → Xử lý & định tuyến tin nhắn đến
│   │   ├── send.ts             → Gửi tin nhắn đi & markdown
│   │   ├── onboarding.ts       → Luồng đăng nhập QR code (bảng điều khiển)
│   │   ├── image-downloader.ts → Xử lý tải media
│   │   └── probe.ts            → Kiểm tra sức khỏe kết nối
│   │
│   ├── client/                 → Wrapper API Zalo & quản lý tài khoản
│   │   ├── zalo-client.ts      → Vòng đời API zca-js (login, getApi, v.v.)
│   │   ├── credentials.ts      → Lưu trữ thông tin đăng nhập (đọc/ghi file)
│   │   ├── accounts.ts         → Phân giải đa tài khoản
│   │   ├── qr-display.ts       → Hiển thị QR code trên terminal
│   │   └── friend-request-store.ts → Theo dõi lời mời kết bạn
│   │
│   ├── config/                 → Schema cấu hình & quản lý
│   │   ├── config-schema.ts    → Schema Zod với gợi ý UI cho bảng điều khiển
│   │   └── config-manager.ts   → Đọc/ghi cấu hình runtime (openclaw.json)
│   │
│   ├── tools/                  → Định nghĩa công cụ agent
│   │   └── tool.ts             → 147 action handlers
│   │
│   ├── features/               → Các module tính năng độc lập
│   │   ├── auto-unsend.ts      → Thu hồi tin nhắn
│   │   ├── msg-id-store.ts     → Ánh xạ Message ID ↔ cliMsgId
│   │   ├── quote-reply.ts      → Hỗ trợ trả lời tin nhắn
│   │   ├── reaction-ack.ts     → Xác nhận reaction
│   │   ├── read-receipt.ts     → Xử lý xác nhận đã đọc
│   │   └── sticker.ts          → Tìm kiếm, cache & gửi sticker
│   │
│   ├── parsing/                → Xử lý văn bản
│   │   └── mention-parser.ts   → Phát hiện @mention & phân giải mention đi
│   │
│   ├── safety/                 → Bảo vệ đầu ra
│   │   ├── output-filter.ts    → Lọc nội dung nhạy cảm khỏi phản hồi
│   │   └── thread-sandbox.ts   → Cô lập thread
│   │
│   └── runtime/                → Trạng thái runtime chia sẻ
│       ├── runtime.ts          → Singleton môi trường runtime
│       ├── types.ts            → Định nghĩa kiểu TypeScript
│       └── status-issues.ts    → Báo cáo trạng thái sức khỏe
│
├── docs/
│   └── FEATURES.md             → Đặc tả tính năng & ghi chú API zca-js
│
├── .github/
│   ├── workflows/ci.yml        → CI: install + typecheck trên Node 22/24
│   └── ISSUE_TEMPLATE/         → Template báo lỗi & yêu cầu tính năng
│
├── CHANGELOG.md
├── CONTRIBUTING.md
├── SECURITY.md
├── CODE_OF_CONDUCT.md
├── LICENSE                     → MIT
└── .editorconfig

Luồng tin nhắn

Zalo → sự kiện zca-js → monitor.ts
  ├── Trích xuất ngữ cảnh trả lời/trích dẫn (nội dung + người gửi)
  ├── Kiểm soát truy cập (chặn/cho phép, chính sách DM, chính sách nhóm)
  ├── Mention gating (nhóm: bỏ qua nếu không @mention → đệm)
  ├── Xử lý hình ảnh (chỉ tải khi được mention hoặc DM)
  ├── Tổng hợp ngữ cảnh (thông tin người gửi, tin nhắn đệm, media, trích dẫn)
  ├── Định dạng envelope → gửi đến OpenClaw agent
  └── Phản hồi agent → send.ts → Zalo

Phát triển

# Kiểm tra kiểu
npm run typecheck

# Kiểm tra local
openclaw plugins install --link .
openclaw gateway restart
openclaw status

Không cần bước build — OpenClaw tải trực tiếp file .ts qua runtime.

Thêm tính năng mới

1. Tạo module trong thư mục con src/ phù hợp
2. Kết nối vào monitor.ts (cho tin đến) hoặc send.ts (cho tin đi)
3. Nếu cần tool action, thêm handler trong src/tools/tool.ts
4. Chạy npm run typecheck để xác minh
5. Kiểm tra với openclaw gateway restart

Hạn chế

• Một tài khoản mỗi instance plugin — đa tài khoản được hỗ trợ về cấu trúc nhưng chưa được kiểm thử
• Không hỗ trợ streaming — zca-js không hỗ trợ phản hồi streaming (blockStreaming: true)
• Giới hạn tốc độ — Zalo có thể hạn chế hoặc chặn tài khoản gửi tin nhắn nhiều
• Ổn định phiên — phiên zca-js có thể hết hạn; cần đăng nhập lại bằng QR khi cookie hết hạn
• Không mã hóa đầu cuối — tin nhắn đi qua máy chủ Zalo như bình thường
• Message TTL — tự hủy tin nhắn (messageTtl) được gửi tới Zalo API nhưng có thể không được áp dụng phía server; sử dụng set-auto-delete-chat cho tự động xóa cấp hội thoại

Giấy phép

MIT © monasprox