openclaw-bridge 0.2.2 → 0.3.0

package/README.md

@@ -61,6 +61,72 @@ Add to `openclaw.json` under `plugins.entries` (replace the API key and server U
 }
 ```
 
+### New Config Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `description` | string | Short description shown on the Hub dashboard agent card |
+| `supportsVision` | boolean | Whether this agent accepts image inputs. Auto-detected from the gateway model config if not set. |
+| `localManager` | object | Local Manager settings — see [Local Manager](#local-manager) section below |
+
+Example with all new fields:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "openclaw-bridge": {
+        "config": {
+          "role": "normal",
+          "agentId": "my-agent",
+          "agentName": "My Agent",
+          "description": "Handles project management tasks and sprint planning",
+          "supportsVision": false,
+          "registry": {
+            "baseUrl": "http://your-server:3080",
+            "apiKey": "your-hub-api-key"
+          },
+          "fileRelay": {
+            "baseUrl": "http://your-server:3080",
+            "apiKey": "your-hub-api-key"
+          },
+          "localManager": {
+            "enabled": true,
+            "hubUrl": "http://your-server:3080",
+            "managerPass": "your-manager-password"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Local Manager
+
+Installing `openclaw-bridge` now bundles a **Local Manager** that handles PM2 process management for your gateway instances on your local machine. It connects to the Hub via WebSocket so the Hub dashboard can remotely start, stop, and restart individual gateways.
+
+**Requirements:**
+
+- PM2 installed globally: `npm install -g pm2`
+- A running `openclaw-bridge-hub` server
+
+**How it works:**
+
+- On startup, the plugin checks if `localManager.enabled` is `true`
+- Only one Local Manager process runs per machine (enforced via a lock file)
+- It connects to Hub at `localManager.hubUrl` over `/ws/manager` and authenticates with `localManager.managerPass`
+- The Hub dashboard can then send `start`, `stop`, and `restart` commands for any gateway on that machine
+- PM2 reports process status (running state, memory, uptime) back to the Hub every heartbeat cycle
+
+**Config fields:**
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `localManager.enabled` | boolean | `false` | Enable Local Manager on this machine |
+| `localManager.hubUrl` | string | (required) | Full URL of the Hub server, e.g. `http://your-server:3080` |
+| `localManager.managerPass` | string | (required) | Password set via `openclaw-bridge-hub manager-pass` |
+
 ### Auto-configured settings
 
 On first startup, the plugin automatically adds these if missing:
@@ -109,6 +175,81 @@ User ←→ Discord DM ←→ Main Gateway
 - Messages and handoffs route through Hub WebSocket (`/ws`)
 - File transfers use local filesystem (same machine) or Hub relay (cross-machine)
 
+## CLI Commands
+
+After installing globally (`npm install -g openclaw-bridge`), the `openclaw-bridge` command is available:
+
+| Command | Description |
+|---------|-------------|
+| `setup` | Interactive setup — configure Hub URL, API key, and manager password |
+| `status` | Show PM2 process status and Hub connection |
+| `start` | Find and start all openclaw instances via PM2 ecosystem |
+| `stop` | Stop all openclaw instances |
+| `restart [agent]` | Restart a specific agent or all |
+| `logs [agent]` | View PM2 logs for an agent (last 100 lines) |
+| `backup` | Create encrypted backup of openclaw-instances |
+| `clean-sessions` | Remove old/deleted session files to free disk space |
+| `add-agent` | Wizard to create a new agent instance |
+| `doctor` | Diagnose environment issues (PM2, Node, ports, Hub) |
+
+### Quick Start
+
+1. Install the plugin: `npm install -g openclaw-bridge`
+2. Run setup: `openclaw-bridge setup`
+3. Check environment: `openclaw-bridge doctor`
+4. Start all agents: `openclaw-bridge start`
+5. Check status: `openclaw-bridge status`
+
+### Adding a New Agent
+
+```bash
+openclaw-bridge add-agent
+```
+
+The wizard will prompt for:
+- Agent name and ID
+- Description
+- AI model selection
+- Automatically assigns the next available port
+- Creates directory, config files, and updates PM2 ecosystem
+
+### Backup & Restore
+
+```bash
+openclaw-bridge backup
+```
+
+Creates an encrypted backup archive. Config files are encrypted with AES-256-CBC. Excludes node_modules, state, workspace, and logs.
+
+## CLI 命令说明
+
+安装后 (`npm install -g openclaw-bridge`)，可使用 `openclaw-bridge` 命令：
+
+| 命令 | 说明 |
+|------|------|
+| `setup` | 交互式设置 — 配置 Hub 地址、API 密钥和管理密码 |
+| `status` | 查看 PM2 进程状态和 Hub 连接情况 |
+| `start` | 查找并启动所有 openclaw 实例 |
+| `stop` | 停止所有实例 |
+| `restart [agent]` | 重启指定或全部 agent |
+| `logs [agent]` | 查看 agent 日志（最近100行） |
+| `backup` | 创建加密备份 |
+| `clean-sessions` | 清理旧会话文件释放磁盘空间 |
+| `add-agent` | 向导式创建新 agent 实例 |
+| `doctor` | 环境诊断（PM2、Node、端口、Hub 连接） |
+
+### 快速开始
+
+1. 安装插件：`npm install -g openclaw-bridge`
+2. 运行设置：`openclaw-bridge setup`
+3. 检查环境：`openclaw-bridge doctor`
+4. 启动所有 agent：`openclaw-bridge start`
+5. 查看状态：`openclaw-bridge status`
+
+## Mac Compatibility
+
+The same plugin code runs on both **Windows** and **macOS** without modification. The Local Manager and orphan process cleanup routines use cross-platform detection — on Windows they use `taskkill`, on macOS/Linux they use `kill` signals. PM2 itself is cross-platform, so the full feature set (start/stop/restart, log streaming, process metrics) works identically on both platforms.
+
 ## Requirements
 
 - [openclaw-bridge-hub](https://www.npmjs.com/package/openclaw-bridge-hub) v0.2.4+ running on a reachable server

package/openclaw.plugin.json

@@ -31,6 +31,26 @@
     "fileRelay.apiKey": {
       "label": "FileRelay API Key",
       "sensitive": true
+    },
+    "description": {
+      "label": "Agent Description",
+      "help": "Short description of what this agent does (shown on Hub dashboard)"
+    },
+    "supportsVision": {
+      "label": "Supports Vision",
+      "help": "Whether the agent's model can process images (auto-detected if not set)"
+    },
+    "localManager.enabled": {
+      "label": "Enable Local Manager",
+      "help": "Start PM2 process manager for this machine"
+    },
+    "localManager.hubUrl": {
+      "label": "Hub URL for Local Manager",
+      "placeholder": "http://your-server:3080"
+    },
+    "localManager.managerPass": {
+      "label": "Manager Password",
+      "sensitive": true
     }
   },
   "configSchema": {
@@ -65,7 +85,17 @@
         }
       },
       "heartbeatIntervalMs": { "type": "number" },
-      "offlineThresholdMs": { "type": "number" }
+      "offlineThresholdMs": { "type": "number" },
+      "description": { "type": "string" },
+      "supportsVision": { "type": "boolean" },
+      "localManager": {
+        "type": "object",
+        "properties": {
+          "enabled": { "type": "boolean" },
+          "hubUrl": { "type": "string" },
+          "managerPass": { "type": "string" }
+        }
+      }
     }
   }
 }

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "openclaw-bridge",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "author": "Bill Zhao (https://www.linkedin.com/in/billzhaodi/)",
   "description": "Cross-gateway communication plugin for OpenClaw — agent discovery, file transfer, real-time messaging, and session handoff",
   "type": "module",
   "main": "src/index.ts",
+  "bin": {
+    "openclaw-bridge": "src/cli.ts"
+  },
   "openclaw": {
     "extensions": [
       "./src/index.ts"