openclaw-bridge 0.3.0 → 0.3.1
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.
- package/README.md +119 -177
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,87 +1,86 @@
|
|
|
1
1
|
# openclaw-bridge
|
|
2
2
|
|
|
3
|
-
|
|
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
|
-
##
|
|
5
|
+
## What's Included
|
|
6
6
|
|
|
7
|
-
- **
|
|
8
|
-
- **
|
|
9
|
-
- **
|
|
10
|
-
- **
|
|
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
|
-
##
|
|
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
|
-
#
|
|
20
|
-
npm install -g openclaw-bridge
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
openclaw-bridge
|
|
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
|
-
|
|
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
|
-
|
|
48
|
+
### Adding a New Agent
|
|
29
49
|
|
|
30
50
|
```bash
|
|
31
|
-
openclaw
|
|
51
|
+
openclaw-bridge add-agent
|
|
32
52
|
```
|
|
33
53
|
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
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
|
-
|
|
59
|
+
### Backup
|
|
39
60
|
|
|
40
|
-
```
|
|
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
|
-
|
|
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
|
-
|
|
67
|
-
|
|
68
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
###
|
|
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
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
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
|
-
|
|
121
|
+
### Roles
|
|
123
122
|
|
|
124
|
-
|
|
|
125
|
-
|
|
126
|
-
| `
|
|
127
|
-
| `
|
|
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
|
|
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
|
-
| `
|
|
138
|
-
| `
|
|
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
|
-
|
|
138
|
+
## Local Manager
|
|
142
139
|
|
|
143
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
167
|
+
User ←→ Discord/Web ←→ Gateway Agent
|
|
167
168
|
↕ (WebSocket)
|
|
168
|
-
openclaw-bridge-hub (
|
|
169
|
+
openclaw-bridge-hub (:3080 + :9090 dashboard)
|
|
169
170
|
↕ (WebSocket)
|
|
170
|
-
|
|
171
|
+
Other Gateway Agents
|
|
171
172
|
```
|
|
172
173
|
|
|
173
|
-
- Each gateway runs one agent with this
|
|
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
|
-
##
|
|
179
|
-
|
|
180
|
-
After installing globally (`npm install -g openclaw-bridge`), the `openclaw-bridge` command is available:
|
|
180
|
+
## Cross-Platform
|
|
181
181
|
|
|
182
|
-
|
|
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
|
-
|
|
184
|
+
---
|
|
196
185
|
|
|
197
|
-
|
|
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
|
-
|
|
188
|
+
openclaw-bridge 是 [OpenClaw](https://github.com/nicepkg/openclaw) 的一站式客户端插件，提供跨网关通信、本地进程管理和完整的 CLI 工具。
|
|
204
189
|
|
|
205
|
-
|
|
206
|
-
openclaw-bridge add-agent
|
|
207
|
-
```
|
|
190
|
+
### 核心功能
|
|
208
191
|
|
|
209
|
-
|
|
210
|
-
-
|
|
211
|
-
-
|
|
212
|
-
-
|
|
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
|
-
###
|
|
197
|
+
### 快速开始
|
|
217
198
|
|
|
218
199
|
```bash
|
|
219
|
-
openclaw-bridge
|
|
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
|
-
|
|
223
|
-
|
|
224
|
-
## CLI 命令说明
|
|
225
|
-
|
|
226
|
-
安装后 (`npm install -g openclaw-bridge`)，可使用 `openclaw-bridge` 命令：
|
|
207
|
+
### CLI 命令
|
|
227
208
|
|
|
228
209
|
| 命令 | 说明 |
|
|
229
210
|
|------|------|
|
|
230
|
-
| `setup` | 交互式设置
|
|
231
|
-
| `status` | 查看 PM2 进程状态和 Hub
|
|
232
|
-
| `start` |
|
|
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` |
|
|
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
|
-
-
|
|
283
|
-
-
|
|
284
|
-
-
|
|
285
|
-
-
|
|
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.
|
|
3
|
+
"version": "0.3.1",
|
|
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",
|