openclaw-rocketchat 0.5.1 → 0.5.3

package/README.en.md

@@ -69,33 +69,161 @@ AI Brain (OpenClaw Agent)
 
 **Either way, your AI data never passes through third parties.**
 
-## Key Advantages
+## Ten Advantages
 
-- **🇨🇳 Works in Mainland China** — Rocket.Chat is on China App Store, server runs on your machine, auto sslip.io free domain + Let's Encrypt HTTPS cert, no domain purchase, no ICP registration, zero dependency on blocked services
-- **⚡ One-Command Deployment** — `openclaw rocketchat setup` interactive wizard handles everything; supports co-located (one machine) and split deployment (RC in cloud, OpenClaw at home)
-- **🔐 Complete Data Sovereignty** — All messages stay in your own MongoDB, chat history never touches third-party servers
-- **🤖 Multi-Agent Multi-Bot** — Different Agents map to different bots (personal assistant, work helper, code reviewer), DMs and group chats coexist
-- **👥 Team Collaboration** — One deployment for the whole team, `add-user` to add people, `invite` to pull into groups, supports full-access and read-only permissions
-- **📱 Cross-Platform** — iOS / Android / macOS / Windows / Linux / Web, real-time sync across all devices. [Download clients](https://www.rocket.chat/download-apps)
-- **🆓 Free and Open Source** — MIT license, no subscription fees, no message limits, MongoDB export anytime, zero vendor lock-in
+### 1. 🏠 A Dedicated AI Workspace
+
+Using Telegram for AI chat? Your AI conversations are sandwiched between friend messages, group spam, and channel noise. Important AI replies get lost.
+
+**Rocket.Chat becomes your dedicated AI command center.** Open it, and all you see are your AI assistants — no social distractions, no unrelated messages. One app, one purpose.
+
+### 2. 🔔 Dedicated Push Notifications
+
+When OpenClaw sends you a message, you get a notification from **Rocket.Chat** — not Telegram's 99th unread, not WeChat's 200th group message.
+
+**You never miss an important AI response.**
+
+### 3. 🔐 Complete Data Sovereignty
+
+| Using Telegram | Using This Plugin |
+|---|---|
+| Messages go through Telegram's servers | Messages stay on your machine |
+| Chat history stored on someone else's cloud | Chat history in your own MongoDB |
+| You can't control where data goes | Docker volume is yours — delete anytime |
+| Terms of service change without notice | You are the terms of service |
+
+**Zero trust in third parties. Your AI conversations, private data, and work content stay on your own hard drive.**
+
+### 4. 🇨🇳 Works Perfectly in Mainland China
+
+- Rocket.Chat App is **directly downloadable** from China App Store / Google Play
+- Server runs on your own machine — **no cross-border traffic**
+- Auto **sslip.io free domain** + auto **Let's Encrypt HTTPS cert** — no domain purchase, no ICP registration needed
+- Zero dependency on blocked services
+
+### 5. ⚡ One-Command Deployment, Two Modes
+
+No 10-page documentation to read. No browser-based admin panels to click through. No manual JSON editing.
+
+```bash
+openclaw rocketchat setup
+```
+
+An interactive wizard guides you through everything — Docker deployment, account creation, config writing — all in one go.
+
+Choose the deployment mode that fits your situation:
+
+| | Co-located | Split Deployment |
+|---|---|---|
+| **Who it's for** | Users with a public server | Home network, low-spec servers |
+| **RC runs on** | Same machine as OpenClaw | Separate cloud VPS |
+| **How to install** | `install-rc.sh` + `openclaw rocketchat setup` | `install-rc.sh` on VPS, connect locally |
+| **Advantage** | Simplest, one machine | OpenClaw can run at home, RC in the cloud |
+
+> Split deployment means even if your OpenClaw is on a **home LAN without a public IP**, a cheap VPS (1 core, 1 GB RAM is enough) lets your phone connect from anywhere.
+
+### 6. 🤖 Multi-Agent, Multi-Bot
+
+Create multiple Agents in OpenClaw (e.g., "Personal Assistant", "Work Helper", "Code Reviewer"), each appearing as a separate bot in Rocket.Chat:
+
+```
+Conversation List
+  🦞 Lobster          ← DM: Personal assistant
+  💼 Work Helper      ← DM: Work agent
+  🏠 AI Squad         ← Group: All bots together
+  📝 Code Review      ← Group: Dedicated code agent
+```
+
+**DMs and group chats coexist** — ask simple questions via DM, tackle complex problems in groups with multiple bots collaborating.
+
+### 7. 👥 Team Collaboration — Share AI Across Your Whole Team
+
+This isn't just a single-user AI tool — your entire team can use it together.
+
+```
+「Product Discussion」
+  👤 Alice (Product Manager)
+  👤 Bob (Designer)
+  👤 Charlie (Developer)
+  🤖 Lobster (AI Assistant)
+
+Alice: Can you analyze the technical feasibility of this feature?
+🦞 Lobster: Based on the requirements, I've analyzed three aspects...
+Bob: @Lobster Any color scheme suggestions?
+🦞 Lobster: From a UI/UX perspective, I recommend...
+Charlie: How long would this take to implement?
+🦞 Lobster: Based on the current tech stack, estimated...
+```
+
+One deployment, the whole team benefits:
+
+- **Companies/Teams** — Everyone discusses with AI in the same group, stay aligned, no relay needed
+- **Families** — Add an account for each family member, everyone gets their own AI assistant
+- **Studios** — Different projects get different groups, each with specialized Agents
+- **Education** — Teachers and students in the same group, AI-assisted learning
+
+`openclaw rocketchat add-user` adds a new member in one command, `openclaw rocketchat invite` pulls them into any group. **No per-person deployment, no per-person configuration — one service for everyone.**
+
+### 8. 🔒 Fine-Grained Permission Control
+
+Not everyone needs to talk to AI — some people just need to watch.
+
+| Permission | View Messages | Send Messages | DM Bots | Use Case |
+|---|---|---|---|---|
+| **Full Access** | ✅ | ✅ | ✅ | Regular team members |
+| **Read-Only** | ✅ | ❌ | ❌ | Boss monitoring, auditing, observers |
+
+Typical scenarios:
+- **Boss/Manager** — Read-only, review team-AI conversations anytime, track project progress
+- **Interns** — Read-only, observe senior staff's AI discussions, learn and grow
+- **Clients** — Read-only, see AI-generated analysis reports without interfering
+- **Audit/Compliance** — Read-only, monitor AI usage for regulatory compliance
+
+```bash
+openclaw rocketchat add-user
+# Choose during setup:
+#   1) Full access — can send messages in groups and DM bots
+#   2) Read-only — can only view group messages, no sending or DM
+```
+
+**No other platform offers this** — on Telegram or WhatsApp, users either see everything and can say everything, or see nothing at all.
+
+### 9. 📱 Cross-Platform
+
+Official Rocket.Chat clients: [rocket.chat/download-apps](https://www.rocket.chat/download-apps)
+
+| Platform | How to Download |
+|---|---|
+| **iOS** | Search **"Rocket.Chat"** on App Store (developer: Rocket.Chat Technologies Corp)<br>Available in China App Store — no account switching needed |
+| **Android** | Search **"Rocket.Chat"** on Google Play, or download APK from the official site |
+| **macOS** | [Mac App Store](https://apps.apple.com/app/rocket-chat/id1148741252) or [download .dmg](https://www.rocket.chat/download-apps) |
+| **Windows** | [Download installer](https://www.rocket.chat/download-apps) |
+| **Linux** | [Download](https://www.rocket.chat/download-apps) (.deb / .rpm / Snap) |
+| **Web** | No download needed — open `https://YOUR-IP.sslip.io` in any browser |
+
+> 💡 **Search tip**: In App Store / Google Play, search "Rocket.Chat" and look for the developer **Rocket.Chat Technologies Corp**.
+
+Deploy once, access from phone, computer, tablet, or browser. Messages sync across all devices in real time.
+
+### 10. 🆓 Completely Free, Open Source, No Vendor Lock-In
+
+- No subscription fees, no message limits, no feature restrictions
+- MIT license — modify as you wish
+- Built on Rocket.Chat's open-source ecosystem with an active community
+- **No vendor lock-in** — export your data anytime (standard MongoDB format)
+- You're running a standard Rocket.Chat server — plug in more features in the future (video calls, file sharing, webhook integrations, etc.)
 
 ## Comparison
 
+> Full comparison table at [docs/ARCHITECTURE.en.md](docs/ARCHITECTURE.en.md)
+
 |  | Feishu | Telegram | WhatsApp | This Plugin |
 |---|---|---|---|---|
 | **China Available** | ✅ | ❌ VPN needed | ❌ Foreign # needed | ✅ |
-| **Setup Complexity** | 🔴 High | 🔴 High (VPN) | 🔴 High | 🟢 One command |
-| **Dedicated AI Space** | ❌ Mixed with work | ❌ Mixed with social | ❌ Mixed with social | ✅ Dedicated |
-| **Dedicated Notifications** | ❌ Mixed | ❌ Buried | ❌ Buried | ✅ Standalone |
-| **Data Privacy** | 🟡 Via Feishu servers | 🟡 Via TG servers | 🟡 Via Meta servers | 🟢 Fully local |
-| **Multi-Agent** | Manual config | Supported | Supported | ✅ Interactive setup |
-| **Group Multi-Bot** | Limited | Supported | Not supported | ✅ Supported |
-| **Multi-User Team** | Enterprise only | ❌ Separate setups | ❌ Separate setups | ✅ One deploy for all |
-| **Permission Control** | Enterprise only | ❌ | ❌ | ✅ Full/Read-Only |
-| **Split Deployment** | ❌ | ❌ | ❌ | ✅ Home LAN works |
-| **Self-Hosted** | ❌ | ❌ | ❌ | ✅ |
-| **Free** | Limited | Yes | Yes | ✅ Completely free |
-| **Open Source** | ❌ | ❌ | ❌ | ✅ MIT |
+| **Setup Complexity** | 🔴 High | 🔴 High | 🔴 High | 🟢 One command |
+| **Data Privacy** | 🟡 Via 3rd party | 🟡 Via 3rd party | 🟡 Via 3rd party | 🟢 Fully local |
+| **Multi-User Team** | Enterprise only | ❌ | ❌ | ✅ One deploy for all |
+| **Free & Open Source** | ❌ | ❌ | ❌ | ✅ MIT |
 
 ## Quick Start
 
@@ -517,143 +645,30 @@ All commands are **interactive** — no flags to memorize, just follow the promp
 
 All config is written automatically by CLI commands into `~/.openclaw/openclaw.json`. You normally don't need to edit it manually, but understanding the structure helps with troubleshooting and advanced customization.
 
-### channels.rocketchat — Channel Config
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `enabled` | `boolean` | `false` | Enable/disable the Rocket.Chat channel |
-| `serverUrl` | `string` | — | Rocket.Chat server URL, e.g. `"https://123-45-67-89.sslip.io"` or `"https://127.0.0.1"` (co-located) |
-| `port` | `number` | `443` | Rocket.Chat HTTPS port (the port specified during `install-rc.sh` installation) |
-| `dmPolicy` | `string` | `"pairing"` | DM policy. `"pairing"` means setup auto-creates DM channels between users and bots |
-| `accounts` | `object` | `{}` | Bot accounts. Key is the bot ID (written by `add-bot` command) |
-| `accounts.<id>.botUsername` | `string` | — | Bot's username in Rocket.Chat |
-| `accounts.<id>.botDisplayName` | `string` | — | Bot's display name (supports Unicode) |
-| `groups` | `object` | `{}` | Group config (written by `add-group` command). Key is the group name |
-| `groups.<name>.bots` | `string[]` | — | Bots in this group (matching keys in `accounts`) |
-| `groups.<name>.requireMention` | `boolean` | `false` | Whether bot requires `@mention` to respond. `false`: responds to all messages; `true`: only responds when directly `@mentioned` (recommended for multi-bot groups to avoid all bots replying at once) |
-
-> **Broadcast mentions**: `@here`, `@all`, `@everyone` never trigger bot responses, even when `requireMention` is `false`. Only direct `@botname` mentions trigger a response.
-
-### bindings — Agent Bindings
+> **Full configuration docs (parameter tables + JSON example + manual editing + full reset): [docs/CONFIGURATION.en.md](docs/CONFIGURATION.en.md)**
 
-The `bindings` array maps bot accounts to Agents (written by `add-bot` command):
+Quick reference for the most common parameters:
 
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `agentId` | `string` | The Agent ID to bind to (e.g. `"main"`). Created via `openclaw agents add` |
-| `match.channel` | `string` | Always `"rocketchat"` |
-| `match.accountId` | `string` | Matches a key in `channels.rocketchat.accounts` |
+| Parameter | Description |
+|-----------|-------------|
+| `channels.rocketchat.enabled` | Enable/disable channel |
+| `channels.rocketchat.serverUrl` | Server URL (`https://127.0.0.1` for co-located, sslip.io domain for remote) |
+| `channels.rocketchat.port` | HTTPS port (default `443`) |
+| `channels.rocketchat.accounts.<id>` | Bot accounts (written by `add-bot`) |
+| `channels.rocketchat.groups.<name>.requireMention` | @mention rule (`true`: only respond to @bot) |
+| `bindings[].agentId` | Bot-to-Agent binding |
+| `plugins.entries.openclaw-rocketchat.enabled` | Plugin enabled state |
 
-### plugins — Plugin Config
+> **Note**: Bot credentials are stored in `~/.openclaw/credentials/`, separate from config.
 
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `entries.openclaw-rocketchat.enabled` | `boolean` | Whether the plugin is enabled. Gateway auto-detects and sets to `true` on start |
-| `installs.openclaw-rocketchat.source` | `string` | Installation source, typically `"npm"` |
-| `installs.openclaw-rocketchat.spec` | `string` | Installed package spec, e.g. `"openclaw-rocketchat@0.5.0"` |
-| `installs.openclaw-rocketchat.installPath` | `string` | Plugin installation path, e.g. `"~/.openclaw/extensions/openclaw-rocketchat"` |
-| `installs.openclaw-rocketchat.version` | `string` | Currently installed version |
-| `installs.openclaw-rocketchat.installedAt` | `string` | Installation timestamp (ISO format) |
-
-### Manual Editing
-
-If auto-configuration has issues, edit `~/.openclaw/openclaw.json` directly:
+## Architecture
 
-```bash
-# Edit config
-vi ~/.openclaw/openclaw.json
+> Detailed architecture diagrams at [docs/ARCHITECTURE.en.md](docs/ARCHITECTURE.en.md)
 
-# Restart Gateway to apply changes
-openclaw gateway restart
 ```
-
-**Common manual edits:**
-
-- **Change server URL**: Edit `channels.rocketchat.serverUrl` (`https://127.0.0.1` for co-located, `https://IP.sslip.io` for remote)
-- **Change port**: Edit `channels.rocketchat.port`
-- **Disable/enable channel**: Set `channels.rocketchat.enabled` to `false` / `true`
-- **Rebind bot to different Agent**: Edit `bindings` array, change `agentId`
-- **Remove a bot**: Delete entries from both `accounts` and `bindings`
-- **Toggle @mention requirement**: Edit `groups.<name>.requireMention`
-- **Upgrade plugin version**: Update `plugins.installs.openclaw-rocketchat.version` and `spec`
-
-> **Note**: Bot credentials (passwords, tokens) are stored in `~/.openclaw/credentials/`, separate from `openclaw.json`. If you reinstall a bot, clean up the credentials directory as well.
-
-## Architecture
-
-### Mode A: Co-located
-
-Everything on one server — simplest setup.
-
-```
-┌─────────────────────────────────────────────┐
-│              📱 Your Phone                   │
-│           Rocket.Chat App                    │
-└─────────────┬───────────────────────────────┘
-              │ HTTPS (:443)
-┌─────────────▼───────────────────────────────┐
-│       Your Server (one machine does it all)  │
-│                                              │
-│  ┌──────────────────────────────────────┐   │
-│  │  Docker                               │   │
-│  │  ┌───────┐  ┌──────────┐  ┌───────┐  │   │
-│  │  │ Nginx │─▸│Rocket.Chat│─▸│MongoDB│  │   │
-│  │  │ :443  │  │  :3000   │  │       │  │   │
-│  │  │(HTTPS)│  │(internal)│  │       │  │   │
-│  │  └───────┘  └──────────┘  └───────┘  │   │
-│  └──────────────────────────────────────┘   │
-│                                              │
-│  ┌──────────────────────────────────────┐   │
-│  │  OpenClaw Gateway                     │   │
-│  │  @openclaw/rocketchat plugin          │   │
-│  │  ┌─────────────┐                     │   │
-│  │  │ Agent: main │                     │   │
-│  │  │ Agent: work │                     │   │
-│  │  └─────────────┘                     │   │
-│  └──────────────────────────────────────┘   │
-└──────────────────────────────────────────────┘
-```
-
-### Mode B: Split Deployment
-
-RC on a cloud VPS, OpenClaw on home network or low-spec machine. Great when you don't have a public IP or need to save memory.
-
-```
-┌─────────────────────────────────────────────┐
-│              📱 Your Phone                   │
-│           Rocket.Chat App                    │
-└─────────────┬───────────────────────────────┘
-              │ HTTPS (:443)
-┌─────────────▼───────────────────────────────┐
-│    Cloud VPS (cheap 1C1G is enough)          │
-│                                              │
-│  ┌──────────────────────────────────────┐   │
-│  │  Docker (install-rc.sh one-click)     │   │
-│  │  ┌───────┐  ┌──────────┐  ┌───────┐  │   │
-│  │  │ Nginx │─▸│Rocket.Chat│─▸│MongoDB│  │   │
-│  │  │ :443  │  │  :3000   │  │       │  │   │
-│  │  │(HTTPS)│  │(internal)│  │       │  │   │
-│  │  └───────┘  └─────▲────┘  └───────┘  │   │
-│  └───────────────────┼──────────────────┘   │
-└──────────────────────┼───────────────────────┘
-                       │ HTTPS/WebSocket (public network)
-┌──────────────────────┼───────────────────────┐
-│       Home Network / Local Machine            │
-│                      │                        │
-│  ┌───────────────────┴──────────────────┐    │
-│  │  OpenClaw Gateway                     │    │
-│  │  @openclaw/rocketchat plugin          │    │
-│  │  (connects to remote RC via internet) │    │
-│  │                                       │    │
-│  │  ┌─────────────┐                      │    │
-│  │  │ Agent: main │                      │    │
-│  │  │ Agent: work │                      │    │
-│  │  └─────────────┘                      │    │
-│  └───────────────────────────────────────┘    │
-└───────────────────────────────────────────────┘
-```
-
-> For Mode B, just run `install-rc.sh` on your remote VPS to install Rocket.Chat (with Nginx HTTPS + auto sslip.io domain), then run `openclaw rocketchat setup` locally and enter `https://VPS-IP.sslip.io`.
+Mode A (Co-located):  Phone → HTTPS → [Nginx + RC + MongoDB + OpenClaw] all on one machine
+Mode B (Split):       Phone → HTTPS → [VPS: Nginx + RC + MongoDB] ← WebSocket ← [Home LAN: OpenClaw]
+```
 
 ## FAQ
 
@@ -680,6 +695,8 @@ If you know the admin username/password, re-run setup and choose "Use existing a
 <details>
 <summary><b>How to reinstall the plugin / start completely fresh?</b></summary>
 
+> Full reset steps also at [docs/CONFIGURATION.en.md — Full Reset](docs/CONFIGURATION.en.md#full-reset)
+
 ```bash
 # 1. Stop Gateway
 openclaw gateway stop
@@ -792,13 +809,12 @@ Plain text, Markdown (with syntax highlighting), images, files, and voice messag
 Yes. Use `openclaw rocketchat add-user` to add more phone users (family, colleagues). Each person downloads Rocket.Chat and logs in with their own account.
 </details>
 
-## Tech Stack
+## More Documentation
 
-- **TypeScript** — Consistent with the OpenClaw ecosystem
-- **Rocket.Chat REST API** — User/group/message management
-- **Rocket.Chat WebSocket (DDP)** — Real-time message subscription
-- **Docker Compose** — One-click Rocket.Chat + MongoDB deployment
-- **Vitest** — Unit testing
+| Document | Content |
+|----------|---------|
+| [Configuration Reference](docs/CONFIGURATION.en.md) | Full parameter tables, JSON example, manual editing, full reset |
+| [Architecture & Comparison](docs/ARCHITECTURE.en.md) | Full comparison table, architecture diagrams, tech stack |
 
 ## Contributing