@coclaw/openclaw-coclaw 0.9.2 → 0.10.0

package/README.md

@@ -137,6 +137,25 @@ openclaw gateway call coclaw.upgradeHealth --json
 
 详见设计文档 `docs/auto-upgrade.md`。
 
+## WebRTC 实现
+
+插件支持两个 WebRTC 实现，运行时自动选择：
+
+1. **node-datachannel**（首选）— 基于 libdatachannel 的工业级实现，通过 vendor 预编译 native binary 部署。
+2. **werift**（回退）— 纯 JavaScript 实现，作为 node-datachannel 加载失败时的兜底。
+
+选择结果通过 remoteLog 上报（`ndc.loaded` 或 `ndc.using-werift`）。
+
+### vendor 预编译包
+
+由于 OpenClaw 使用 `--ignore-scripts` 安装插件，node-datachannel 的 native binary 需通过 vendor 预编译包提供：
+
+```bash
+bash scripts/download-ndc-prebuilds.sh   # 下载 5 平台预编译包到 vendor/ndc-prebuilds/
+```
+
+支持的平台：linux-x64、linux-arm64、darwin-x64、darwin-arm64、win32-x64。vendor 目录不入 git，通过 npm publish 的 `files` 字段包含在发布包中。
+
 ## 运行与排障日志
 
 ### 日志级别建议
@@ -176,10 +195,8 @@ openclaw logs --limit 300 --plain | rg -n "ui->server req|bot->server res|bot->s
 ## 测试门禁
 
 ```bash
-pnpm check       # lint + typecheck
-pnpm test         # 全部单测
-pnpm coverage     # 覆盖率检查
-pnpm verify       # 完整验证（check → test:standalone → test:plugin → test → coverage）
+pnpm check        # lint + typecheck
+pnpm test         # 测试 + 覆盖率检查
 ```
 
 覆盖率阈值：lines/statements/functions 100%，branches ≥ 95%。未通过禁止接入 gateway。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coclaw/openclaw-coclaw",
-  "version": "0.9.2",
+  "version": "0.10.0",
   "type": "module",
   "license": "Apache-2.0",
   "description": "OpenClaw CoClaw channel plugin for remote chat",
@@ -32,6 +32,7 @@
     "!src/**/*.test.js",
     "!src/mock-server.helper.js",
     "openclaw.plugin.json",
+    "vendor/ndc-prebuilds/**",
     "LICENSE"
   ],
   "main": "index.js",
@@ -49,11 +50,9 @@
     "lint": "eslint \"**/*.{js,mjs,cjs}\" --no-error-on-unmatched-pattern",
     "typecheck": "echo \"No typecheck configured yet (coclaw openclaw plugin)\"",
     "check": "pnpm lint && pnpm typecheck",
-    "test:standalone": "node --test src/standalone-mode.test.js",
     "test:plugin": "node --test src/plugin-mode.test.js",
-    "test": "node --test",
-    "coverage": "c8 --check-coverage --lines 100 --functions 100 --branches 95 --statements 100 --reporter=text --reporter=lcov node --test",
-    "verify": "pnpm check && pnpm coverage",
+    "test": "c8 --check-coverage --lines 100 --functions 100 --branches 95 --statements 100 --reporter=text --reporter=lcov bash -c 'for f in src/**/*.test.js src/*.test.js index.test.js; do node --test \"$f\" || exit 1; done'",
+    "verify": "pnpm check && pnpm test",
     "link": "bash ./scripts/link.sh",
     "unlink": "bash ./scripts/unlink.sh",
     "install:npm": "bash ./scripts/install-npm.sh",
@@ -64,6 +63,7 @@
     "release:versions": "npm view @coclaw/openclaw-coclaw versions --json --registry=https://registry.npmjs.org/ && npm view @coclaw/openclaw-coclaw versions --json"
   },
   "dependencies": {
+    "node-datachannel": "0.32.1",
     "werift": "^0.19.0"
   },
   "devDependencies": {

package/src/auto-upgrade/updater.js

@@ -5,6 +5,7 @@ import { checkForUpdate } from './updater-check.js';
 import { spawnUpgradeWorker } from './updater-spawn.js';
 import { resolveStateDir } from './state.js';
 import { getRuntime } from '../runtime.js';
+import { remoteLog } from '../remote-log.js';
 
 const INITIAL_DELAY_MS = 5 * 60 * 1000; // 5 分钟
 const CHECK_INTERVAL_MS = 60 * 60 * 1000; // 1 小时
@@ -203,6 +204,7 @@ export class AutoUpgradeScheduler {
 			// 若上一次 spawn 的 worker 仍在运行，跳过本次检查
 			const isLocked = this.__opts.isUpgradeLockedFn ?? isUpgradeLocked;
 			if (await isLocked({ logger: this.__logger })) {
+				remoteLog('upgrade.worker-locked');
 				this.__logger.info?.('[auto-upgrade] Upgrade worker still running, skipping check');
 				return;
 			}
@@ -221,11 +223,13 @@ export class AutoUpgradeScheduler {
 				return;
 			}
 
+			remoteLog(`upgrade.available from=${result.currentVersion} to=${result.latestVersion}`);
 			this.__logger.info?.(`[auto-upgrade] Update available: ${result.currentVersion} → ${result.latestVersion}`);
 
 			const getInstallPath = this.__opts.getPluginInstallPathFn ?? getPluginInstallPath;
 			const pluginDir = getInstallPath(this.__pluginId);
 			if (!pluginDir) {
+				remoteLog('upgrade.no-install-path');
 				this.__logger.warn?.('[auto-upgrade] Cannot determine plugin install path');
 				return;
 			}
@@ -245,6 +249,7 @@ export class AutoUpgradeScheduler {
 			await writeLock(child.pid);
 		}
 		catch (err) {
+			remoteLog(`upgrade.check-failed msg=${err.message}`);
 			this.__logger.warn?.(`[auto-upgrade] Check failed: ${err.message}`);
 		}
 		finally {

package/src/config.js

@@ -42,8 +42,10 @@ async function readJson(filePath) {
 	try {
 		return JSON.parse(raw);
 	}
-	catch {
+	catch (err) {
 		// 文件损坏，删除后当空文件处理
+		/* c8 ignore next -- ?./?? fallback */
+		console.warn?.(`[coclaw] corrupt bindings file deleted: ${filePath} (${String(err?.message ?? err)})`);
 		await fs.unlink(filePath).catch(() => {});
 		return {};
 	}

package/src/device-identity.js

@@ -115,8 +115,10 @@ export function loadOrCreateDeviceIdentity(filePath) {
 			}
 		}
 	}
-	catch {
-		// 读取/解析失败时重新生成
+	catch (err) {
+		// 读取/解析失败时重新生成（将产生新 deviceId，需重新 enroll）
+		/* c8 ignore next -- ?./?? fallback */
+		console.warn?.(`[coclaw] device identity read failed, regenerating: ${String(err?.message ?? err)}`);
 	}
 
 	const identity = generateIdentity();

package/src/ndc-preloader.js

@@ -0,0 +1,191 @@
+import { createRequire } from 'module';
+import nodePath from 'path';
+import fsSync from 'fs';
+import fsPromises from 'fs/promises';
+import { remoteLog as defaultRemoteLog } from './remote-log.js';
+
+const SUPPORTED_PLATFORMS = new Set([
+	'linux-x64',
+	'linux-arm64',
+	'darwin-x64',
+	'darwin-arm64',
+	'win32-x64',
+]);
+
+const DEFAULT_IMPORT_TIMEOUT_MS = 10_000;
+
+/**
+ * 给 promise 加超时保护。超时后 reject，但原 promise 仍在后台执行——
+ * JS 无法取消 pending 的 import()，超时只是让调用方不再等待。
+ * @param {Promise} promise
+ * @param {number} ms
+ * @param {string} label - 用于错误信息
+ */
+function withTimeout(promise, ms, label) {
+	// 超时后原 promise 仍在后台执行（JS 无法取消 pending 的 import()）。
+	// 必须 .catch 兜住原 promise 的潜在 rejection，否则超时场景下
+	// 原 promise 最终 reject 会成为 unhandled rejection，导致进程终止。
+	promise.catch(() => {});
+	let timer;
+	const timeout = new Promise((_, reject) => {
+		timer = setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms);
+		timer.unref?.();
+	});
+	return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
+}
+
+/**
+ * 解析 vendor 源和部署目标路径。
+ * @param {string} platformKey - 如 'linux-x64'
+ * @param {string} pluginRoot - 插件根目录
+ * @returns {{ src: string, dest: string, destDir: string }}
+ */
+export function defaultResolvePaths(platformKey, pluginRoot) {
+	const src = nodePath.join(pluginRoot, 'vendor', 'ndc-prebuilds', platformKey, 'node_datachannel.node');
+
+	// 定位 node-datachannel 包根：从入口路径向上查找 package.json
+	const require = createRequire(nodePath.join(pluginRoot, 'package.json'));
+	const entryPath = require.resolve('node-datachannel');
+	let pkgRoot = nodePath.dirname(entryPath);
+	while (pkgRoot !== nodePath.dirname(pkgRoot)) {
+		try {
+			const pkg = JSON.parse(fsSync.readFileSync(nodePath.join(pkgRoot, 'package.json'), 'utf8'));
+			if (pkg.name === 'node-datachannel') break;
+		} catch { /* 继续向上 */ }
+		pkgRoot = nodePath.dirname(pkgRoot);
+	}
+	const destDir = nodePath.join(pkgRoot, 'build', 'Release');
+	const dest = nodePath.join(destDir, 'node_datachannel.node');
+
+	return { src, dest, destDir };
+}
+
+/**
+ * 预加载 WebRTC 实现：优先 node-datachannel，失败回退 werift，全部失败返回 null。
+ *
+ * **此函数永不 throw**——所有异常内部捕获，通过 remoteLog 报告。
+ * 返回值始终为 { PeerConnection, cleanup, impl } 结构。
+ *
+ * @param {object} [deps] - 可注入依赖（测试用）
+ * @param {object} [deps.fs] - { access, copyFile, mkdir }
+ * @param {Function} [deps.dynamicImport] - (specifier) => import(specifier)
+ * @param {Function} [deps.remoteLog] - (text) => void
+ * @param {string} [deps.platform] - 覆盖 process.platform
+ * @param {string} [deps.arch] - 覆盖 process.arch
+ * @param {string} [deps.pluginRoot] - 覆盖插件根目录
+ * @param {Function} [deps.resolvePaths] - (platformKey, pluginRoot) => { src, dest, destDir }
+ * @param {number} [deps.importTimeout] - 动态 import 超时（ms），默认 10s
+ * @returns {Promise<{ PeerConnection: Function|null, cleanup: Function|null, impl: string }>}
+ */
+export async function preloadNdc(deps = {}) {
+	const fs = deps.fs ?? fsPromises;
+	const dynamicImport = deps.dynamicImport ?? ((spec) => import(spec));
+	const log = deps.remoteLog ?? defaultRemoteLog;
+	const platform = deps.platform ?? process.platform;
+	const arch = deps.arch ?? process.arch;
+	const pluginRoot = deps.pluginRoot ?? nodePath.resolve(import.meta.dirname, '..');
+	const resolvePaths = deps.resolvePaths ?? defaultResolvePaths;
+	const importTimeout = deps.importTimeout ?? DEFAULT_IMPORT_TIMEOUT_MS;
+
+	const platformKey = `${platform}-${arch}`;
+	log(`ndc.preload platform=${platformKey}`);
+
+	try {
+		// 平台检查
+		if (!SUPPORTED_PLATFORMS.has(platformKey)) {
+			log(`ndc.skip reason=unsupported-platform platform=${platformKey}`);
+			return weriftFallback(dynamicImport, log, importTimeout);
+		}
+		const { src, dest, destDir } = resolvePaths(platformKey, pluginRoot);
+
+		// 检查目标 binary 是否已存在（正常 pnpm install 或已执行过 bootstrap）
+		let needCopy = false;
+		try {
+			await fs.access(dest);
+			log('ndc.binary-exists');
+		} catch {
+			needCopy = true;
+		}
+
+		if (needCopy) {
+			// 检查 vendor 源 binary
+			try {
+				await fs.access(src);
+			} catch {
+				log('ndc.fallback reason=binary-missing');
+				return weriftFallback(dynamicImport, log, importTimeout);
+			}
+
+			// 部署 binary
+			try {
+				await fs.mkdir(destDir, { recursive: true });
+				await fs.copyFile(src, dest);
+				log('ndc.binary-deployed');
+			} catch (err) {
+				log(`ndc.fallback reason=copy-failed error=${err.message}`);
+				return weriftFallback(dynamicImport, log, importTimeout);
+			}
+		}
+
+		// 加载模块（带超时保护，防止 native binding dlopen 卡住）
+		let polyfill, ndc;
+		try {
+			polyfill = await withTimeout(
+				dynamicImport('node-datachannel/polyfill'),
+				importTimeout,
+				'import(node-datachannel/polyfill)',
+			);
+			ndc = await withTimeout(
+				dynamicImport('node-datachannel'),
+				importTimeout,
+				'import(node-datachannel)',
+			);
+		} catch (err) {
+			log(`ndc.fallback reason=import-failed error=${err.message}`);
+			return weriftFallback(dynamicImport, log, importTimeout);
+		}
+
+		const { RTCPeerConnection } = polyfill;
+		const cleanup = ndc.cleanup ?? ndc.default?.cleanup ?? null;
+
+		// 验证 RTCPeerConnection 可用（不创建实例，避免 native thread 阻止进程退出）
+		if (typeof RTCPeerConnection !== 'function') {
+			log('ndc.fallback reason=smoke-failed error=RTCPeerConnection is not a function');
+			return weriftFallback(dynamicImport, log, importTimeout);
+		}
+
+		// 重要：调用方在不再需要 node-datachannel 时（如 bridge stop），必须调用 cleanup()。
+		// node-datachannel 内部使用 ThreadSafeCallback 维持 native threads，不调用 cleanup()
+		// 会阻止 Node 进程正常退出（上游 issue #366）。
+		// 当前由 RealtimeBridge.stop() 负责调用。若 gateway 被 SIGKILL 强杀则无法执行，
+		// 但 OS 会回收所有资源。若 OpenClaw 提供了优雅终止钩子，应在钩子中也调用 cleanup。
+		log(`ndc.loaded platform=${platformKey}`);
+		return { PeerConnection: RTCPeerConnection, cleanup, impl: 'ndc' };
+	} catch (err) {
+		// resolvePaths 或其他未预期异常的兜底
+		log(`ndc.fallback reason=unexpected error=${err.message}`);
+		return weriftFallback(dynamicImport, log, importTimeout);
+	}
+}
+
+/**
+ * 回退到 werift。加载也带超时保护。
+ * werift 也失败时返回 PeerConnection: null（WebRTC 不可用但不影响 gateway）。
+ * @param {Function} dynamicImport
+ * @param {Function} log
+ * @param {number} importTimeout
+ */
+async function weriftFallback(dynamicImport, log, importTimeout) {
+	try {
+		const { RTCPeerConnection } = await withTimeout(
+			dynamicImport('werift'),
+			importTimeout,
+			'import(werift)',
+		);
+		log('webrtc.fallback-to-werift');
+		return { PeerConnection: RTCPeerConnection, cleanup: null, impl: 'werift' };
+	} catch (err) {
+		log(`webrtc.all-unavailable error=${err.message}`);
+		return { PeerConnection: null, cleanup: null, impl: 'none' };
+	}
+}

package/src/realtime-bridge.js

@@ -10,6 +10,7 @@ import {
 	buildDeviceAuthPayloadV3,
 } from './device-identity.js';
 import { getRuntime } from './runtime.js';
+import { setSender as setRemoteLogSender, remoteLog } from './remote-log.js';
 
 const DEFAULT_GATEWAY_WS_URL = `ws://127.0.0.1:${process.env.OPENCLAW_GATEWAY_PORT || '18789'}`;
 const RECONNECT_MS = 10_000;
@@ -52,7 +53,8 @@ function defaultResolveGatewayAuthToken() {
 		const token = cfg?.gateway?.auth?.token;
 		return typeof token === 'string' && token.trim() ? token.trim() : '';
 	}
-	catch {
+	catch (err) {
+		console.warn?.(`[coclaw] resolve gateway auth token failed: ${String(err?.message ?? err)}`);
 		return '';
 	}
 }
@@ -72,6 +74,7 @@ export class RealtimeBridge {
 	 * @param {Function} [deps.getBindingsPath] - 获取绑定文件路径
 	 * @param {Function} [deps.resolveGatewayAuthToken] - 获取 gateway 认证 token
 	 * @param {Function} [deps.loadDeviceIdentity] - 加载设备身份
+	 * @param {number} [deps.gatewayReadyTimeoutMs] - __waitGatewayReady 默认超时（测试可注入短值）
 	 */
 	constructor(deps = {}) {
 		this.__readConfig = deps.readConfig ?? readConfig;
@@ -79,7 +82,9 @@ export class RealtimeBridge {
 		this.__getBindingsPath = deps.getBindingsPath ?? getBindingsPath;
 		this.__resolveGatewayAuthToken = deps.resolveGatewayAuthToken ?? defaultResolveGatewayAuthToken;
 		this.__loadDeviceIdentity = deps.loadDeviceIdentity ?? loadOrCreateDeviceIdentity;
+		this.__preloadNdc = deps.preloadNdc ?? null;
 		this.__WebSocket = deps.WebSocket ?? null;
+		this.__gatewayReadyTimeoutMs = deps.gatewayReadyTimeoutMs ?? 1500;
 
 		this.serverWs = null;
 		this.gatewayWs = null;
@@ -100,6 +105,8 @@ export class RealtimeBridge {
 		this.webrtcPeer = null;
 		this.__webrtcPeerReady = null;
 		this.__fileHandler = null;
+		this.__ndcPreloadResult = null;
+		this.__ndcCleanup = null;
 	}
 
 	__resolveWebSocket() {
@@ -149,6 +156,7 @@ export class RealtimeBridge {
 			this.serverHbTimer.unref?.();
 			return;
 		}
+		remoteLog(`ws.hb-timeout peer=server misses=${this.__serverHbMissCount}`);
 		this.logger.warn?.(
 			`[coclaw] server ws heartbeat timeout after ${this.__serverHbMissCount} consecutive misses (~${this.__serverHbMissCount * SERVER_HB_TIMEOUT_MS / 1000}s), closing`
 		);
@@ -198,22 +206,26 @@ export class RealtimeBridge {
 	}
 
 	/** 懒加载 WebRtcPeer（promise 锁防并发重复创建） */
+	/* c8 ignore start -- 仅通过 WebRTC 路径触发，集成测试覆盖 */
 	async __initWebrtcPeer() {
+		const PeerConnection = this.__ndcPreloadResult?.PeerConnection;
+		if (!PeerConnection) {
+			remoteLog('rtc.unavailable reason=no-webrtc-impl');
+			throw new Error('No WebRTC implementation available');
+		}
+
 		const { WebRtcPeer } = await import('./webrtc-peer.js');
 		const { createFileHandler } = await import('./file-manager/handler.js');
-		/* c8 ignore start -- 仅通过 WebRTC 路径触发，集成测试覆盖 */
 		this.__fileHandler = createFileHandler({
 			resolveWorkspace: (agentId) => this.__resolveWorkspace(agentId),
 			logger: this.logger,
 		});
 		this.__fileHandler.scheduleTmpCleanup(() => this.__listAgentWorkspaces());
-		/* c8 ignore stop */
 		this.webrtcPeer = new WebRtcPeer({
 			onSend: (msg) => this.__forwardToServer(msg),
 			onRequest: (dcPayload) => {
 				void this.__handleGatewayRequestFromServer(dcPayload);
 			},
-			/* c8 ignore start -- 仅通过 WebRTC 路径触发，集成测试覆盖 */
 			onFileRpc: (payload, sendFn) => {
 				this.__fileHandler.handleRpcRequest(payload, sendFn)
 					.catch((err) => this.logger.warn?.(`[coclaw/file] rpc error: ${err.message}`));
@@ -221,10 +233,11 @@ export class RealtimeBridge {
 			onFileChannel: (dc) => {
 				this.__fileHandler.handleFileChannel(dc);
 			},
-			/* c8 ignore stop */
+			PeerConnection,
 			logger: this.logger,
 		});
 	}
+	/* c8 ignore stop */
 
 	/* c8 ignore next 7 -- 防御性检查，serverWs 通常在调用时可用 */
 	__forwardToServer(payload) {
@@ -450,8 +463,8 @@ export class RealtimeBridge {
 			try {
 				const ws = await this.__resolveWorkspace(id);
 				workspaces.push(ws);
-			} catch {
-				// 个别 agent 解析失败不阻断
+			} catch (err) {
+				this.__logDebug(`workspace resolve failed for agent=${id}: ${err?.message}`);
 			}
 		}
 		return workspaces;
@@ -523,7 +536,8 @@ export class RealtimeBridge {
 				params,
 			}));
 		}
-		catch {
+		catch (err) {
+			this.logger.warn?.(`[coclaw] gateway connect request failed: ${String(err?.message ?? err)}`);
 			this.gatewayConnectReqId = null;
 		}
 	}
@@ -562,6 +576,7 @@ export class RealtimeBridge {
 			if (payload.type === 'res' && this.gatewayConnectReqId && payload.id === this.gatewayConnectReqId) {
 				if (payload.ok === true) {
 					this.gatewayReady = true;
+					remoteLog('ws.connected peer=gateway');
 					this.__logDebug(`gateway connect ok <- id=${payload.id}`);
 					this.gatewayConnectReqId = null;
 					this.__ensureSessionsPromise = this.__ensureAllAgentSessions();
@@ -569,6 +584,7 @@ export class RealtimeBridge {
 				else {
 					this.gatewayReady = false;
 					this.gatewayConnectReqId = null;
+					remoteLog(`ws.connect-failed peer=gateway msg=${payload?.error?.message ?? 'unknown'}`);
 					this.logger.warn?.(`[coclaw] gateway connect failed: ${payload?.error?.message ?? 'unknown'}`);
 					try { ws.close(1008, 'gateway_connect_failed'); }
 					/* c8 ignore next */
@@ -592,15 +608,18 @@ export class RealtimeBridge {
 				return;
 			}
 			if (payload.type === 'res' || payload.type === 'event') {
+				// TODO: UI 已通过 DataChannel 接收业务消息，待旧版 UI 全部更新后移除此转发
 				this.__forwardToServer(payload);
 				this.webrtcPeer?.broadcast(payload);
 			}
 		});
 
 		ws.addEventListener('open', () => {
-			// wait for connect.challenge
+			this.__logDebug('gateway ws open, waiting for connect.challenge');
 		});
-		ws.addEventListener('close', () => {
+		ws.addEventListener('close', (ev) => {
+			remoteLog(`ws.disconnected peer=gateway code=${ev?.code ?? '?'}`);
+			this.logger.info?.(`[coclaw] gateway ws closed (code=${ev?.code ?? '?'} reason=${ev?.reason ?? 'n/a'})`);
 			this.gatewayWs = null;
 			this.gatewayReady = false;
 			this.gatewayConnectReqId = null;
@@ -610,10 +629,14 @@ export class RealtimeBridge {
 			}
 			this.gatewayPendingRequests.clear();
 		});
-		ws.addEventListener('error', () => {});
+		ws.addEventListener('error', (err) => {
+			/* c8 ignore next -- ?./?? fallback */
+			remoteLog(`ws.error peer=gateway msg=${String(err?.message ?? err)}`);
+			this.logger.warn?.(`[coclaw] gateway ws error: ${String(err?.message ?? err)}`);
+		});
 	}
 
-	async __waitGatewayReady(timeoutMs = 1500) {
+	async __waitGatewayReady(timeoutMs = this.__gatewayReadyTimeoutMs) {
 		this.__ensureGatewayConnection();
 		if (this.gatewayWs && this.gatewayWs.readyState === 1 && this.gatewayReady) {
 			return true;
@@ -711,6 +734,7 @@ export class RealtimeBridge {
 		if (!this.started || this.reconnectTimer) {
 			return;
 		}
+		remoteLog(`ws.reconnecting peer=server delay=${RECONNECT_MS}ms`);
 		this.reconnectTimer = setTimeout(() => {
 			this.reconnectTimer = null;
 			this.__connectIfNeeded().catch((err) => {
@@ -758,6 +782,7 @@ export class RealtimeBridge {
 				return;
 			}
 			this.logger.warn?.(`[coclaw] realtime bridge connect timeout, will retry: ${maskedTarget}`);
+			remoteLog('ws.connect-timeout peer=server');
 			this.serverWs = null;
 			this.__closeGatewayWs();
 			this.__scheduleReconnect();
@@ -770,6 +795,10 @@ export class RealtimeBridge {
 		sock.addEventListener('open', () => {
 			this.__clearConnectTimer();
 			this.logger.info?.(`[coclaw] realtime bridge connected: ${maskedTarget}`);
+			remoteLog('ws.connected peer=server');
+			setRemoteLogSender((msg) => {
+				if (sock.readyState === 1) sock.send(JSON.stringify(msg));
+			});
 			this.__startServerHeartbeat(sock);
 			this.__ensureGatewayConnection();
 		});
@@ -779,6 +808,7 @@ export class RealtimeBridge {
 			try {
 				const payload = JSON.parse(String(event.data ?? '{}'));
 				if (payload?.type === 'bot.unbound') {
+					remoteLog('ws.bot-unbound');
 					await this.__clearTokenLocal(payload.botId);
 					try { sock.close(4001, 'bot_unbound'); }
 					/* c8 ignore next */
@@ -797,6 +827,7 @@ export class RealtimeBridge {
 						await this.webrtcPeer.handleSignaling(payload);
 					} catch (err) {
 						this.logger.warn?.(`[coclaw/rtc] signaling error (or werift not found): ${err?.message}`);
+						remoteLog(`rtc.signaling-error msg=${err?.message}`);
 					}
 					return;
 				}
@@ -820,6 +851,7 @@ export class RealtimeBridge {
 			if (this.serverWs !== null && this.serverWs !== sock) {
 				return;
 			}
+			setRemoteLogSender(null);
 			const wasIntentional = this.intentionallyClosed;
 			this.serverWs = null;
 			this.intentionallyClosed = false;
@@ -837,6 +869,8 @@ export class RealtimeBridge {
 			}
 
 			if (event?.code === 4001 || event?.code === 4003) {
+				remoteLog(`ws.auth-close peer=server code=${event.code}`);
+				this.logger.warn?.(`[coclaw] server ws auth-close (code=${event.code}), clearing local token`);
 				try {
 					await this.__clearTokenLocal();
 				}
@@ -848,6 +882,7 @@ export class RealtimeBridge {
 			}
 
 			if (!wasIntentional) {
+				remoteLog(`ws.disconnected peer=server code=${event?.code ?? 'unknown'} reason=${event?.reason ?? 'n/a'}`);
 				this.logger.warn?.(`[coclaw] realtime bridge closed (${event?.code ?? 'unknown'}: ${event?.reason ?? 'n/a'}), will retry in ${RECONNECT_MS}ms`);
 				this.__scheduleReconnect();
 			}
@@ -859,6 +894,8 @@ export class RealtimeBridge {
 			}
 			this.__clearServerHeartbeat();
 			this.__clearConnectTimer();
+			setRemoteLogSender(null);
+			remoteLog(`ws.error peer=server msg=${String(err?.message ?? err)}`);
 			this.logger.warn?.(`[coclaw] realtime bridge error, will retry in ${RECONNECT_MS}ms: ${String(err?.message ?? err)}`);
 			this.serverWs = null;
 			this.__closeGatewayWs();
@@ -873,6 +910,27 @@ export class RealtimeBridge {
 		this.logger = logger ?? console;
 		this.pluginConfig = pluginConfig ?? {};
 		this.started = true;
+		// 先完成 WebRTC 实现加载，再建立连接，避免 UI 发来 offer 时 RTC 包未就绪
+		const preloadFn = this.__preloadNdc
+			?? (await import('./ndc-preloader.js')).preloadNdc;
+		const preloadResult = await preloadFn()
+			.catch((err) => {
+				// preloadNdc 设计上永不 throw，此 catch 为纯防御性兜底
+				this.logger.warn?.(`[coclaw] ndc preload unexpected failure: ${err?.message}`);
+				return { PeerConnection: null, cleanup: null, impl: 'none' };
+			});
+		// 竞态保护：若 preload 期间 stop() 已执行，不再赋值，立即释放 cleanup
+		if (!this.started) {
+			if (preloadResult.cleanup) {
+				try { preloadResult.cleanup(); } catch {}
+			}
+			return;
+		}
+		this.__ndcPreloadResult = preloadResult;
+		this.__ndcCleanup = preloadResult.cleanup;
+		const implLabel = preloadResult.impl === 'ndc' ? 'node-datachannel(ndc)' : preloadResult.impl;
+		this.logger.info?.(`[coclaw] WebRTC impl: ${implLabel}`);
+		remoteLog(`bridge.webrtc-impl impl=${implLabel}`);
 		await this.__connectIfNeeded();
 	}
 
@@ -886,6 +944,7 @@ export class RealtimeBridge {
 
 	async stop() {
 		this.started = false;
+		setRemoteLogSender(null);
 		this.__clearServerHeartbeat();
 		this.__clearConnectTimer();
 		if (this.reconnectTimer) {
@@ -898,6 +957,17 @@ export class RealtimeBridge {
 			this.webrtcPeer = null;
 			this.__webrtcPeerReady = null;
 		}
+		// ndc cleanup：node-datachannel 的 native threads 必须通过 cleanup() 释放，
+		// 否则会阻止进程退出（issue #366）。
+		// start() 已 await preload 完成并缓存 cleanup 引用，此处直接使用。
+		// 注意：若进程被 SIGKILL 强杀，此处不会执行，OS 会回收资源。
+		// TODO: 若 OpenClaw 未来提供 graceful shutdown 钩子，应在钩子中也调用 cleanup。
+		if (this.__ndcCleanup) {
+			try { this.__ndcCleanup(); }
+			catch (err) { remoteLog(`ndc.cleanup-failed error=${err?.message}`); }
+		}
+		this.__ndcCleanup = null;
+		this.__ndcPreloadResult = null;
 		if (this.__fileHandler) {
 			this.__fileHandler.cancelCleanup();
 			this.__fileHandler = null;

package/src/remote-log.js

@@ -0,0 +1,70 @@
+/**
+ * 远程日志推送模块
+ *
+ * 将诊断日志缓冲并通过 WS 通道推送到 CoClaw server。
+ * 单例模式——各模块直接 import { remoteLog } 使用。
+ */
+
+const MAX_BUFFER = 1000;
+const BATCH_SIZE = 20;
+
+/** @type {{ ts: number, text: string }[]} */
+const buffer = [];
+
+/** @type {((msg: object) => void) | null} */
+let sender = null;
+
+let flushing = false;
+
+/**
+ * 注入/移除发送函数。由 RealtimeBridge 在 WS 连接/断开时调用。
+ * @param {((msg: object) => void) | null} fn
+ */
+export function setSender(fn) {
+	sender = fn;
+	if (fn && buffer.length > 0) {
+		flush().catch(() => {});
+	}
+}
+
+/**
+ * 推送一条远程诊断日志。
+ * @param {string} text - 可读文本描述（不含时间戳，内部自动附加）
+ */
+export function remoteLog(text) {
+	if (buffer.length >= MAX_BUFFER) {
+		buffer.shift();
+	}
+	buffer.push({ ts: Date.now(), text });
+	if (sender && !flushing) {
+		flush().catch(() => {});
+	}
+}
+
+async function flush() {
+	if (flushing) return;
+	flushing = true;
+	try {
+		while (buffer.length > 0 && sender) {
+			const batch = buffer.slice(0, BATCH_SIZE);
+			try {
+				sender({ type: 'log', logs: batch });
+				buffer.splice(0, batch.length);
+			} catch {
+				break;
+			}
+			await new Promise(r => setTimeout(r, 0));
+		}
+	} finally {
+		flushing = false;
+	}
+}
+
+// 测试用：重置内部状态
+export function __reset() {
+	buffer.length = 0;
+	sender = null;
+	flushing = false;
+}
+
+export { buffer as __buffer, BATCH_SIZE as __BATCH_SIZE, MAX_BUFFER as __MAX_BUFFER };

package/src/webrtc-peer.js

@@ -1,5 +1,5 @@
-import { RTCPeerConnection as WeriftRTCPeerConnection } from 'werift';
 import { chunkAndSend, createReassembler } from './utils/dc-chunking.js';
+import { remoteLog } from './remote-log.js';
 
 /**
  * 管理多个 WebRTC PeerConnection（以 connId 为粒度）。
@@ -13,15 +13,18 @@ export class WebRtcPeer {
 	 * @param {function} [opts.onFileRpc] - rpc DC 上 coclaw.files.* 请求的回调 (payload, sendFn, connId) => void
 	 * @param {function} [opts.onFileChannel] - file:<transferId> DataChannel 的回调 (dc, connId) => void
 	 * @param {object} [opts.logger] - pino 风格 logger
-	 * @param {function} [opts.PeerConnection] - 可替换的构造函数（测试用）
+	 * @param {function} opts.PeerConnection - RTCPeerConnection 构造函数（由 ndc-preloader 提供）
 	 */
 	constructor({ onSend, onRequest, onFileRpc, onFileChannel, logger, PeerConnection }) {
+		if (!PeerConnection) {
+			throw new Error('PeerConnection constructor is required');
+		}
 		this.__onSend = onSend;
 		this.__onRequest = onRequest;
 		this.__onFileRpc = onFileRpc;
 		this.__onFileChannel = onFileChannel;
 		this.logger = logger ?? console;
-		this.__PeerConnection = PeerConnection ?? WeriftRTCPeerConnection;
+		this.__PeerConnection = PeerConnection;
 		/** @type {Map<string, { pc: object, rpcChannel: object|null, remoteMaxMessageSize: number, nextMsgId: number }>} */
 		this.__sessions = new Map();
 	}
@@ -50,6 +53,7 @@ export class WebRtcPeer {
 		session.pc.onconnectionstatechange = null;
 		session.pc.onicecandidate = null;
 		await session.pc.close();
+		remoteLog(`rtc.closed conn=${connId}`);
 		this.logger.info?.(`[coclaw/rtc] [${connId}] closed`);
 	}
 
@@ -82,6 +86,7 @@ export class WebRtcPeer {
 		if (isIceRestart) {
 			const existing = this.__sessions.get(connId);
 			if (existing) {
+				remoteLog(`rtc.ice-restart conn=${connId}`);
 				this.logger.info?.(`[coclaw/rtc] ICE restart offer from ${connId}, renegotiating`);
 				try {
 					await existing.pc.setRemoteDescription({ type: 'offer', sdp: msg.payload.sdp });
@@ -96,6 +101,7 @@ export class WebRtcPeer {
 					return;
 				} catch (err) {
 					// ICE restart 协商失败 → 回退到 full rebuild
+					remoteLog(`rtc.ice-restart-failed conn=${connId}`);
 					this.logger.warn?.(`[coclaw/rtc] ICE restart failed for ${connId}, falling back to rebuild: ${err?.message}`);
 					await this.closeByConnId(connId);
 				}
@@ -103,6 +109,7 @@ export class WebRtcPeer {
 			// 无现有 session 或 ICE restart 失败 → 按 full rebuild 继续
 		}
 
+		remoteLog(`rtc.offer conn=${connId}`);
 		this.logger.info?.(`[coclaw/rtc] offer received from ${connId}, creating answer`);
 
 		// 同一 connId 重复 offer → 先关闭旧连接
@@ -125,6 +132,11 @@ export class WebRtcPeer {
 			}
 		}
 
+		// 记录 ICE 服务器配置（脱敏，不含 credential）
+		const stunUrl = iceServers.find((s) => s.urls?.startsWith('stun:'))?.urls ?? 'none';
+		const turnUrl = iceServers.find((s) => s.urls?.startsWith('turn:'))?.urls ?? 'none';
+		remoteLog(`rtc.ice-config conn=${connId} stun=${stunUrl} turn=${turnUrl}`);
+
 		const pc = new this.__PeerConnection({ iceServers });
 
 		// 从 SDP 解析对端 maxMessageSize（用于分片决策）
@@ -134,9 +146,19 @@ export class WebRtcPeer {
 		const session = { pc, rpcChannel: null, remoteMaxMessageSize, nextMsgId: 1 };
 		this.__sessions.set(connId, session);
 
-		// ICE candidate → 发给 UI
+		// ICE candidate → 发给 UI，并统计各类型 candidate 数量
+		const candidateCounts = { host: 0, srflx: 0, relay: 0 };
 		pc.onicecandidate = ({ candidate }) => {
-			if (!candidate) return;
+			if (!candidate) {
+				// gathering 完成，输出汇总
+				remoteLog(`rtc.ice-gathered conn=${connId} host=${candidateCounts.host} srflx=${candidateCounts.srflx} relay=${candidateCounts.relay}`);
+				return;
+			}
+			// 从 candidate 字符串中提取类型（typ host / typ srflx / typ relay）
+			const typMatch = candidate.candidate?.match(/typ (\w+)/);
+			if (typMatch && candidateCounts[typMatch[1]] !== undefined) {
+				candidateCounts[typMatch[1]]++;
+			}
 			this.__onSend({
 				type: 'rtc:ice',
 				toConnId: connId,
@@ -151,6 +173,7 @@ export class WebRtcPeer {
 		// 连接状态变更（校验 pc 归属，防止旧 PC 异步回调删除新 session）
 		pc.onconnectionstatechange = () => {
 			const state = pc.connectionState;
+			remoteLog(`rtc.state conn=${connId} ${state}`);
 			this.logger.info?.(`[coclaw/rtc] [${connId}] connectionState: ${state}`);
 			if (state === 'connected') {
 				const nominated = pc.iceTransports?.[0]?.connection?.nominated;
@@ -159,6 +182,7 @@ export class WebRtcPeer {
 					const remoteC = nominated.remoteCandidate;
 					const localInfo = `${localC?.type ?? '?'} ${localC?.host ?? '?'}:${localC?.port ?? '?'}`;
 					const remoteInfo = `${remoteC?.type ?? '?'} ${remoteC?.host ?? '?'}:${remoteC?.port ?? '?'}`;
+					remoteLog(`rtc.ice-nominated conn=${connId} local=${localInfo} remote=${remoteInfo}`);
 					this.logger.info?.(`[coclaw/rtc] [${connId}] ICE nominated: local=${localInfo} remote=${remoteInfo}`);
 				}
 			} else if (state === 'failed' || state === 'closed') {
@@ -171,6 +195,7 @@ export class WebRtcPeer {
 
 		// 监听 UI 创建的 DataChannel
 		pc.ondatachannel = ({ channel }) => {
+			remoteLog(`dc.received conn=${connId} label=${channel.label}`);
 			this.logger.info?.(`[coclaw/rtc] [${connId}] DataChannel "${channel.label}" received`);
 			if (channel.label === 'rpc') {
 				session.rpcChannel = channel;
@@ -191,6 +216,7 @@ export class WebRtcPeer {
 				toConnId: connId,
 				payload: { sdp: answer.sdp },
 			});
+			remoteLog(`rtc.answer conn=${connId}`);
 			this.logger.info?.(`[coclaw/rtc] answer sent to ${connId}`);
 		} catch (err) {
 			// SDP 协商失败 → 清理已入 Map 的 session，避免泄漏
@@ -217,6 +243,12 @@ export class WebRtcPeer {
 	__setupDataChannel(connId, dc) {
 		const reassembler = createReassembler((jsonStr) => {
 			const payload = JSON.parse(jsonStr);
+			// DC 探测：立即回复，不走 gateway
+			if (payload.type === 'probe') {
+				try { dc.send(JSON.stringify({ type: 'probe-ack' })); }
+				catch { /* DC 已关闭，忽略 */ }
+				return;
+			}
 			if (payload.type === 'req') {
 				// coclaw.files.* 方法本地处理，不转发 gateway
 				if (payload.method?.startsWith('coclaw.files.') && this.__onFileRpc) {
@@ -243,14 +275,21 @@ export class WebRtcPeer {
 		}, { logger: this.logger });
 
 		dc.onopen = () => {
+			remoteLog(`dc.open conn=${connId} label=${dc.label}`);
 			this.logger.info?.(`[coclaw/rtc] [${connId}] DataChannel "${dc.label}" opened`);
 		};
 		dc.onclose = () => {
+			remoteLog(`dc.closed conn=${connId} label=${dc.label}`);
 			this.logger.info?.(`[coclaw/rtc] [${connId}] DataChannel "${dc.label}" closed`);
 			reassembler.reset();
 			const session = this.__sessions.get(connId);
 			if (session && dc.label === 'rpc') session.rpcChannel = null;
 		};
+		dc.onerror = (err) => {
+			remoteLog(`dc.error conn=${connId} label=${dc.label}`);
+			/* c8 ignore next -- ?./?? fallback */
+			this.logger.warn?.(`[coclaw/rtc] [${connId}] DataChannel "${dc.label}" error: ${String(err?.message ?? err)}`);
+		};
 		dc.onmessage = (event) => {
 			try {
 				reassembler.feed(event.data);