zalo-agent-cli

Công cụ CLI tự động hóa Zalo — đa tài khoản, proxy, chuyển khoản ngân hàng, thanh toán QR. Xây dựng trên zca-js.

Tiếng Việt | English

[!WARNING] Tool này sử dụng API Zalo không chính thức (zca-js). Zalo không hỗ trợ và tài khoản của bạn có thể bị khóa hoặc ban. Tự chịu trách nhiệm. Không liên kết với Zalo hay VNG. Xem DISCLAIMER.md.

[!TIP] AI Agent Skill — Dùng với OpenClaw, Claude Code, hoặc bất kỳ agent nào hỗ trợ SKILL.md:

clawhub install zalo-agent          # OpenClaw (từ ClawHub registry)
cp -r skill/ ~/.claude/skills/zalo-agent/   # Claude Code

15+ nhóm lệnh · listen mode + webhook · 55+ ngân hàng VN · đa tài khoản + proxy Xem skill/SKILL.md · Eval scenarios

[!NOTE] Zalo Official Account (OA) — v1.1.0 hỗ trợ Zalo OA API v3.0 chính thức:

zalo-agent oa init                                    # Setup wizard (interactive)
zalo-agent oa init --app-id <ID> --secret <KEY> --skip-webhook  # Non-interactive (AI agent)
zalo-agent oa whoami                                  # Xem thông tin OA
zalo-agent oa msg text <user-id> "Xin chào"           # Gửi tin nhắn
zalo-agent oa listen -p 3000                           # Webhook listener

OAuth login · gửi tin nhắn · quản lý follower · tag · webhook listener · VPS support Xem docs/official-account.md

[!TIP] MCP Server (AI Agent Integration) — v1.2.0 hỗ trợ Model Context Protocol cho Claude Code và các MCP client:

zalo-agent mcp start              # stdio (local Claude Code)
zalo-agent mcp start --http 3847 --auth your-secret  # HTTP (VPS)

4 tools: get_messages · send_message · list_threads · mark_read Auto-reconnect · thread filter · noise reduction · group notifications Xem MCP Guide

Cài đặt

npm install -g zalo-agent-cli

Bắt đầu nhanh

1. Đăng nhập

zalo-agent login

Quét QR bằng Zalo app > Quét mã QR. Thông tin tự động lưu.

2. Tìm bạn bè

zalo-agent friend search "Phúc"

3. Lắng nghe tin nhắn (lấy thread ID)

zalo-agent listen

Mỗi tin nhắn đến sẽ hiện threadId. Dùng --json để lấy dạng JSON.

4. Gửi tin nhắn

# Gửi cho cá nhân
zalo-agent msg send <THREAD_ID> "Xin chào!"

# Gửi vào nhóm
zalo-agent msg send <THREAD_ID> "Xin chào nhóm!" -t 1

Danh sách lệnh

Tất cả lệnh hỗ trợ --json. Tài liệu đầy đủ: Wiki

| Nhóm lệnh | Mô tả | Docs | |------------|--------|------| | msg | Gửi tin nhắn, hình, file, voice, video, sticker, link, thẻ chuyển khoản, QR | Tin nhắn | | friend | Danh sách, tìm, thêm, xóa, chặn, biệt danh, gợi ý | Bạn bè | | group | Tạo, đổi tên, thành viên, cài đặt, link, ghi chú, lời mời | Nhóm & Cộng đồng | | conv | Tắt thông báo, ghim, lưu trữ, ẩn hội thoại, tự xóa | Hội thoại | | profile | Xem/cập nhật hồ sơ, ảnh đại diện, quyền riêng tư | Hồ sơ | | poll | Tạo, bỏ phiếu, đóng khảo sát | Khảo sát | | reminder | Tạo, sửa, xóa nhắc nhở | Nhắc nhở | | auto-reply | Quản lý trả lời tự động | Trả lời tự động | | quick-msg | Tin nhắn nhanh đã lưu | Tin nhắn nhanh | | label | Nhãn hội thoại | Nhãn | | catalog | zBusiness — danh mục sản phẩm | zBusiness | | listen | Lắng nghe tin nhắn real-time, webhook, lưu JSONL | Lắng nghe | | account | Đa tài khoản & proxy | Tài khoản | | oa | Zalo Official Account API v3.0 — OAuth, tin nhắn, follower, tag, webhook | Official Account |

Xem thêm: Đa tài khoản & Proxy · Cài đặt VPS · Thẻ chuyển khoản & QR · Official Account

Tính năng

• Đăng nhập QR qua HTTP server tự động (browser + terminal)
• Đa tài khoản với proxy riêng biệt (1:1)
• 90+ lệnh phủ hết tính năng Zalo
• Zalo Official Account (OA) API v3.0 — OAuth login, gửi tin nhắn, quản lý follower, webhook listener
• Thẻ chuyển khoản (55+ ngân hàng VN) & QR VietQR
• Lắng nghe real-time với webhook & lưu JSONL local
• Output --json cho mọi lệnh — scripting & AI agents
• Credentials mã hóa tại chỗ (quyền 0600)
• Dual mode: interactive (human) + non-interactive (AI agents, CI/CD)

Ủng hộ

Nếu tool này giúp bạn tiết kiệm thời gian, hãy mua cho chúng tôi một ly cà phê!

English

CLI tool for Zalo automation — multi-account, proxy support, bank transfers, QR payments.

[!TIP] AI Agent Skill — Use with OpenClaw, Claude Code, or any SKILL.md-compatible agent:

clawhub install zalo-agent                    # OpenClaw (from ClawHub registry)
cp -r skill/ ~/.claude/skills/zalo-agent/     # Claude Code

15+ command groups · listen mode + webhook · 55+ VN banks · multi-account + proxy See skill/SKILL.md · Eval scenarios

[!NOTE] Zalo Official Account (OA) — v1.1.0 adds official Zalo OA API v3.0:

zalo-agent oa init                                    # Setup wizard (interactive)
zalo-agent oa init --app-id <ID> --secret <KEY> --skip-webhook  # Non-interactive (AI agent)
zalo-agent oa whoami                                  # OA profile
zalo-agent oa msg text <user-id> "Hello"              # Send message
zalo-agent oa listen -p 3000                           # Webhook listener

OAuth login · messaging · follower management · tags · webhook listener · VPS support See docs/official-account.md

[!TIP] MCP Server (AI Agent Integration) — v1.2.0 adds Model Context Protocol support for Claude Code and MCP clients:

zalo-agent mcp start              # stdio (local Claude Code)
zalo-agent mcp start --http 3847 --auth your-secret  # HTTP (VPS)

4 tools: get_messages · send_message · list_threads · mark_read Auto-reconnect · thread filter · noise reduction · group notifications See MCP Guide

Quick Start

npm install -g zalo-agent-cli
zalo-agent login                           # 1. Login via QR
zalo-agent friend search "Name"            # 2. Find a friend
zalo-agent listen                          # 3. Listen for threadId
zalo-agent msg send <THREAD_ID> "Hello!"   # 4. Send a message

Commands

Full docs: Wiki

| Group | Description | Docs | |-------|-------------|------| | msg | Text, images, files, voice, video, stickers, links, bank cards, QR | Messages | | friend | List, find, add, remove, block, alias, recommendations | Friends | | group | Create, rename, members, settings, links, notes, invites | Groups | | conv | Mute, pin, archive, hidden, auto-delete | Conversations | | profile | Profile, avatar gallery, privacy | Profile | | poll | Create, vote, lock polls | Polls | | reminder | Create, edit, remove reminders | Reminders | | auto-reply | Auto-reply rules | Auto-Reply | | quick-msg | Saved quick messages | Quick Messages | | label | Conversation labels | Labels | | catalog | zBusiness catalogs & products | Catalog | | listen | Real-time listener, webhook, JSONL | Listener | | account | Multi-account & proxy | Accounts | | oa | Zalo Official Account API v3.0 — OAuth, messaging, followers, webhook | Official Account |

Support Us

If this tool saves you time, consider buying us a coffee!

Star History

License

MIT · See DISCLAIMER.md for full terms.