🛡️ openclaw-zalo-mod — Zero-Token Zalo Group Moderation

OpenClaw runtime plugin dành cho quản trị nhóm Zalo. Xử lý kiểm duyệt, slash commands, anti-spam với 0 token LLM. Chỉ có tin nhắn @mention mới được chuyển lên AI agent.

🇺🇸 English

✨ Tính năng

🖥️ Zalo Owner Dashboard (UI)

The plugin features a built-in administrative graphical user interface Zalo Owner Dashboard crafted under Premium Glassmorphism & High-Density Studio v1.5 design guidelines.

• Access URL: http://127.0.0.1:19790 (the plugin's own default) or your server IP on port 19790.

⚠️ Installed through OpenClaw Setup? The port is different. Setup writes dashboardPort = gateway port + 1 so every project gets its own dashboard — gateway 18789 → dashboard 18790. When in doubt, read plugins.entries["zalo-mod"].config.dashboardPort from openclaw.json, or click Open on the openclaw-zalo-mod card in Setup (that button derives the right port). On a VPS you also have to forward that port over an SSH tunnel — the dashboard listens on loopback only.

• Configuration inside openclaw.json:

  "dashboardEnabled": true,
  "dashboardHost": "127.0.0.1",
  "dashboardPort": 19790
  

Key Modules:

1. 📊 Operations Overview: Live monitoring of group statistics, pending member requests, and operational audit logs.
2. 👥 Group Management: Configure Silent Mode, Welcome messages, view invite links, and track group administrators.
3. ⏳ Member Approvals: Quickly accept pending group membership requests and watch flagged members.
4. ✍️ Message Composer: Write and dispatch raw text or image announcements directly to chosen groups with immediate preview.
5. 💬 Chat workspace: A three-column, Zalo-Web-style view — conversation list (filtered per bot), two-way message thread with a typing indicator, and an AI assistant column (Draft · Summarize · Suggest · Analyze). The composer is enabled for DMs only; groups point you to the bulk-send page.
6. 🗂️ Contacts (CRM): Friends and not-yet-friend customers in one page — phone, gender, birthday, shared groups, colored Zalo labels. Filter by label / type / upcoming birthday, bulk-select to tag or delete, import and export CSV.
7. 🔌 API Directory: Inspect fully documented ZCA JavaScript APIs with real integration examples.

Data is scoped per bot. Each Zalo account is its own mailbox, so the chat workspace and the Contacts page always filter by the selected bot. "All bots" mode merges duplicate people (Zalo issues a different uid per account for the same person) but never merges conversations.

Feature tiers

Every first installation automatically receives a 30-day Pro trial. The license server signs and binds the trial to the Device ID, so no manual key is required.

After the trial, every page remains readable and all single-item actions continue to work.

🏗️ Kiến trúc

Tin nhắn Zalo đến
    │  OpenClaw Zalo Connect owns the connection and inbound gate
    ├─ Mute               → drop before pipeline/model (0 tokens)
    ├─ Silent, no mention → drop before pipeline/model (0 tokens)
    └─ Allowed message    → Zalo Mod commands/policy/context
                              ├─ local command, anti-spam (0 tokens)
                              └─ agent reply → tag triggering sender
                                                → Zalo Connect native mention

Chat workspace + CRM (dashboard)
    │  Zalo Connect publishes 3 bridge channels: inbound · history · typing
    ├─ inbound + history  → written to `context.db`, keyed per Zalo account
    ├─ typing             → kept in RAM only, expires after 3s
    └─ dashboard polls a ~68-byte fingerprint every 2s to detect changes

OpenClaw Zalo Connect is the only Zalo channel/runtime used in production. Zalo Mod does not log in separately, patch private dist files, or own a second transport. Internal architecture and bridge notes live in the ignored docs_dev/ directory and are intentionally not included in public releases.

🔐 Data & security

The published package is intentionally auditable and ships readable source code.

• Local data: reads OpenClaw configuration plus Zalo Mod state under the local OpenClaw project; writes only plugin settings, audit records, memory/history, and a random persistent 16-character installation ID.
• Chat history and contacts: the chat workspace and CRM store messages and contact details in context.db inside your own OpenClaw project — the same machine the bot already runs on. Nothing is uploaded; the license server never receives them. Delete the file and the data is gone. Typing indicators are never written to disk at all.
• Zalo access: uses the locally installed OpenClaw Zalo Connect bridge. Zalo Mod does not collect Zalo login cookies or create a second Zalo session.
• License service: sends the random installation ID and license/order state only to https://zalo-mod-server.monkeytech.io.vn to issue the 30-day trial, activate purchases, and refresh signed entitlements. It does not send hostname, hardware identifiers, browser cookies, chat history, or Zalo credentials.
• AI summaries: only when a summary feature is used, the relevant text is sent to the 9Router/OpenAI-compatible endpoint already configured by the OpenClaw owner. No hidden endpoint is used.
• Dashboard: listens on 127.0.0.1 by default. In Docker it listens on the container interface so a host-side 127.0.0.1:PORT:PORT mapping can reach it; OpenClaw Setup creates that localhost-only mapping automatically. An explicitly configured non-loopback dashboardHost still requires a dashboardToken of at least 24 characters.
• Removed scope: this package contains no Facebook crawler and never reads, stores, or forwards Facebook/browser cookies.
• Telemetry: the plugin has no analytics or background telemetry.

📦 Cài đặt

1. Docker (khuyến nghị — dùng với openclaw-setup)

# Install the pinned OpenClaw Zalo Connect release first, then Zalo Mod
docker exec openclaw-bot openclaw plugins install "https://github.com/tuanminhhole/openclaw-zalo-connect.git#v3.0.0"
docker exec openclaw-bot openclaw plugins install clawhub:openclaw-zalo-mod --force
docker restart openclaw-bot

2. Native (không Docker)

openclaw plugins install "https://github.com/tuanminhhole/openclaw-zalo-connect.git#v3.0.0"
openclaw plugins install openclaw-zalo-mod
openclaw gateway restart

3. Cài thủ công từ source

# Copy source vào thư mục extensions
xcopy /E /I openclaw-zalo-mod "%OPENCLAW_HOME%\extensions\zalo-mod"

# Hoặc trên Linux
cp -r openclaw-zalo-mod ~/.openclaw/extensions/zalo-mod

# Restart gateway
openclaw gateway restart

4. Patch nhanh khi phát triển (Docker)

# Copy file đã sửa vào container
Copy-Item -Path "D:\openclaw-zalo-mod\index.js" -Destination "E:\final\.openclaw\extensions\zalo-mod\index.js" -Force

# Fix quyền (Windows bind mount tạo quyền 777)
docker exec openclaw-bot chmod 644 /root/project/.openclaw/extensions/zalo-mod/index.js

# Restart
docker restart openclaw-bot

⚠️ Lưu ý quyền file: Windows bind mounts tạo file với quyền 0777. OpenClaw sẽ từ chối load plugin có quyền world-writable. Luôn chạy chmod 644 sau khi copy.

⚙️ Cấu hình ban đầu

Bước 1: Xác nhận bot đã load plugin

Kiểm tra log sau khi restart:

[gateway] ... plugins: ..., zalo-connect, zalo-mod, ...
[openclaw-zalo-mod] bridge backend: zalo-connect-service connected=true
[openclaw-zalo-mod] live group policy replayed: N/N

Plugin phải xuất hiện trong danh sách. Nếu thiếu, kiểm tra quyền file.

Bước 2: Nhận quyền Owner

Mở Zalo Mod Dashboard → Cài đặt, copy Device ID, rồi gửi DM riêng cho bot:

i'm owner <DEVICE_ID>

Device ID chứng minh bạn có quyền truy cập máy chủ, tránh người lạ tự nhận Owner. Chỉ cần xác nhận một lần; bot sẽ ghi ownerId vào config và khóa quyền sở hữu.

Bước 3: Đăng ký Group

Vào group cần quản lý, gửi lệnh:

/bot-rules groupid

Bot sẽ quét session, lấy creatorId + adminIds từ Zalo API, rồi tự ghi vào config.

📋 Danh sách lệnh đầy đủ

👤 Mọi người (trong group)

🔧 Admin (trong group)

👑 Owner — trong group

🔐 Owner — qua DM riêng

🛑 Anti-Spam

Cấu hình trong openclaw.json:

"spamRepeatN": 3,
"spamWindowSeconds": 300

🔧 Yêu cầu

• OpenClaw >= 2026.5.7
• Plugin/channel zalo-connect is configured and authenticated
• OpenClaw Zalo Connect bridge service v2 (including live group policy)
• Node.js >= 22

📄 License

MIT — see LICENSE