openclaw-bridge 0.2.2 → 0.3.1

package/README.md

@@ -1,51 +1,86 @@
 # openclaw-bridge
 
-Cross-gateway communication plugin for [OpenClaw](https://github.com/nicepkg/openclaw). Enables independent gateway instances to discover each other, exchange files, relay messages, and hand off conversations.
+The all-in-one client plugin for [OpenClaw](https://github.com/nicepkg/openclaw) distributed gateway architecture. Provides cross-gateway communication, local process management, and a full CLI for managing your OpenClaw agents.
 
-## Features
+## What's Included
 
-- **Agent Discovery** — Auto-register and discover online agents via heartbeat
-- **File Transfer** — Send files between agents (local or cross-machine via Hub)
-- **Message Relay** — Send messages to any agent through the Hub and get replies
-- **Session Handoff** — Transfer active conversations between agents seamlessly
-- **Superuser Tools** — Read/write files and restart remote gateways
-- **Auto-Config** — Automatically patches `openclaw.json` with recommended settings on first run
+- **Cross-Gateway Communication** — Agent discovery, file transfer, message relay, and session handoff
+- **Local Manager** — PM2-based process management with remote control via Hub
+- **CLI Tools** — Setup, status, start/stop/restart, log viewing, backup, agent creation, diagnostics
+- **Auto-Config** — Automatically patches missing settings on first run
 
-## Prerequisites
+## Quick Start
 
-You need [openclaw-bridge-hub](https://www.npmjs.com/package/openclaw-bridge-hub) (v0.2.4+) running on a reachable server first:
+```bash
+# 1. Install globally
+npm install -g openclaw-bridge
+
+# 2. Interactive setup (Hub URL, API key, manager password)
+openclaw-bridge setup
+
+# 3. Check your environment
+openclaw-bridge doctor
+
+# 4. Start all gateway instances
+openclaw-bridge start
+
+# 5. Verify everything is running
+openclaw-bridge status
+```
+
+**Prerequisites:** [openclaw-bridge-hub](https://www.npmjs.com/package/openclaw-bridge-hub) running on a server, PM2 installed globally (`npm install -g pm2`), Node.js 18+.
+
+## CLI Commands
+
+| 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) |
+
+### Adding a New Agent
 
 ```bash
-# On your server:
-npm install -g openclaw-bridge-hub
-openclaw-bridge-hub init          # generates API key — save it!
-openclaw-bridge-hub start         # starts on port 3080
-openclaw-bridge-hub install-service  # auto-start on boot (Linux)
+openclaw-bridge add-agent
 ```
 
-Save the generated API key — you'll need it for the plugin config below.
+The wizard prompts for agent name, ID, description, and AI model. It automatically:
+- Assigns the next available port
+- Creates the directory with `openclaw.json`, `run.sh`, `run.ps1`
+- Updates `ecosystem.config.cjs`
 
-## Installation
+### Backup
 
 ```bash
-openclaw plugins install openclaw-bridge
+openclaw-bridge backup
 ```
 
-Or manually: place this plugin in a directory listed in `plugins.load.paths` of your `openclaw.json`.
+Creates an encrypted tar.gz archive. Config files are encrypted with AES-256-CBC. Excludes node_modules, state, workspace, and logs.
+
+---
 
-## Configuration
+## Plugin Configuration
 
-Add to `openclaw.json` under `plugins.entries` (replace the API key and server URL with your own):
+The plugin is also loaded by each OpenClaw gateway instance for cross-agent communication. Add to `openclaw.json`:
 
 ```json
 {
   "plugins": {
     "entries": {
       "openclaw-bridge": {
+        "enabled": true,
         "config": {
           "role": "normal",
           "agentId": "my-agent",
           "agentName": "My Agent",
+          "description": "Handles project management and sprint planning",
           "registry": {
             "baseUrl": "http://your-server:3080",
             "apiKey": "your-hub-api-key"
@@ -53,6 +88,11 @@ Add to `openclaw.json` under `plugins.entries` (replace the API key and server U
           "fileRelay": {
             "baseUrl": "http://your-server:3080",
             "apiKey": "your-hub-api-key"
+          },
+          "localManager": {
+            "enabled": true,
+            "hubUrl": "http://your-server:3080",
+            "managerPass": "your-manager-password"
           }
         }
       }
@@ -61,32 +101,59 @@ Add to `openclaw.json` under `plugins.entries` (replace the API key and server U
 }
 ```
 
-### Auto-configured settings
+### Config Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `role` | `"normal"` \| `"superuser"` | Agent permission level |
+| `agentId` | string | Unique identifier (e.g., `pm`, `director`) |
+| `agentName` | string | Display name (e.g., `PM Bot`, `Director`) |
+| `description` | string | Short description shown on Hub dashboard |
+| `supportsVision` | boolean | Accept image inputs. Auto-detected from model config if not set |
+| `registry.baseUrl` | string | Hub server URL |
+| `registry.apiKey` | string | Hub API key |
+| `fileRelay.baseUrl` | string | Hub server URL (same as registry) |
+| `fileRelay.apiKey` | string | Hub API key (same as registry) |
+| `localManager.enabled` | boolean | Enable Local Manager on this machine |
+| `localManager.hubUrl` | string | Hub server URL |
+| `localManager.managerPass` | string | Password set via `openclaw-bridge-hub manager-pass` |
+
+### Roles
+
+| Role | Capabilities |
+|------|-------------|
+| `normal` | discover, whois, send_file, send_message, handoff |
+| `superuser` | All of normal + read_file, write_file, restart |
+
+### Auto-configured Settings
 
 On first startup, the plugin automatically adds these if missing:
 
 | Setting | Value | Purpose |
 |---------|-------|---------|
 | `messageRelay.url` | Derived from `fileRelay.baseUrl` | WebSocket connection to Hub |
-| `messageRelay.apiKey` | Same as `fileRelay.apiKey` | Hub authentication |
-| `gateway.http.endpoints.chatCompletions.enabled` | `true` | Required for message relay processing |
-| `channels.discord.accounts.*.dmHistoryLimit` | `0` | Fast DM responses (OpenViking handles memory) |
+| `gateway.http.endpoints.chatCompletions.enabled` | `true` | Required for message relay |
+| `channels.discord.accounts.*.dmHistoryLimit` | `0` | Fast DM responses |
 
-### Roles
+## Local Manager
 
-| Role | Capabilities |
-|------|-------------|
-| `normal` | discover, whois, send_file, send_message, handoff |
-| `superuser` | All of normal + read_file, write_file, restart |
+The Local Manager handles PM2 process management for your gateway instances. It connects to the Hub via WebSocket so the Hub dashboard can remotely start, stop, and restart gateways.
+
+- Only one instance runs per machine (enforced via lock file)
+- Reports process status (running state, memory, uptime) and logs every 30 seconds
+- Handles remote commands from Hub dashboard
+- Starts automatically when `localManager.enabled: true` in any gateway's bridge config
+
+## Bridge Tools
 
-## Tools
+These tools are available to agents during conversations:
 
 | Tool | Description |
 |------|-------------|
 | `bridge_discover` | List all online agents |
 | `bridge_whois` | Get details for a specific agent |
 | `bridge_send_file` | Send a file to another agent's inbox |
-| `bridge_send_message` | Send a message and wait for reply (relay mode) |
+| `bridge_send_message` | Send a message and wait for reply |
 | `bridge_handoff` | Hand off conversation to another agent |
 | `bridge_handoff_end` | End handoff and return to original agent |
 | `bridge_handoff_switch` | Switch handoff to a different agent |
@@ -97,51 +164,67 @@ On first startup, the plugin automatically adds these if missing:
 ## Architecture
 
 ```
-User ←→ Discord DM ←→ Main Gateway
+User ←→ Discord/Web ←→ Gateway Agent
                             ↕ (WebSocket)
-                      openclaw-bridge-hub (port 3080)
+                      openclaw-bridge-hub (:3080 + :9090 dashboard)
                             ↕ (WebSocket)
-                       PM Gateway / Bot1-4
+                       Other Gateway Agents
 ```
 
-- Each gateway runs one agent with this shared plugin
+- Each gateway runs one agent with this plugin
 - Plugin auto-registers to Hub, heartbeats every 30 seconds
 - Messages and handoffs route through Hub WebSocket (`/ws`)
 - File transfers use local filesystem (same machine) or Hub relay (cross-machine)
+- Local Manager connects to Hub via `/ws/manager` for remote control
 
-## Requirements
+## Cross-Platform
 
-- [openclaw-bridge-hub](https://www.npmjs.com/package/openclaw-bridge-hub) v0.2.4+ running on a reachable server
-- OpenClaw gateway 2026.3.24+
+Same code runs on **Windows** and **macOS** without modification. Local Manager and orphan process cleanup use platform detection. PM2 is cross-platform, so start/stop/restart, logs, and process metrics work identically on both.
 
 ---
 
 ## 中文说明
 
-openclaw-bridge 是 [OpenClaw](https://github.com/nicepkg/openclaw) 的跨网关通信插件，让独立运行的 Agent 网关之间能够互相发现、传输文件、实时传话和无缝切换对话。
+openclaw-bridge 是 [OpenClaw](https://github.com/nicepkg/openclaw) 的一站式客户端插件，提供跨网关通信、本地进程管理和完整的 CLI 工具。
 
 ### 核心功能
 
-- **Agent 发现** — 通过心跳自动注册和发现在线 Agent
-- **文件传输** — Agent 之间发送文件（同机直传，跨机走 Hub 中转）
-- **消息中继** — 通过 Hub 向任意 Agent 发消息并等待回复（传话模式）
-- **会话交接** — 将对话无缝切换给其他 Agent（Handoff 模式）
-- **超级用户工具** — 读写远程 Agent 文件、重启远程网关
-- **自动配置** — 首次启动时自动补全推荐配置项
+- **跨网关通信** — Agent 发现、文件传输、消息中继、会话交接
+- **本地管理器** — 基于 PM2 的进程管理，支持通过 Hub 远程控制
+- **CLI 工具** — 设置、状态查看、启停重启、日志、备份、创建 Agent、环境诊断
+- **自动配置** — 首次启动自动补全推荐配置
 
 ### 快速开始
 
-1. 先在服务器部署 [openclaw-bridge-hub](https://www.npmjs.com/package/openclaw-bridge-hub)
-2. 安装本插件：`openclaw plugins install openclaw-bridge`
-3. 在 `openclaw.json` 中配置 Hub 地址和 API Key
-4. 启动网关，插件会自动注册和连接
+```bash
+npm install -g openclaw-bridge    # 安装
+openclaw-bridge setup             # 配置 Hub 连接
+openclaw-bridge doctor            # 检查环境
+openclaw-bridge start             # 启动所有实例
+openclaw-bridge status            # 查看状态
+```
+
+### CLI 命令
+
+| 命令 | 说明 |
+|------|------|
+| `setup` | 交互式设置 Hub 地址、API 密钥、管理密码 |
+| `status` | 查看 PM2 进程状态和 Hub 连接 |
+| `start` | 启动所有 openclaw 实例 |
+| `stop` | 停止所有实例 |
+| `restart [agent]` | 重启指定或全部 agent |
+| `logs [agent]` | 查看 agent 日志（最近100行） |
+| `backup` | 创建加密备份 |
+| `clean-sessions` | 清理旧会话文件 |
+| `add-agent` | 向导式创建新 agent |
+| `doctor` | 环境诊断 |
 
 ### 使用场景
 
-- 用户在 DM 中让 Main Bot 传话给 PM Bot
-- 用户要求切换到其他 Bot 继续对话，无需换频道
-- 跨机器部署的 Agent 之间互相通信
-- Superuser 远程管理其他 Agent 的文件和生命周期
+- 多台电脑部署 Agent，统一通过 Hub 互相通信和管理
+- 用户让 Main Bot 传话给其他 Bot，或直接切换对话
+- 通过 Hub Dashboard 远程监控和重启 Agent
+- 一键备份整个 OpenClaw 实例，跨平台迁移部署
 
 ## Author
 

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.1",
   "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"