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  --secret  --skip-webhook  # Non-interactive (AI agent)
zalo-agent oa whoami                                  # Xem thông tin OA
zalo-agent oa msg text  "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)

7 tools: get_messages · get_history · send_message · list_threads · search_threads · mark_read · view_media Auto-reconnect (exponential backoff) · thread filter · noise reduction · group notifications Xem MCP Guide

Cấu hình client (stdio):

• Claude Code: claude mcp add zalo -- zalo-agent mcp start
• Claude Desktop — sửa ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) hoặc %APPDATA%\Claude\claude_desktop_config.json (Windows):

  { "mcpServers": { "zalo": { "command": "zalo-agent", "args": ["mcp", "start"] } } }
  

  App GUI không kế thừa PATH của shell (đặc biệt với nvm). Nếu Claude Desktop báo không tìm thấy zalo-agent, thay command bằng đường dẫn tuyệt đối từ which zalo-agent, ví dụ /Users/ban/.nvm/versions/node/v20.x/bin/zalo-agent.

⚠️ Chỉ bật MCP server ở MỘT client tại một thời điểm (Claude Code hoặc Claude Desktop). Zalo chỉ cho phép một phiên web (zca-js) mỗi tài khoản — chạy cả hai sẽ gây vòng lặp mất kết nối (reconnect loop). App Zalo gốc trên máy thì không ảnh hưởng.

---

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  "Xin chào!"

# Gửi vào nhóm
zalo-agent msg send  "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

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ê!

Quét bằng app ngân hàng bất kỳ

---

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  --secret  --skip-webhook  # Non-interactive (AI agent)
zalo-agent oa whoami                                  # OA profile
zalo-agent oa msg text  "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)

7 tools: get_messages · get_history · send_message · list_threads · search_threads · mark_read · view_media Auto-reconnect (exponential backoff) · thread filter · noise reduction · group notifications See MCP Guide

Client setup (stdio):

• Claude Code: claude mcp add zalo -- zalo-agent mcp start
• Claude Desktop — edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

  { "mcpServers": { "zalo": { "command": "zalo-agent", "args": ["mcp", "start"] } } }
  

  GUI apps don’t inherit your shell PATH (especially with nvm). If Claude Desktop can’t find zalo-agent, set command to the absolute path from which zalo-agent, e.g. /Users/you/.nvm/versions/node/v20.x/bin/zalo-agent.

⚠️ Run the MCP server in only ONE client at a time (Claude Code or Claude Desktop). Zalo allows a single web (zca-js) session per account — running both triggers a reconnect/eviction loop. The native Zalo desktop app is unaffected.

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  "Hello!"   # 4. Send a message

Commands

Full docs: Wiki

Support Us

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

Scan with any Vietnamese banking app

---

Star History

License

MIT · See DISCLAIMER.md for full terms.