openclaw-rocketchat 0.4.2 → 0.4.3

package/README.en.md

@@ -641,70 +641,109 @@ All config is written automatically by CLI commands into `~/.openclaw/openclaw.j
 
 ### channels.rocketchat — Channel Config
 
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `enabled` | `boolean` | Enable/disable the Rocket.Chat channel |
-| `serverUrl` | `string` | Rocket.Chat server URL, e.g. `"https://123-45-67-89.sslip.io"` |
-| `accounts` | `object` | Bot accounts. Key is the account ID |
-| `accounts.<id>.botUsername` | `string` | Bot's username in RC |
-| `accounts.<id>.botDisplayName` | `string` | Bot's display name |
-| `groups` | `object` | Group config (optional). Key is group name |
-| `groups.<name>.bots` | `string[]` | Bots in this group |
-| `groups.<name>.requireMention` | `boolean` | Whether bot requires @mention to respond in groups |
+| 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
 
-The `bindings` array maps bot accounts to Agents:
+The `bindings` array maps bot accounts to Agents (written by `add-bot` command):
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `agentId` | `string` | The Agent ID to bind to (e.g. `"main"`) |
+| `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 `accounts` |
+| `match.accountId` | `string` | Matches a key in `channels.rocketchat.accounts` |
 
-### plugins.entries — Plugin State
+### plugins — Plugin Config
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `openclaw-rocketchat.enabled` | `boolean` | Whether the plugin is enabled |
+| `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.4.2"` |
+| `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) |
 
 ### Full Config Example
 
+Below shows the Rocket.Chat plugin-related sections of `~/.openclaw/openclaw.json` (omitting `meta`, `auth`, `models`, `agents`, `gateway`, and other unrelated sections):
+
 ```json5
 {
-  // Agents managed by openclaw agents add
-  "agents": {
-    "list": [
-      { "id": "main", "default": true },
-      { "id": "work", "name": "Work Helper" }
-    ]
-  },
-
-  // Bot → Agent bindings (written by add-bot)
-  "bindings": [
-    { "agentId": "main", "match": { "channel": "rocketchat", "accountId": "molty" } },
-    { "agentId": "work", "match": { "channel": "rocketchat", "accountId": "work-claw" } }
-  ],
-
-  // Rocket.Chat channel config (written by setup / add-bot)
+  // Rocket.Chat channel config (written by setup / add-bot / add-group)
   "channels": {
     "rocketchat": {
       "enabled": true,
-      "serverUrl": "https://123-45-67-89.sslip.io",
+      "serverUrl": "https://127.0.0.1",     // Use 127.0.0.1 for co-located; use sslip.io domain for remote
+      "port": 443,                            // Rocket.Chat HTTPS port
+      "dmPolicy": "pairing",                  // DM policy
       "accounts": {
-        "molty": { "botUsername": "molty", "botDisplayName": "Lobster" },
-        "work-claw": { "botUsername": "work-claw", "botDisplayName": "Work Helper" }
+        "molty": {                            // Bot 1
+          "botUsername": "molty",
+          "botDisplayName": "Lobster"
+        },
+        "work-bot": {                         // Bot 2 (optional, multiple bots)
+          "botUsername": "work-bot",
+          "botDisplayName": "Work Helper"
+        }
       },
-      "groups": {
-        "AI Squad": { "requireMention": false, "bots": ["molty", "work-claw"] }
+      "groups": {                             // Groups (optional)
+        "AI Squad": {
+          "requireMention": false,            // Responds to all messages
+          "bots": ["molty", "work-bot"]       // Bots in this group
+        },
+        "Tech Talk": {
+          "requireMention": true,             // Only responds when @mentioned
+          "bots": ["molty"]
+        }
       }
     }
   },
 
+  // Bot → Agent bindings (written by add-bot)
+  "bindings": [
+    {
+      "agentId": "main",                      // Bound to main Agent
+      "match": {
+        "channel": "rocketchat",
+        "accountId": "molty"                   // Matches key in accounts
+      }
+    },
+    {
+      "agentId": "work",                      // Different bots can bind to different Agents
+      "match": {
+        "channel": "rocketchat",
+        "accountId": "work-bot"
+      }
+    }
+  ],
+
   // Plugin state
   "plugins": {
     "entries": {
       "openclaw-rocketchat": { "enabled": true }
+    },
+    "installs": {
+      "openclaw-rocketchat": {
+        "source": "npm",
+        "spec": "openclaw-rocketchat@0.4.2",
+        "installPath": "/root/.openclaw/extensions/openclaw-rocketchat",
+        "version": "0.4.2",
+        "installedAt": "2026-02-15T07:37:17.498Z"
+      }
     }
   }
 }
@@ -718,20 +757,56 @@ If auto-configuration has issues, edit `~/.openclaw/openclaw.json` directly:
 # Edit config
 vi ~/.openclaw/openclaw.json
 
-# Restart gateway to apply changes
+# Restart Gateway to apply changes
 openclaw gateway restart
 ```
 
 **Common manual edits:**
 
-- **Change server URL**: Edit `channels.rocketchat.serverUrl`
-- **Disable/enable channel**: Edit `channels.rocketchat.enabled`
+- **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.
 
+### Full Reset
+
+To completely remove Rocket.Chat config and start over:
+
+```bash
+# Stop Gateway
+openclaw gateway stop
+
+# Remove plugin and credentials
+rm -rf ~/.openclaw/extensions/openclaw-rocketchat
+rm -rf ~/.openclaw/credentials/rocketchat*
+
+# Remove RC-related config entries
+python3 -c "
+import json
+p = '$HOME/.openclaw/openclaw.json'
+with open(p) as f:
+    c = json.load(f)
+c.get('channels', {}).pop('rocketchat', None)
+c['bindings'] = [b for b in c.get('bindings', []) if b.get('match', {}).get('channel') != 'rocketchat']
+c.get('plugins', {}).get('entries', {}).pop('openclaw-rocketchat', None)
+c.get('plugins', {}).get('entries', {}).pop('rocketchat', None)
+c.get('plugins', {}).get('installs', {}).pop('openclaw-rocketchat', None)
+with open(p, 'w') as f:
+    json.dump(c, f, indent=2, ensure_ascii=False)
+print('Done')
+"
+
+# Reinstall and reconfigure
+openclaw plugins install openclaw-rocketchat
+openclaw rocketchat setup
+openclaw rocketchat add-bot
+```
+
 ## Architecture
 
 ### Mode A: Co-located

package/README.md

@@ -641,70 +641,109 @@ openclaw rocketchat uninstall
 
 ### channels.rocketchat — 频道配置
 
-| 参数 | 类型 | 说明 |
-|------|------|------|
-| `enabled` | `boolean` | 是否启用 Rocket.Chat 频道。`true` 启用，`false` 禁用 |
-| `serverUrl` | `string` | Rocket.Chat 服务器地址，如 `"https://123-45-67-89.sslip.io"`。Gateway 通过此地址连接 RC |
-| `accounts` | `object` | 机器人账号列表，key 为账号 ID |
-| `accounts.<id>.botUsername` | `string` | 机器人在 RC 中的用户名 |
-| `accounts.<id>.botDisplayName` | `string` | 机器人显示昵称 |
-| `groups` | `object` | 群组配置（可选），key 为群组名 |
-| `groups.<name>.bots` | `string[]` | 群组中的机器人列表 |
-| `groups.<name>.requireMention` | `boolean` | 群组中是否需要 @提及 机器人才回复 |
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `enabled` | `boolean` | `false` | 是否启用 Rocket.Chat 频道 |
+| `serverUrl` | `string` | — | Rocket.Chat 服务器地址，如 `"https://123-45-67-89.sslip.io"` 或 `"https://127.0.0.1"`（同机部署） |
+| `port` | `number` | `443` | Rocket.Chat 对外 HTTPS 端口（`install-rc.sh` 安装时指定的端口） |
+| `dmPolicy` | `string` | `"pairing"` | 私聊策略。`"pairing"` 表示 setup 时自动为用户和机器人创建 DM 通道 |
+| `accounts` | `object` | `{}` | 机器人账号列表，key 为机器人 ID（由 `add-bot` 命令自动写入） |
+| `accounts.<id>.botUsername` | `string` | — | 机器人在 Rocket.Chat 中的用户名 |
+| `accounts.<id>.botDisplayName` | `string` | — | 机器人显示昵称（可中文） |
+| `groups` | `object` | `{}` | 群组配置（由 `add-group` 命令自动写入），key 为群组名 |
+| `groups.<name>.bots` | `string[]` | — | 群组中的机器人列表（对应 `accounts` 的 key） |
+| `groups.<name>.requireMention` | `boolean` | `false` | 群内是否需要 `@机器人名` 才回复。`false`：所有消息都回复；`true`：只有 `@机器人` 才回复（多机器人群推荐开启，避免抢答） |
+
+> **关于群内广播提及**：`@here`、`@all`、`@everyone` 这类广播提及不会触发机器人回复，即使 `requireMention` 为 `false`。只有直接 `@机器人名` 才会触发。
 
 ### bindings — Agent 绑定
 
-`bindings` 数组将机器人账号绑定到 Agent：
+`bindings` 数组将机器人账号绑定到 Agent（由 `add-bot` 命令自动写入）：
 
 | 参数 | 类型 | 说明 |
 |------|------|------|
-| `agentId` | `string` | 绑定的 Agent ID（如 `"main"`） |
+| `agentId` | `string` | 绑定的 Agent ID（如 `"main"`）。通过 `openclaw agents add` 创建 |
 | `match.channel` | `string` | 固定为 `"rocketchat"` |
-| `match.accountId` | `string` | 对应 `accounts` 中的 key |
+| `match.accountId` | `string` | 对应 `channels.rocketchat.accounts` 中的 key |
 
-### plugins.entries — 插件状态
+### plugins — 插件配置
 
 | 参数 | 类型 | 说明 |
 |------|------|------|
-| `openclaw-rocketchat.enabled` | `boolean` | 插件是否启用 |
+| `entries.openclaw-rocketchat.enabled` | `boolean` | 插件是否启用。Gateway 启动时自动检测并设为 `true` |
+| `installs.openclaw-rocketchat.source` | `string` | 安装来源，通常为 `"npm"` |
+| `installs.openclaw-rocketchat.spec` | `string` | 安装的包版本，如 `"openclaw-rocketchat@0.4.2"` |
+| `installs.openclaw-rocketchat.installPath` | `string` | 插件安装路径，如 `"~/.openclaw/extensions/openclaw-rocketchat"` |
+| `installs.openclaw-rocketchat.version` | `string` | 当前安装版本号 |
+| `installs.openclaw-rocketchat.installedAt` | `string` | 安装时间（ISO 格式） |
 
 ### 完整配置示例
 
+以下展示 `~/.openclaw/openclaw.json` 中与 Rocket.Chat 插件相关的配置（省略了 `meta`、`auth`、`models`、`agents`、`gateway` 等与插件无关的部分）：
+
 ```json5
 {
-  // Agent 由 openclaw agents add 管理
-  "agents": {
-    "list": [
-      { "id": "main", "default": true },
-      { "id": "work", "name": "工作助手" }
-    ]
-  },
-
-  // 机器人 → Agent 绑定（由 add-bot 自动写入）
-  "bindings": [
-    { "agentId": "main", "match": { "channel": "rocketchat", "accountId": "molty" } },
-    { "agentId": "work", "match": { "channel": "rocketchat", "accountId": "work-claw" } }
-  ],
-
-  // Rocket.Chat 频道配置（由 setup / add-bot 自动写入）
+  // Rocket.Chat 频道配置（由 setup / add-bot / add-group 自动写入）
   "channels": {
     "rocketchat": {
       "enabled": true,
-      "serverUrl": "https://123-45-67-89.sslip.io",
+      "serverUrl": "https://127.0.0.1",     // 同机部署用 127.0.0.1；远程部署填 sslip.io 域名
+      "port": 443,                            // Rocket.Chat HTTPS 端口
+      "dmPolicy": "pairing",                  // 私聊策略
       "accounts": {
-        "molty": { "botUsername": "molty", "botDisplayName": "小龙虾" },
-        "work-claw": { "botUsername": "work-claw", "botDisplayName": "工作助手" }
+        "molty": {                            // 机器人 1
+          "botUsername": "molty",
+          "botDisplayName": "小龙虾"
+        },
+        "work-bot": {                         // 机器人 2（可选，多个机器人）
+          "botUsername": "work-bot",
+          "botDisplayName": "工作助手"
+        }
       },
-      "groups": {
-        "AI全能群": { "requireMention": false, "bots": ["molty", "work-claw"] }
+      "groups": {                             // 群组（可选）
+        "AI全能群": {
+          "requireMention": false,            // 所有消息都回复
+          "bots": ["molty", "work-bot"]       // 群内的机器人
+        },
+        "技术讨论": {
+          "requireMention": true,             // 只有 @机器人 才回复
+          "bots": ["molty"]
+        }
       }
     }
   },
 
+  // 机器人 → Agent 绑定（由 add-bot 自动写入）
+  "bindings": [
+    {
+      "agentId": "main",                      // 绑定到 main Agent
+      "match": {
+        "channel": "rocketchat",
+        "accountId": "molty"                   // 对应 accounts 中的 key
+      }
+    },
+    {
+      "agentId": "work",                      // 不同机器人可绑定不同 Agent
+      "match": {
+        "channel": "rocketchat",
+        "accountId": "work-bot"
+      }
+    }
+  ],
+
   // 插件状态
   "plugins": {
     "entries": {
       "openclaw-rocketchat": { "enabled": true }
+    },
+    "installs": {
+      "openclaw-rocketchat": {
+        "source": "npm",
+        "spec": "openclaw-rocketchat@0.4.2",
+        "installPath": "/root/.openclaw/extensions/openclaw-rocketchat",
+        "version": "0.4.2",
+        "installedAt": "2026-02-15T07:37:17.498Z"
+      }
     }
   }
 }
@@ -718,20 +757,56 @@ openclaw rocketchat uninstall
 # 编辑配置
 vi ~/.openclaw/openclaw.json
 
-# 修改后重启 gateway 生效
+# 修改后重启 Gateway 生效
 openclaw gateway restart
 ```
 
 **常见手动修改场景：**
 
-- **更换服务器地址**：修改 `channels.rocketchat.serverUrl`
-- **禁用/启用频道**：修改 `channels.rocketchat.enabled`
+- **更换服务器地址**：修改 `channels.rocketchat.serverUrl`（同机部署填 `https://127.0.0.1`，远程部署填 `https://IP.sslip.io`）
+- **更换端口**：修改 `channels.rocketchat.port`
+- **禁用/启用频道**：修改 `channels.rocketchat.enabled` 为 `false` / `true`
 - **修改机器人绑定的 Agent**：修改 `bindings` 数组中对应条目的 `agentId`
 - **删除机器人**：从 `accounts` 和 `bindings` 中删除对应条目
 - **修改群组的 @提及 规则**：修改 `groups.<name>.requireMention`
+- **升级插件版本**：修改 `plugins.installs.openclaw-rocketchat.version` 和 `spec`
 
 > **注意**: 机器人的凭据（密码、token）存储在 `~/.openclaw/credentials/` 目录下，与 `openclaw.json` 分离。如果重装机器人，需要同时清理凭据文件。
 
+### 完全重置 Rocket.Chat 配置
+
+如果需要从头开始，运行以下命令清除所有 Rocket.Chat 相关配置：
+
+```bash
+# 停止 Gateway
+openclaw gateway stop
+
+# 清除插件和凭据
+rm -rf ~/.openclaw/extensions/openclaw-rocketchat
+rm -rf ~/.openclaw/credentials/rocketchat*
+
+# 清除配置中的 Rocket.Chat 相关项
+python3 -c "
+import json
+p = '$HOME/.openclaw/openclaw.json'
+with open(p) as f:
+    c = json.load(f)
+c.get('channels', {}).pop('rocketchat', None)
+c['bindings'] = [b for b in c.get('bindings', []) if b.get('match', {}).get('channel') != 'rocketchat']
+c.get('plugins', {}).get('entries', {}).pop('openclaw-rocketchat', None)
+c.get('plugins', {}).get('entries', {}).pop('rocketchat', None)
+c.get('plugins', {}).get('installs', {}).pop('openclaw-rocketchat', None)
+with open(p, 'w') as f:
+    json.dump(c, f, indent=2, ensure_ascii=False)
+print('Done')
+"
+
+# 重新安装和配置
+openclaw plugins install openclaw-rocketchat
+openclaw rocketchat setup
+openclaw rocketchat add-bot
+```
+
 ## 架构
 
 ### 方式 A：同机部署

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-rocketchat",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "Rocket.Chat channel plugin for OpenClaw — connect via mobile app, ideal for China mainland users",
   "type": "module",
   "main": "./dist/index.js",