openclaw-zalo-mod 2.29.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tuanminhole
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,295 @@
+# 🛡️ 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.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![OpenClaw Plugin](https://img.shields.io/badge/OpenClaw-Plugin-blue.svg)](https://openclaw.ai)
+[![Version](https://img.shields.io/badge/version-2.29.0-green.svg)](./CHANGELOG.md)
+
+**[🇺🇸 English](./README.md)**
+
+---
+
+<div align="center">
+  <a href="https://www.youtube.com/watch?v=hPusYX-5Pmw">
+    <img src="https://img.youtube.com/vi/hPusYX-5Pmw/maxresdefault.jpg" alt="Watch the OpenClaw and Zalo video guide" width="820" />
+  </a>
+  <br />
+  <strong>▶ Watch the OpenClaw + Zalo video guide on YouTube</strong>
+</div>
+
+---
+
+## ✨ Tính năng
+
+| Tính năng                | Token | Mô tả                                                                                                                                          |
+| ------------------------ | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Zalo Owner Dashboard** | 0     | Stunning graphical UI Dashboard (Premium Glassmorphism), manage groups, approve pending members, and compose direct messages via real ZCA API! |
+| **Chat workspace**       | 0     | Read and reply to Zalo threads inside the dashboard: conversation list, two-way message thread, composer, typing indicator                      |
+| **Chat history sync**    | 0     | Pulls older Zalo messages (groups *and* DMs) into `context.db` so the chat workspace does not start empty                                       |
+| **CRM Contacts**         | 0     | Friends and not-yet-friend customers in one page: phone, gender, birthday, shared groups, scoped per bot                                        |
+| **Zalo labels**          | 0     | Syncs the classification labels you already set in the Zalo app (colors preserved), filter and bulk-tag by them                                 |
+| **CSV import / export**  | 0     | Round-trip contacts through Excel, de-duplicating by phone → name+birthday → name                                                              |
+| **AI assistant column**  | LLM   | Draft · Summarize · Suggest · Analyze scoped to the open conversation (runs only when clicked)                                                  |
+| **Slash Commands**       | 0     | `/noi-quy`, `/menu`, `/huong-dan`, `/groupid`, `/ownerid`, `/report`, `/rules`                                                                 |
+| **Warn System**          | 0     | `/warn @name [reason]` — member violation tracker                                                                                              |
+| **Anti-Spam**            | 0     | Detect repeated messages, suspicious links, emoji floods                                                                                       |
+| **Admin Notes**          | 0     | `/note [text]` — quick admin annotations                                                                                                       |
+| **Memory Sync**          | 0     | `/memory` — saves context digest in `skills/memory/`                                                                                           |
+| **Smart Q&A**            | 0     | Native retrieval: "who is warned?", "spam log?" via local data                                                                                 |
+| **ZCA Admin Sync**       | 0     | Synchronizes `creatorId` & `adminIds` from Zalo API                                                                                            |
+| **Owner DM**             | 0     | Administrative command control panel over private DM                                                                                           |
+
+---
+
+## 🖥️ 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`:**
+  ```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.
+
+| Plan | View dashboard | Single group/member actions | Multi-group / bulk / `all` | Multi-bot actions |
+| --- | --- | --- | --- | --- |
+| Free | ✅ | ✅ | ❌ | ❌ |
+| Pro | ✅ | ✅ | ✅ | ❌ |
+| Team / Lifetime | ✅ | ✅ | ✅ | ✅ |
+
+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)
+
+```powershell
+# 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)
+
+```bash
+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
+
+```powershell
+# 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)
+
+```powershell
+# 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)
+
+| Lệnh                   | Mô tả                 |
+| ---------------------- | --------------------- |
+| `/{botname}-noi-quy`   | Xem nội quy nhóm      |
+| `/{botname}-menu`      | Danh sách lệnh        |
+| `/{botname}-huong-dan` | Hướng dẫn sử dụng bot |
+| `/{botname}-report`    | Báo cáo vi phạm       |
+
+### 🔧 Admin (trong group)
+
+| Lệnh                            | Mô tả             |
+| ------------------------------- | ----------------- |
+| `/{botname}-mute`               | Tắt bot hoàn toàn |
+| `/{botname}-unmute`             | Bật lại bot       |
+| `/{botname}-warn @name [lý do]` | Cảnh cáo member   |
+| `/{botname}-note [text]`        | Ghi chú admin     |
+| `/{botname}-memory [note]`      | Lưu memory digest |
+
+### 👑 Owner — trong group
+
+| Lệnh                         | Mô tả                                      |
+| ---------------------------- | ------------------------------------------ |
+| `/bot-rules`                 | Xem panel sub-lệnh                         |
+| `/bot-rules status`          | Cấu hình group hiện tại                    |
+| `/bot-rules groupid`         | Thêm group + lấy adminIds/creatorId từ ZCA |
+| `/bot-rules silent-on/off`   | Bật/tắt silent mode                        |
+| `/bot-rules welcome-on/off`  | Bật/tắt chào member mới                    |
+| `/bot-rules tracking-on/off` | Bật/tắt ghi lịch sử                        |
+
+### 🔐 Owner — qua DM riêng
+
+| Lệnh                                   | Mô tả                    |
+| -------------------------------------- | ------------------------ |
+| `/bot-rules mute <groupId> on/off`     | Mute/unmute group cụ thể |
+| `/bot-rules mute all on/off`           | Mute/unmute tất cả       |
+| `/bot-rules silent <groupId> on/off`   | Silent group cụ thể      |
+| `/bot-rules welcome <groupId> on/off`  | Welcome group cụ thể     |
+| `/bot-rules tracking <groupId> on/off` | Tracking group cụ thể    |
+| `/bot-rules dm-add <userId>`           | Thêm vào DM whitelist    |
+| `/bot-rules groupid-list`              | Danh sách tất cả groups  |
+| `/bot-ownerid`                         | Xem owner ID hiện tại    |
+
+---
+
+## 🛑 Anti-Spam
+
+| Loại            | Phát hiện                                      |
+| --------------- | ---------------------------------------------- |
+| **Repeat Spam** | Cùng tin nhắn gửi N lần trong khoảng thời gian |
+| **Link Spam**   | URL rút gọn hoặc link affiliate đáng ngờ       |
+| **Emoji Flood** | 5+ emoji liên tiếp                             |
+
+Cấu hình trong `openclaw.json`:
+
+```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](./LICENSE)

package/README.vi.md

@@ -0,0 +1,306 @@
+# 🛡️ openclaw-zalo-mod — Quản Trị Nhóm Zalo Zero-Token
+
+> Plugin OpenClaw 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ỉ tin nhắn `@mention` được chuyển lên AI agent.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![OpenClaw Plugin](https://img.shields.io/badge/OpenClaw-Plugin-blue.svg)](https://openclaw.ai)
+[![Version](https://img.shields.io/badge/version-2.29.0-green.svg)](./CHANGELOG.md)
+
+**[🇺🇸 English](./README.md)**
+
+---
+
+<div align="center">
+  <a href="https://www.youtube.com/watch?v=hPusYX-5Pmw">
+    <img src="https://img.youtube.com/vi/hPusYX-5Pmw/maxresdefault.jpg" alt="Xem video hướng dẫn OpenClaw và Zalo" width="820" />
+  </a>
+  <br />
+  <strong>▶ Xem video hướng dẫn OpenClaw + Zalo trên YouTube</strong>
+</div>
+
+---
+
+## ✨ Tính năng
+
+| Tính năng | Token | Mô tả |
+| --------- | ----- | ----- |
+| **Zalo Owner Dashboard** | 0 | UI Dashboard đồ họa tuyệt đẹp (Premium Glassmorphism), quản lý group, duyệt member, soạn gửi tin nhắn trực tiếp qua ZCA API! |
+| **Khung chat** | 0 | Đọc và trả lời tin nhắn Zalo ngay trong dashboard: danh sách hội thoại, luồng tin hai chiều, ô soạn tin, chỉ báo "đang soạn tin" |
+| **Lịch sử chat** | 0 | Kéo tin cũ từ Zalo về `context.db` (cả nhóm lẫn tin riêng) để khung chat không bắt đầu từ con số 0 |
+| **CRM Liên hệ** | 0 | Bạn bè + khách hàng chưa kết bạn trong một trang: SĐT, giới tính, sinh nhật, nhóm chung, tách theo từng bot |
+| **Nhãn Zalo** | 0 | Đồng bộ nhãn phân loại đã gán sẵn trên app Zalo (giữ nguyên màu), lọc và gắn nhãn hàng loạt |
+| **Nhập / tải CSV** | 0 | Đưa danh sách liên hệ ra Excel và nạp ngược lại, tự gộp trùng theo SĐT → tên+ngày sinh → tên |
+| **Trợ lý AI trong chat** | LLM | Soạn hộ · Tóm tắt · Gợi ý · Phân tích cho đúng hội thoại đang mở (chỉ chạy khi bấm) |
+| **Slash Commands** | 0 | `/[botname]-noi-quy`, `/[botname]-menu`, `/[botname]-huong-dan`, v.v. |
+| **Warn System** | 0 | `/[botname]-warn @name [lý do]` — theo dõi vi phạm theo member |
+| **Anti-Spam** | 0 | Tự phát hiện tin nhắn lặp, spam link, emoji flood |
+| **Admin Notes** | 0 | `/[botname]-note [text]` — ghi chú admin |
+| **Memory Sync** | 0 | `/[botname]-memory` — lưu digest vào `skills/memory/` |
+| **Smart Q&A** | 0 | Tự trả lời "ai bị warn?", "vi phạm?" từ dữ liệu local |
+| **ZCA Admin Sync** | 0 | Tự động lấy `creatorId` + `adminIds` từ Zalo API |
+| **Owner DM** | 0 | Nhận lệnh quản trị qua DM riêng với bot |
+
+> **Lưu ý về prefix lệnh:** Tất cả lệnh dùng prefix `/{tên-bot}-`. Ví dụ nếu bot tên `Williams` thì lệnh là `/williams-menu`, `/williams-noi-quy`, v.v.
+
+---
+
+## 🖥️ Zalo Owner Dashboard (UI)
+
+Plugin tích hợp sẵn giao diện quản trị đồ họa **Zalo Owner Dashboard** được thiết kế theo chuẩn **Premium Glassmorphism & High-Density Studio v1.5** siêu sang trọng.
+
+- **Cách truy cập:** `http://127.0.0.1:19790` (mặc định của plugin) hoặc IP máy chủ của bạn trên cổng `19790`.
+
+> ⚠️ **Cài qua OpenClaw Setup thì cổng KHÁC.** Setup tự ghi `dashboardPort = cổng gateway + 1` để mỗi
+> project có dashboard riêng — gateway `18789` → dashboard **`18790`**. Không chắc thì mở
+> `openclaw.json` xem `plugins.entries["zalo-mod"].config.dashboardPort`, hoặc bấm **Mở web** trên
+> card `openclaw-zalo-mod` trong Setup (nút đó tự suy ra cổng đúng). Trên VPS còn phải forward cổng
+> đó qua SSH tunnel vì dashboard chỉ nghe trên loopback.
+- **Cấu hình trong `openclaw.json`:**
+  ```json
+  "dashboardEnabled": true,
+  "dashboardHost": "127.0.0.1",
+  "dashboardPort": 19790
+  ```
+
+### Các phân hệ chính trên Dashboard:
+
+1. **📊 Tổng quan vận hành**: Xem nhanh số lượng nhóm, member chờ duyệt, logs hoạt động theo thời gian thực.
+2. **👥 Quản lý Nhóm**: Cấu hình chế độ Silent Mode, Welcome message, xem link mời nhóm, xem danh sách Admin từng nhóm.
+3. **⏳ Thành viên & Duyệt**: Duyệt nhanh thành viên xin vào nhóm, theo dõi member vi phạm/cảnh cáo.
+4. **✍️ Gửi tin nhắn (Composer)**: Soạn thảo tin nhắn và gửi trực tiếp đến các nhóm nhanh chóng, hỗ trợ preview hình ảnh trước khi gửi.
+5. **💬 Khung chat**: Ba cột kiểu Zalo Web — danh sách hội thoại (lọc theo bot), luồng tin hai chiều kèm chỉ báo *đang soạn tin*, và cột trợ lý AI (Soạn hộ · Tóm tắt · Gợi ý · Phân tích). Ô soạn tin chỉ mở ở tin nhắn riêng; nhóm chuyển sang trang Gửi hàng loạt.
+6. **🗂️ Liên hệ (CRM)**: Bạn bè và khách hàng chưa kết bạn chung một trang — SĐT, giới tính, sinh nhật, nhóm chung, nhãn Zalo có màu. Lọc theo nhãn / loại / sinh nhật sắp tới, chọn hàng loạt để gắn nhãn hoặc xoá, nhập-tải CSV.
+7. **🔌 Danh mục API**: Tra cứu toàn bộ các ZCA API khả dụng và các ví dụ thực tế.
+
+> **Dữ liệu tách theo từng bot.** Mỗi tài khoản Zalo là một hộp thư riêng, nên khung chat và trang
+> Liên hệ luôn lọc theo bot đang chọn. Chế độ "tất cả bot" có gộp trùng người (Zalo cấp uid khác
+> nhau cho cùng một người ở hai tài khoản) nhưng **không** trộn hội thoại.
+
+---
+
+### Gói tính năng
+
+Mỗi bản cài mới được tự động dùng thử **Pro trong 30 ngày**. Trial được license server ký và gắn với Device ID, không cần nhập key.
+
+| Gói | Xem dashboard | Thao tác từng group/member | Nhiều group / hàng loạt / `all` | Nhiều bot cùng lúc |
+| --- | --- | --- | --- | --- |
+| Free | ✅ | ✅ | ❌ | ❌ |
+| Pro | ✅ | ✅ | ✅ | ❌ |
+| Team / Lifetime | ✅ | ✅ | ✅ | ✅ |
+
+Hết trial, dashboard và mọi dữ liệu vẫn xem được; các thao tác đơn vẫn hoạt động bình thường.
+
+---
+
+## 🏗️ Kiến trúc
+
+```
+Tin nhắn Zalo đến
+    │  OpenClaw Zalo Connect sở hữu kết nối Zalo + inbound gate
+    ├─ Mute               → chặn trước pipeline/model (0 token)
+    ├─ Silent, không tag  → chặn trước pipeline/model (0 token)
+    └─ Tin được phép      → Zalo Mod xử lý lệnh/policy/context
+                              ├─ lệnh local, anti-spam (0 token)
+                              └─ agent reply → tự tag đúng người gửi
+                                                → Zalo Connect gửi mention native
+
+Khung chat + CRM (dashboard)
+    │  Zalo Connect phát 3 kênh riêng qua bridge: inbound · lịch sử · đang-soạn-tin
+    ├─ inbound + lịch sử  → ghi vào `context.db` (theo từng tài khoản Zalo)
+    ├─ đang-soạn-tin      → giữ trong RAM, hết 3 giây là bỏ
+    └─ dashboard poll một dấu-vân-tay ~68 byte mỗi 2s để biết có gì mới
+```
+
+OpenClaw Zalo Connect là channel/runtime Zalo duy nhất trong production. Zalo Mod
+không đăng nhập Zalo riêng, không patch private `dist`, và không sở hữu transport thứ hai.
+Kiến trúc kỹ thuật và bridge contract nằm trong thư mục nội bộ `docs_dev/`,
+được Git bỏ qua và không phát hành công khai.
+
+---
+
+## 🔐 Dữ liệu & bảo mật
+
+Gói phát hành dùng mã nguồn rõ để người dùng và ClawHub có thể kiểm tra đầy đủ.
+
+- **Dữ liệu local:** chỉ đọc cấu hình OpenClaw và dữ liệu Zalo Mod trong project; chỉ ghi thiết lập plugin, audit, memory/lịch sử và một mã cài đặt ngẫu nhiên 16 ký tự được lưu bền vững.
+- **Lịch sử chat và liên hệ:** khung chat và CRM lưu tin nhắn cùng thông tin liên hệ vào `context.db` **nằm trong project OpenClaw của bạn** — chính máy đang chạy bot. Không có gì được tải lên, máy chủ bản quyền không hề nhận. Xoá file đó là mất sạch dữ liệu. Riêng chỉ báo "đang soạn tin" không bao giờ ghi xuống đĩa.
+- **Kết nối Zalo:** dùng bridge của OpenClaw Zalo Connect đã cài trên cùng máy. Zalo Mod không thu thập cookie đăng nhập Zalo và không tạo phiên Zalo thứ hai.
+- **Máy chủ bản quyền:** chỉ gửi mã cài đặt ngẫu nhiên cùng trạng thái license/order tới `https://zalo-mod-server.monkeytech.io.vn` để cấp 30 ngày Pro, kích hoạt đơn hàng và làm mới entitlement có chữ ký. Không gửi hostname, thông tin phần cứng, cookie trình duyệt, lịch sử chat hay thông tin đăng nhập Zalo.
+- **Tóm tắt AI:** chỉ khi người dùng bật/chạy tính năng tóm tắt, phần text liên quan mới được gửi tới endpoint tương thích OpenAI/9Router mà chính Owner đã cấu hình trong OpenClaw; plugin không dùng endpoint bí mật khác.
+- **Dashboard:** mặc định chỉ nghe tại `127.0.0.1`. Trong Docker, plugin nghe trên interface nội bộ của container để ánh xạ `127.0.0.1:PORT:PORT` phía máy chủ truy cập được; OpenClaw Setup tự tạo ánh xạ chỉ-localhost này. Nếu tự cấu hình `dashboardHost` ngoài localhost, plugin vẫn yêu cầu `dashboardToken` dài tối thiểu 24 ký tự.
+- **Đã bỏ khỏi phạm vi:** gói không chứa Facebook Crawler và không đọc, lưu hay chuyển tiếp cookie Facebook/cookie trình duyệt.
+- **Telemetry:** plugin không có analytics hoặc telemetry nền.
+
+---
+
+## 📦 Cài đặt
+
+### 1. Docker (khuyến nghị — dùng với openclaw-setup)
+
+```powershell
+# Cài bản OpenClaw Zalo Connect đã ghim trước, sau đó cài 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)
+
+```bash
+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
+
+```powershell
+# 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)
+
+```powershell
+# Copy file đã sửa vào volume
+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 — OpenClaw sẽ từ chối load)
+docker exec openclaw-bot chmod 644 /root/project/.openclaw/extensions/zalo-mod/index.js
+
+# Restart
+docker restart openclaw-bot
+```
+
+---
+
+## ⚙️ Cấu hình ban đầu
+
+### Bước 1: Xác nhận plugin đã load
+
+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
+[plugins] [openclaw-zalo-mod] loaded — bot="Williams" owner=... groups=N
+```
+
+### 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 (thay `botname` theo tên bot của bạn):
+
+```
+/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 đủ
+
+> **Prefix lệnh:** `/{tên-bot}-` — ví dụ bot tên `Williams` → prefix là `/williams-`
+
+### 👤 Mọi người (trong group)
+
+| Lệnh                   | Mô tả                 |
+| ---------------------- | --------------------- |
+| `/{botname}-noi-quy`   | Xem nội quy nhóm      |
+| `/{botname}-menu`      | Danh sách lệnh        |
+| `/{botname}-huong-dan` | Hướng dẫn sử dụng bot |
+| `/{botname}-report`    | Báo cáo vi phạm       |
+
+### 🔧 Admin (trong group)
+
+| Lệnh                            | Mô tả             |
+| ------------------------------- | ----------------- |
+| `/{botname}-mute`               | Tắt bot hoàn toàn |
+| `/{botname}-unmute`             | Bật lại bot       |
+| `/{botname}-warn @name [lý do]` | Cảnh cáo member   |
+| `/{botname}-note [text]`        | Ghi chú admin     |
+| `/{botname}-memory [note]`      | Lưu memory digest |
+
+### 👑 Owner — trong group
+
+| Lệnh                         | Mô tả                                      |
+| ---------------------------- | ------------------------------------------ |
+| `/bot-rules`                 | Xem panel sub-lệnh                         |
+| `/bot-rules status`          | Cấu hình group hiện tại                    |
+| `/bot-rules groupid`         | Thêm group + lấy adminIds/creatorId từ ZCA |
+| `/bot-rules silent-on/off`   | Bật/tắt silent mode                        |
+| `/bot-rules welcome-on/off`  | Bật/tắt chào member mới                    |
+| `/bot-rules tracking-on/off` | Bật/tắt ghi lịch sử                        |
+
+### 🔐 Owner — qua DM riêng
+
+| Lệnh                                   | Mô tả                    |
+| -------------------------------------- | ------------------------ |
+| `/bot-rules mute <groupId> on/off`     | Mute/unmute group cụ thể |
+| `/bot-rules mute all on/off`           | Mute/unmute tất cả       |
+| `/bot-rules silent <groupId> on/off`   | Silent group cụ thể      |
+| `/bot-rules welcome <groupId> on/off`  | Welcome group cụ thể     |
+| `/bot-rules tracking <groupId> on/off` | Tracking group cụ thể    |
+| `/bot-rules dm-add <userId>`           | Thêm vào DM whitelist    |
+| `/bot-rules groupid-list`              | Danh sách tất cả groups  |
+| `/bot-ownerid`                         | Xem owner ID hiện tại    |
+
+---
+
+## 🛑 Anti-Spam
+
+| Loại            | Phát hiện                                      |
+| --------------- | ---------------------------------------------- |
+| **Repeat Spam** | Cùng tin nhắn gửi N lần trong khoảng thời gian |
+| **Link Spam**   | URL rút gọn hoặc link affiliate đáng ngờ       |
+| **Emoji Flood** | 5+ emoji liên tiếp                             |
+
+Cấu hình trong `openclaw.json`:
+
+```json
+"spamRepeatN": 3,
+"spamWindowSeconds": 300
+```
+
+---
+
+## 🔇 Mute vs Silent
+
+|                | Mute             | Silent             |
+| -------------- | ---------------- | ------------------ |
+| Bot im lặng    | Hoàn toàn        | Chỉ không tự reply |
+| Slash commands | ❌ (chỉ /unmute) | ✅                 |
+| @mention       | ❌               | ✅                 |
+| Welcome        | ❌               | ✅                 |
+
+---
+
+## 🔧 Yêu cầu
+
+- OpenClaw `>= 2026.5.7`
+- Plugin/channel `zalo-connect` đã được cấu hình và xác thực
+- OpenClaw Zalo Connect bridge service v2 (có live group policy)
+- Node.js `>= 22`
+
+---
+
+## 📄 License
+
+MIT — see [LICENSE](./LICENSE)