openclaw-bridge 0.3.0 → 0.3.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +119 -177
  2. package/package.json +1 -1
  3. package/src/heartbeat.ts +11 -7
package/README.md CHANGED
@@ -1,87 +1,86 @@
1
1
  # openclaw-bridge
2
2
 
3
- 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.
3
+ 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.
4
4
 
5
- ## Features
5
+ ## What's Included
6
6
 
7
- - **Agent Discovery** — Auto-register and discover online agents via heartbeat
8
- - **File Transfer** — Send files between agents (local or cross-machine via Hub)
9
- - **Message Relay** — Send messages to any agent through the Hub and get replies
10
- - **Session Handoff** — Transfer active conversations between agents seamlessly
11
- - **Superuser Tools** — Read/write files and restart remote gateways
12
- - **Auto-Config** — Automatically patches `openclaw.json` with recommended settings on first run
7
+ - **Cross-Gateway Communication** — Agent discovery, file transfer, message relay, and session handoff
8
+ - **Local Manager** — PM2-based process management with remote control via Hub
9
+ - **CLI Tools** — Setup, status, start/stop/restart, log viewing, backup, agent creation, diagnostics
10
+ - **Auto-Config** — Automatically patches missing settings on first run
13
11
 
14
- ## Prerequisites
15
-
16
- You need [openclaw-bridge-hub](https://www.npmjs.com/package/openclaw-bridge-hub) (v0.2.4+) running on a reachable server first:
12
+ ## Quick Start
17
13
 
18
14
  ```bash
19
- # On your server:
20
- npm install -g openclaw-bridge-hub
21
- openclaw-bridge-hub init # generates API key — save it!
22
- openclaw-bridge-hub start # starts on port 3080
23
- openclaw-bridge-hub install-service # auto-start on boot (Linux)
15
+ # 1. Install globally
16
+ npm install -g openclaw-bridge
17
+
18
+ # 2. Interactive setup (Hub URL, API key, manager password)
19
+ openclaw-bridge setup
20
+
21
+ # 3. Check your environment
22
+ openclaw-bridge doctor
23
+
24
+ # 4. Start all gateway instances
25
+ openclaw-bridge start
26
+
27
+ # 5. Verify everything is running
28
+ openclaw-bridge status
24
29
  ```
25
30
 
26
- Save the generated API key you'll need it for the plugin config below.
31
+ **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+.
32
+
33
+ ## CLI Commands
34
+
35
+ | Command | Description |
36
+ |---------|-------------|
37
+ | `setup` | Interactive setup — configure Hub URL, API key, and manager password |
38
+ | `status` | Show PM2 process status and Hub connection |
39
+ | `start` | Find and start all openclaw instances via PM2 ecosystem |
40
+ | `stop` | Stop all openclaw instances |
41
+ | `restart [agent]` | Restart a specific agent or all |
42
+ | `logs [agent]` | View PM2 logs for an agent (last 100 lines) |
43
+ | `backup` | Create encrypted backup of openclaw-instances |
44
+ | `clean-sessions` | Remove old/deleted session files to free disk space |
45
+ | `add-agent` | Wizard to create a new agent instance |
46
+ | `doctor` | Diagnose environment issues (PM2, Node, ports, Hub) |
27
47
 
28
- ## Installation
48
+ ### Adding a New Agent
29
49
 
30
50
  ```bash
31
- openclaw plugins install openclaw-bridge
51
+ openclaw-bridge add-agent
32
52
  ```
33
53
 
34
- Or manually: place this plugin in a directory listed in `plugins.load.paths` of your `openclaw.json`.
35
-
36
- ## Configuration
54
+ The wizard prompts for agent name, ID, description, and AI model. It automatically:
55
+ - Assigns the next available port
56
+ - Creates the directory with `openclaw.json`, `run.sh`, `run.ps1`
57
+ - Updates `ecosystem.config.cjs`
37
58
 
38
- Add to `openclaw.json` under `plugins.entries` (replace the API key and server URL with your own):
59
+ ### Backup
39
60
 
40
- ```json
41
- {
42
- "plugins": {
43
- "entries": {
44
- "openclaw-bridge": {
45
- "config": {
46
- "role": "normal",
47
- "agentId": "my-agent",
48
- "agentName": "My Agent",
49
- "registry": {
50
- "baseUrl": "http://your-server:3080",
51
- "apiKey": "your-hub-api-key"
52
- },
53
- "fileRelay": {
54
- "baseUrl": "http://your-server:3080",
55
- "apiKey": "your-hub-api-key"
56
- }
57
- }
58
- }
59
- }
60
- }
61
- }
61
+ ```bash
62
+ openclaw-bridge backup
62
63
  ```
63
64
 
64
- ### New Config Fields
65
+ Creates an encrypted tar.gz archive. Config files are encrypted with AES-256-CBC. Excludes node_modules, state, workspace, and logs.
65
66
 
66
- | Field | Type | Description |
67
- |-------|------|-------------|
68
- | `description` | string | Short description shown on the Hub dashboard agent card |
69
- | `supportsVision` | boolean | Whether this agent accepts image inputs. Auto-detected from the gateway model config if not set. |
70
- | `localManager` | object | Local Manager settings — see [Local Manager](#local-manager) section below |
67
+ ---
68
+
69
+ ## Plugin Configuration
71
70
 
72
- Example with all new fields:
71
+ The plugin is also loaded by each OpenClaw gateway instance for cross-agent communication. Add to `openclaw.json`:
73
72
 
74
73
  ```json
75
74
  {
76
75
  "plugins": {
77
76
  "entries": {
78
77
  "openclaw-bridge": {
78
+ "enabled": true,
79
79
  "config": {
80
80
  "role": "normal",
81
81
  "agentId": "my-agent",
82
82
  "agentName": "My Agent",
83
- "description": "Handles project management tasks and sprint planning",
84
- "supportsVision": false,
83
+ "description": "Handles project management and sprint planning",
85
84
  "registry": {
86
85
  "baseUrl": "http://your-server:3080",
87
86
  "apiKey": "your-hub-api-key"
@@ -102,57 +101,59 @@ Example with all new fields:
102
101
  }
103
102
  ```
104
103
 
105
- ### Local Manager
106
-
107
- 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.
108
-
109
- **Requirements:**
104
+ ### Config Fields
110
105
 
111
- - PM2 installed globally: `npm install -g pm2`
112
- - A running `openclaw-bridge-hub` server
113
-
114
- **How it works:**
115
-
116
- - On startup, the plugin checks if `localManager.enabled` is `true`
117
- - Only one Local Manager process runs per machine (enforced via a lock file)
118
- - It connects to Hub at `localManager.hubUrl` over `/ws/manager` and authenticates with `localManager.managerPass`
119
- - The Hub dashboard can then send `start`, `stop`, and `restart` commands for any gateway on that machine
120
- - PM2 reports process status (running state, memory, uptime) back to the Hub every heartbeat cycle
106
+ | Field | Type | Description |
107
+ |-------|------|-------------|
108
+ | `role` | `"normal"` \| `"superuser"` | Agent permission level |
109
+ | `agentId` | string | Unique identifier (e.g., `pm`, `director`) |
110
+ | `agentName` | string | Display name (e.g., `PM Bot`, `Director`) |
111
+ | `description` | string | Short description shown on Hub dashboard |
112
+ | `supportsVision` | boolean | Accept image inputs. Auto-detected from model config if not set |
113
+ | `registry.baseUrl` | string | Hub server URL |
114
+ | `registry.apiKey` | string | Hub API key |
115
+ | `fileRelay.baseUrl` | string | Hub server URL (same as registry) |
116
+ | `fileRelay.apiKey` | string | Hub API key (same as registry) |
117
+ | `localManager.enabled` | boolean | Enable Local Manager on this machine |
118
+ | `localManager.hubUrl` | string | Hub server URL |
119
+ | `localManager.managerPass` | string | Password set via `openclaw-bridge-hub manager-pass` |
121
120
 
122
- **Config fields:**
121
+ ### Roles
123
122
 
124
- | Field | Type | Default | Description |
125
- |-------|------|---------|-------------|
126
- | `localManager.enabled` | boolean | `false` | Enable Local Manager on this machine |
127
- | `localManager.hubUrl` | string | (required) | Full URL of the Hub server, e.g. `http://your-server:3080` |
128
- | `localManager.managerPass` | string | (required) | Password set via `openclaw-bridge-hub manager-pass` |
123
+ | Role | Capabilities |
124
+ |------|-------------|
125
+ | `normal` | discover, whois, send_file, send_message, handoff |
126
+ | `superuser` | All of normal + read_file, write_file, restart |
129
127
 
130
- ### Auto-configured settings
128
+ ### Auto-configured Settings
131
129
 
132
130
  On first startup, the plugin automatically adds these if missing:
133
131
 
134
132
  | Setting | Value | Purpose |
135
133
  |---------|-------|---------|
136
134
  | `messageRelay.url` | Derived from `fileRelay.baseUrl` | WebSocket connection to Hub |
137
- | `messageRelay.apiKey` | Same as `fileRelay.apiKey` | Hub authentication |
138
- | `gateway.http.endpoints.chatCompletions.enabled` | `true` | Required for message relay processing |
139
- | `channels.discord.accounts.*.dmHistoryLimit` | `0` | Fast DM responses (OpenViking handles memory) |
135
+ | `gateway.http.endpoints.chatCompletions.enabled` | `true` | Required for message relay |
136
+ | `channels.discord.accounts.*.dmHistoryLimit` | `0` | Fast DM responses |
140
137
 
141
- ### Roles
138
+ ## Local Manager
142
139
 
143
- | Role | Capabilities |
144
- |------|-------------|
145
- | `normal` | discover, whois, send_file, send_message, handoff |
146
- | `superuser` | All of normal + read_file, write_file, restart |
140
+ 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.
147
141
 
148
- ## Tools
142
+ - Only one instance runs per machine (enforced via lock file)
143
+ - Reports process status (running state, memory, uptime) and logs every 30 seconds
144
+ - Handles remote commands from Hub dashboard
145
+ - Starts automatically when `localManager.enabled: true` in any gateway's bridge config
146
+
147
+ ## Bridge Tools
148
+
149
+ These tools are available to agents during conversations:
149
150
 
150
151
  | Tool | Description |
151
152
  |------|-------------|
152
153
  | `bridge_discover` | List all online agents |
153
154
  | `bridge_whois` | Get details for a specific agent |
154
155
  | `bridge_send_file` | Send a file to another agent's inbox |
155
- | `bridge_send_message` | Send a message and wait for reply (relay mode) |
156
+ | `bridge_send_message` | Send a message and wait for reply |
156
157
  | `bridge_handoff` | Hand off conversation to another agent |
157
158
  | `bridge_handoff_end` | End handoff and return to original agent |
158
159
  | `bridge_handoff_switch` | Switch handoff to a different agent |
@@ -163,126 +164,67 @@ On first startup, the plugin automatically adds these if missing:
163
164
  ## Architecture
164
165
 
165
166
  ```
166
- User ←→ Discord DM ←→ Main Gateway
167
+ User ←→ Discord/Web ←→ Gateway Agent
167
168
  ↕ (WebSocket)
168
- openclaw-bridge-hub (port 3080)
169
+ openclaw-bridge-hub (:3080 + :9090 dashboard)
169
170
  ↕ (WebSocket)
170
- PM Gateway / Bot1-4
171
+ Other Gateway Agents
171
172
  ```
172
173
 
173
- - Each gateway runs one agent with this shared plugin
174
+ - Each gateway runs one agent with this plugin
174
175
  - Plugin auto-registers to Hub, heartbeats every 30 seconds
175
176
  - Messages and handoffs route through Hub WebSocket (`/ws`)
176
177
  - File transfers use local filesystem (same machine) or Hub relay (cross-machine)
178
+ - Local Manager connects to Hub via `/ws/manager` for remote control
177
179
 
178
- ## CLI Commands
179
-
180
- After installing globally (`npm install -g openclaw-bridge`), the `openclaw-bridge` command is available:
180
+ ## Cross-Platform
181
181
 
182
- | Command | Description |
183
- |---------|-------------|
184
- | `setup` | Interactive setup — configure Hub URL, API key, and manager password |
185
- | `status` | Show PM2 process status and Hub connection |
186
- | `start` | Find and start all openclaw instances via PM2 ecosystem |
187
- | `stop` | Stop all openclaw instances |
188
- | `restart [agent]` | Restart a specific agent or all |
189
- | `logs [agent]` | View PM2 logs for an agent (last 100 lines) |
190
- | `backup` | Create encrypted backup of openclaw-instances |
191
- | `clean-sessions` | Remove old/deleted session files to free disk space |
192
- | `add-agent` | Wizard to create a new agent instance |
193
- | `doctor` | Diagnose environment issues (PM2, Node, ports, Hub) |
182
+ 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.
194
183
 
195
- ### Quick Start
184
+ ---
196
185
 
197
- 1. Install the plugin: `npm install -g openclaw-bridge`
198
- 2. Run setup: `openclaw-bridge setup`
199
- 3. Check environment: `openclaw-bridge doctor`
200
- 4. Start all agents: `openclaw-bridge start`
201
- 5. Check status: `openclaw-bridge status`
186
+ ## 中文说明
202
187
 
203
- ### Adding a New Agent
188
+ openclaw-bridge [OpenClaw](https://github.com/nicepkg/openclaw) 的一站式客户端插件,提供跨网关通信、本地进程管理和完整的 CLI 工具。
204
189
 
205
- ```bash
206
- openclaw-bridge add-agent
207
- ```
190
+ ### 核心功能
208
191
 
209
- The wizard will prompt for:
210
- - Agent name and ID
211
- - Description
212
- - AI model selection
213
- - Automatically assigns the next available port
214
- - Creates directory, config files, and updates PM2 ecosystem
192
+ - **跨网关通信** Agent 发现、文件传输、消息中继、会话交接
193
+ - **本地管理器** 基于 PM2 的进程管理,支持通过 Hub 远程控制
194
+ - **CLI 工具** — 设置、状态查看、启停重启、日志、备份、创建 Agent、环境诊断
195
+ - **自动配置** 首次启动自动补全推荐配置
215
196
 
216
- ### Backup & Restore
197
+ ### 快速开始
217
198
 
218
199
  ```bash
219
- openclaw-bridge backup
200
+ npm install -g openclaw-bridge # 安装
201
+ openclaw-bridge setup # 配置 Hub 连接
202
+ openclaw-bridge doctor # 检查环境
203
+ openclaw-bridge start # 启动所有实例
204
+ openclaw-bridge status # 查看状态
220
205
  ```
221
206
 
222
- Creates an encrypted backup archive. Config files are encrypted with AES-256-CBC. Excludes node_modules, state, workspace, and logs.
223
-
224
- ## CLI 命令说明
225
-
226
- 安装后 (`npm install -g openclaw-bridge`),可使用 `openclaw-bridge` 命令:
207
+ ### CLI 命令
227
208
 
228
209
  | 命令 | 说明 |
229
210
  |------|------|
230
- | `setup` | 交互式设置 — 配置 Hub 地址、API 密钥和管理密码 |
231
- | `status` | 查看 PM2 进程状态和 Hub 连接情况 |
232
- | `start` | 查找并启动所有 openclaw 实例 |
211
+ | `setup` | 交互式设置 Hub 地址、API 密钥、管理密码 |
212
+ | `status` | 查看 PM2 进程状态和 Hub 连接 |
213
+ | `start` | 启动所有 openclaw 实例 |
233
214
  | `stop` | 停止所有实例 |
234
215
  | `restart [agent]` | 重启指定或全部 agent |
235
216
  | `logs [agent]` | 查看 agent 日志(最近100行) |
236
217
  | `backup` | 创建加密备份 |
237
- | `clean-sessions` | 清理旧会话文件释放磁盘空间 |
238
- | `add-agent` | 向导式创建新 agent 实例 |
239
- | `doctor` | 环境诊断(PM2、Node、端口、Hub 连接) |
240
-
241
- ### 快速开始
242
-
243
- 1. 安装插件:`npm install -g openclaw-bridge`
244
- 2. 运行设置:`openclaw-bridge setup`
245
- 3. 检查环境:`openclaw-bridge doctor`
246
- 4. 启动所有 agent:`openclaw-bridge start`
247
- 5. 查看状态:`openclaw-bridge status`
248
-
249
- ## Mac Compatibility
250
-
251
- 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.
252
-
253
- ## Requirements
254
-
255
- - [openclaw-bridge-hub](https://www.npmjs.com/package/openclaw-bridge-hub) v0.2.4+ running on a reachable server
256
- - OpenClaw gateway 2026.3.24+
257
-
258
- ---
259
-
260
- ## 中文说明
261
-
262
- openclaw-bridge 是 [OpenClaw](https://github.com/nicepkg/openclaw) 的跨网关通信插件,让独立运行的 Agent 网关之间能够互相发现、传输文件、实时传话和无缝切换对话。
263
-
264
- ### 核心功能
265
-
266
- - **Agent 发现** — 通过心跳自动注册和发现在线 Agent
267
- - **文件传输** — Agent 之间发送文件(同机直传,跨机走 Hub 中转)
268
- - **消息中继** — 通过 Hub 向任意 Agent 发消息并等待回复(传话模式)
269
- - **会话交接** — 将对话无缝切换给其他 Agent(Handoff 模式)
270
- - **超级用户工具** — 读写远程 Agent 文件、重启远程网关
271
- - **自动配置** — 首次启动时自动补全推荐配置项
272
-
273
- ### 快速开始
274
-
275
- 1. 先在服务器部署 [openclaw-bridge-hub](https://www.npmjs.com/package/openclaw-bridge-hub)
276
- 2. 安装本插件:`openclaw plugins install openclaw-bridge`
277
- 3. 在 `openclaw.json` 中配置 Hub 地址和 API Key
278
- 4. 启动网关,插件会自动注册和连接
218
+ | `clean-sessions` | 清理旧会话文件 |
219
+ | `add-agent` | 向导式创建新 agent |
220
+ | `doctor` | 环境诊断 |
279
221
 
280
222
  ### 使用场景
281
223
 
282
- - 用户在 DM 中让 Main Bot 传话给 PM Bot
283
- - 用户要求切换到其他 Bot 继续对话,无需换频道
284
- - 跨机器部署的 Agent 之间互相通信
285
- - Superuser 远程管理其他 Agent 的文件和生命周期
224
+ - 多台电脑部署 Agent,统一通过 Hub 互相通信和管理
225
+ - 用户让 Main Bot 传话给其他 Bot,或直接切换对话
226
+ - 通过 Hub Dashboard 远程监控和重启 Agent
227
+ - 一键备份整个 OpenClaw 实例,跨平台迁移部署
286
228
 
287
229
  ## Author
288
230
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "openclaw-bridge",
3
- "version": "0.3.0",
3
+ "version": "0.3.2",
4
4
  "author": "Bill Zhao (https://www.linkedin.com/in/billzhaodi/)",
5
5
  "description": "Cross-gateway communication plugin for OpenClaw — agent discovery, file transfer, real-time messaging, and session handoff",
6
6
  "type": "module",
package/src/heartbeat.ts CHANGED
@@ -90,10 +90,11 @@ export class BridgeHeartbeat {
90
90
  }
91
91
 
92
92
  private detectVisionSupport(): boolean {
93
+ // Explicit config override takes priority
93
94
  if (this.config.supportsVision !== undefined) {
94
95
  return this.config.supportsVision;
95
96
  }
96
- if (!this.configPath) return false;
97
+ if (!this.configPath) return true; // Default to true — most models support vision
97
98
  try {
98
99
  const raw = readFileSync(this.configPath, "utf-8");
99
100
  const config = JSON.parse(raw) as {
@@ -102,14 +103,17 @@ export class BridgeHeartbeat {
102
103
  list?: Array<{ id?: string; name?: string }>;
103
104
  };
104
105
  };
105
- const defaultModel = config.models?.default ?? "";
106
- const visionPatterns = [
107
- "gpt-4o", "gpt-4-vision", "claude-3", "claude-sonnet", "claude-opus",
108
- "gemini", "gemini-pro", "gemini-2", "pixtral", "llava",
106
+ const defaultModel = (config.models?.default ?? "").toLowerCase();
107
+ if (!defaultModel) return true;
108
+ // Known text-only models that do NOT support vision
109
+ const textOnlyPatterns = [
110
+ "minimax", "m2.7", "deepseek-r1", "deepseek-v2", "qwen-turbo",
111
+ "yi-lightning", "glm-3", "glm-4-flash", "mistral-small",
112
+ "codestral", "command-r", "phi-3-mini", "phi-3-small",
109
113
  ];
110
- return visionPatterns.some((p) => defaultModel.toLowerCase().includes(p));
114
+ return !textOnlyPatterns.some((p) => defaultModel.includes(p));
111
115
  } catch {
112
- return false;
116
+ return true;
113
117
  }
114
118
  }
115
119