@coclaw/openclaw-coclaw 0.12.2 → 0.12.3

package/README.md

@@ -1,10 +1,17 @@
 # @coclaw/openclaw-coclaw
 
-CoClaw 的 OpenClaw 插件（npm: `@coclaw/openclaw-coclaw`，plugin id: `openclaw-coclaw`），包含：
+CoClaw 的 OpenClaw 插件（npm: `@coclaw/openclaw-coclaw`，plugin id: `openclaw-coclaw`），运行在 OpenClaw gateway 进程中，是 CoClaw 与 OpenClaw 之间的核心连接层。
 
-- **transport bridge** — CoClaw server 与 OpenClaw gateway 之间的实时消息桥接
-- **session-manager** — 会话列表/读取能力（`nativeui.sessions.listAll` / `nativeui.sessions.get`）
+主要模块：
+
+- **realtime bridge** — CoClaw server 与 OpenClaw gateway 之间的 WebSocket 实时消息桥接，支持 RPC 转发和事件广播
+- **WebRTC peer** — 与 CoClaw UI 建立 WebRTC DataChannel 直连，提供 RPC 和文件传输两类通道
+- **session manager** — 会话列表/读取能力（`nativeui.sessions.listAll` / `nativeui.sessions.get`）
+- **chat history manager** — 跟踪和管理 chat reset 产生的孤儿 session（`coclaw.chatHistory.list`）
+- **topic manager** — 独立话题的创建、列表、标题生成与删除（`coclaw.topics.*`）
+- **file manager** — 工作区文件管理，支持通过 WebRTC DataChannel 流式传输和 gateway RPC 回退（`coclaw.files.*`）
 - **auto-upgrade** — 从 npm 安装的插件自动检查并升级到最新版本
+- **device identity** — Ed25519 密钥对管理，用于 gateway WebSocket 连接的设备认证
 
 ## 安装与模式切换
 
@@ -60,6 +67,41 @@ WAIT=1 pnpm run release:check -- 0.1.7     # 轮询直到版本生效
 pnpm run release:versions                  # 显示所有已发布版本
 ```
 
+## Gateway RPC 方法
+
+插件注册的所有 gateway method（通过 `openclaw gateway call <method>` 或 WebRTC DC 调用）：
+
+| 方法 | 说明 |
+|------|------|
+| `coclaw.bind` | 绑定 Claw 到 CoClaw server |
+| `coclaw.unbind` | 解绑并停止 bridge |
+| `coclaw.enroll` | 生成认领码，等待用户完成绑定 |
+| `coclaw.info` / `coclaw.info.get` | 获取插件版本、claw 版本、capabilities、名称、主机名 |
+| `coclaw.info.patch` | 修改 claw 显示名称，广播 `coclaw.info.updated` 事件 |
+| `coclaw.topics.create` | 创建话题 |
+| `coclaw.topics.list` | 列出指定 agent 的话题 |
+| `coclaw.topics.get` | 获取单个话题 |
+| `coclaw.topics.getHistory` | 获取话题对话记录 |
+| `coclaw.topics.update` | 更新话题标题 |
+| `coclaw.topics.generateTitle` | 通过 agent RPC 自动生成话题标题 |
+| `coclaw.topics.delete` | 删除话题及其 `.jsonl` 文件 |
+| `coclaw.chatHistory.list` | 列出 chat 的历史（孤儿）session |
+| `coclaw.sessions.getById` | 按 sessionId 获取消息记录 |
+| `coclaw.upgradeHealth` | 返回当前插件版本（升级健康检查） |
+| `coclaw.files.list` | 列出工作区文件（RPC 回退） |
+| `coclaw.files.delete` | 删除工作区文件/目录 |
+| `coclaw.files.mkdir` | 创建工作区目录 |
+| `coclaw.files.create` | 创建空文件 |
+| `nativeui.sessions.listAll` | 列出所有 session（分页 + 标题推导） |
+| `nativeui.sessions.get` | 获取 session 原始 JSONL 行（分页） |
+
+## Gateway Services
+
+| Service ID | 说明 |
+|------------|------|
+| `coclaw-realtime-bridge` | CoClaw server WebSocket 桥接 + WebRTC peer 管理 |
+| `coclaw-auto-upgrade` | npm 安装模式下的自动升级调度器 |
+
 ## 绑定 / 解绑
 
 绑定码从 CoClaw Web 端生成，有效期有限。
@@ -183,6 +225,19 @@ openclaw logs --limit 300 --plain | rg -n "gateway connect failed|protocol misma
 openclaw logs --limit 300 --plain | rg -n "ui->server req|bot->server res|bot->server event|gateway req" -i
 ```
 
+## 设置
+
+插件设置存储在 `~/.openclaw/coclaw/settings.json`，独立于绑定信息，解绑后重新绑定不会丢失。
+
+当前支持的设置项：
+- `name` — Claw 显示名称（可选，最长 63 字符），通过 `coclaw.info.patch` RPC 修改
+
+`settings.js` 是读写设置的唯一入口。
+
+## 设备身份
+
+插件在首次运行时自动生成 Ed25519 密钥对，存储在 `~/.openclaw/coclaw/device-identity.json`（mode 0o600）。`deviceId` 为公钥的 SHA-256 摘要，用于 gateway WebSocket 连接的设备认证（v3 auth payload）。
+
 ## 测试门禁
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coclaw/openclaw-coclaw",
-  "version": "0.12.2",
+  "version": "0.12.3",
   "type": "module",
   "license": "Apache-2.0",
   "description": "OpenClaw CoClaw channel plugin for remote chat",
@@ -60,7 +60,8 @@
   },
   "dependencies": {
     "node-datachannel": "0.32.2",
-    "werift": "^0.19.0"
+    "werift": "^0.19.0",
+    "ws": "^8.19.0"
   },
   "devDependencies": {
     "c8": "^10.1.3",

package/src/auto-upgrade/updater-check.js

@@ -37,7 +37,7 @@ export async function getLatestVersion(pkgName, opts) {
 	return new Promise((resolve, reject) => {
 		doExecFile('npm', ['view', pkgName, 'version'], {
 			timeout: 30_000,
-			shell: true,
+			shell: process.platform === 'win32',
 		}, (err, stdout) => {
 			if (err) {
 				reject(new Error(`npm view failed: ${err.message}`));

package/src/auto-upgrade/updater-spawn.js

@@ -52,6 +52,7 @@ export function spawnUpgradeWorker({ pluginDir, fromVersion, toVersion, pluginId
 		detached: true,
 		stdio: 'ignore',
 		env,
+		windowsHide: true,
 	});
 
 	// spawn 失败时 Node.js 会异步 emit 'error'；若无监听器则变为未捕获异常导致 gateway 崩溃

package/src/auto-upgrade/worker-verify.js

@@ -26,7 +26,7 @@ const CMD_TIMEOUT_MS = 30_000;
 function runCmd(cmd, args, opts) {
 	const doExecFile = opts?.execFileFn ?? nodeExecFile;
 	return new Promise((resolve, reject) => {
-		doExecFile(cmd, args, { timeout: CMD_TIMEOUT_MS, shell: true }, (err, stdout) => {
+		doExecFile(cmd, args, { timeout: CMD_TIMEOUT_MS, shell: process.platform === 'win32' }, (err, stdout) => {
 			if (err) reject(err);
 			else resolve(String(stdout).trim());
 		});

package/src/auto-upgrade/worker.js

@@ -9,7 +9,7 @@
  * 注意：
  * - 本模块作为独立 node 进程运行，与 gateway 进程隔离
  * - state dir 通过 OPENCLAW_STATE_DIR 环境变量由 spawner 传入
- * - shell: true 为 Windows 兼容性所需（openclaw 全局安装生成 .cmd 包装器）
+ * - shell 仅在 Windows 启用（openclaw 全局安装生成 .cmd 包装器，需 shell 解析）
  */
 
 import { execFile as nodeExecFile } from 'node:child_process';
@@ -34,7 +34,7 @@ function runPluginUpdate(pluginId, opts) {
 	return new Promise((resolve, reject) => {
 		doExecFile('openclaw', ['plugins', 'update', pluginId], {
 			timeout: 120_000,
-			shell: true,
+			shell: process.platform === 'win32',
 		}, (err) => {
 			if (err) reject(new Error(`plugins update failed: ${err.message}`));
 			else resolve();
@@ -63,7 +63,7 @@ async function fallbackInstallOldVersion(pkgName, version, pluginId, opts) {
 	}
 	const doExecFile = opts?.execFileFn ?? nodeExecFile;
 	const run = (args, timeout = 120_000) => new Promise((resolve, reject) => {
-		doExecFile('openclaw', args, { timeout, shell: true }, (err) => {
+		doExecFile('openclaw', args, { timeout, shell: process.platform === 'win32' }, (err) => {
 			if (err) reject(err);
 			else resolve();
 		});

package/src/cli-registrar.js

@@ -87,7 +87,7 @@ function handleRpcError(result, fallbackMsg) {
  * @param {object} ctx.logger - 日志实例
  * @param {object} [deps] - 可注入依赖（测试用）
  */
-export function registerCoclawCli({ program, logger }, deps = {}) {
+export function registerCoclawCli({ program, logger: _logger }, deps = {}) {
 	const coclaw = program
 		.command('coclaw')
 		.description('CoClaw bind/unbind commands');

package/src/realtime-bridge.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import nodePath from 'node:path';
+import { WebSocket as WsWebSocket } from 'ws';
 
 import { clearConfig, getBindingsPath, readConfig } from './config.js';
 import { getHostName, readSettings } from './settings.js';
@@ -85,7 +86,7 @@ export class RealtimeBridge {
 		this.__resolveGatewayAuthToken = deps.resolveGatewayAuthToken ?? defaultResolveGatewayAuthToken;
 		this.__loadDeviceIdentity = deps.loadDeviceIdentity ?? loadOrCreateDeviceIdentity;
 		this.__preloadNdc = deps.preloadNdc ?? null;
-		this.__WebSocket = deps.WebSocket ?? null;
+		this.__WebSocket = deps.WebSocket; // undefined=使用 ws 包, null=禁用（测试用）, 其他=自定义实现
 		this.__gatewayReadyTimeoutMs = deps.gatewayReadyTimeoutMs ?? 1500;
 
 		this.serverWs = null;
@@ -112,7 +113,7 @@ export class RealtimeBridge {
 	}
 
 	__resolveWebSocket() {
-		return this.__WebSocket ?? globalThis.WebSocket;
+		return this.__WebSocket === undefined ? WsWebSocket : this.__WebSocket;
 	}
 
 	__logDebug(message) {
@@ -226,7 +227,8 @@ export class RealtimeBridge {
 		this.webrtcPeer = new WebRtcPeer({
 			onSend: (msg) => this.__forwardToServer(msg),
 			onRequest: (dcPayload) => {
-				void this.__handleGatewayRequestFromServer(dcPayload);
+				this.__handleGatewayRequestFromDc(dcPayload)
+					.catch((err) => this.logger.warn?.(`[coclaw] dc request handler error: ${err?.message}`));
 			},
 			onFileRpc: (payload, sendFn) => {
 				this.__fileHandler.handleRpcRequest(payload, sendFn)
@@ -625,8 +627,6 @@ export class RealtimeBridge {
 				return;
 			}
 			if (payload.type === 'res' || payload.type === 'event') {
-				// TODO: UI 已通过 DataChannel 接收业务消息，待旧版 UI 全部更新后移除此转发
-				this.__forwardToServer(payload);
 				this.webrtcPeer?.broadcast(payload);
 			}
 		});
@@ -698,11 +698,11 @@ export class RealtimeBridge {
 		});
 	}
 
-	async __handleGatewayRequestFromServer(payload) {
+	async __handleGatewayRequestFromDc(payload) {
 		const ready = await this.__waitGatewayReady();
 		if (!ready || !this.gatewayWs || this.gatewayWs.readyState !== 1) {
 			this.__logDebug(`gateway req drop (offline): id=${payload.id} method=${payload.method}`);
-			const errorRes = {
+			this.webrtcPeer?.broadcast({
 				type: 'res',
 				id: payload.id,
 				ok: false,
@@ -710,9 +710,7 @@ export class RealtimeBridge {
 					code: 'GATEWAY_OFFLINE',
 					message: 'Gateway is offline',
 				},
-			};
-			this.__forwardToServer(errorRes);
-			this.webrtcPeer?.broadcast(errorRes);
+			});
 			return;
 		}
 		try {
@@ -725,7 +723,7 @@ export class RealtimeBridge {
 			}));
 		}
 		catch {
-			const errorRes = {
+			this.webrtcPeer?.broadcast({
 				type: 'res',
 				id: payload.id,
 				ok: false,
@@ -733,9 +731,7 @@ export class RealtimeBridge {
 					code: 'GATEWAY_SEND_FAILED',
 					message: 'Failed to send request to gateway',
 				},
-			};
-			this.__forwardToServer(errorRes);
-			this.webrtcPeer?.broadcast(errorRes);
+			});
 		}
 	}
 
@@ -848,13 +844,6 @@ export class RealtimeBridge {
 					}
 					return;
 				}
-				if (payload?.type === 'req' || payload?.type === 'rpc.req') {
-					void this.__handleGatewayRequestFromServer({
-						id: payload.id,
-						method: payload.method,
-						params: payload.params ?? {},
-					});
-				}
 			}
 			catch (err) {
 				this.logger.warn?.(`[coclaw] realtime message parse failed: ${String(err?.message ?? err)}`);
@@ -1029,7 +1018,8 @@ export async function restartRealtimeBridge(opts) {
 		await singleton.stop();
 		singleton = null;
 	}
-	singleton = new RealtimeBridge();
+	const deps = opts?.__deps; // 仅测试用
+	singleton = new RealtimeBridge(deps);
 	await singleton.start(opts);
 }
 

package/src/webrtc/webrtc-peer.js

@@ -236,8 +236,12 @@ export class WebRtcPeer {
 			this.__logDebug(`ICE candidate from ${connId} but no session`);
 			return;
 		}
-		await session.pc.addIceCandidate(msg.payload);
-		this.__logDebug(`[${connId}] ICE candidate added`);
+		try {
+			await session.pc.addIceCandidate(msg.payload);
+			this.__logDebug(`[${connId}] ICE candidate added`);
+		} catch (err) {
+			this.__logDebug(`[${connId}] addIceCandidate failed: ${err?.message}`);
+		}
 	}
 
 	__setupDataChannel(connId, dc) {