@coclaw/openclaw-coclaw 0.21.0 → 0.21.3

package/index.js

@@ -5,6 +5,7 @@ import { notBound, bindOk, unbindOk, claimCodeCreated } from './src/common/messa
 import { coclawChannelPlugin } from './src/channel-plugin.js';
 import { ensureAgentSession, gatewayAgentRpc, restartRealtimeBridge, stopRealtimeBridge, waitForSessionsReady, broadcastPluginEvent } from './src/realtime-bridge.js';
 import { getHostName, readSettings, writeName, MAX_NAME_LENGTH } from './src/settings.js';
+import { readConfig } from './src/config.js';
 import { setRuntime } from './src/runtime.js';
 import { createSessionManager } from './src/session-manager/manager.js';
 import { TopicManager } from './src/topic-manager/manager.js';
@@ -157,6 +158,13 @@ const plugin = {
 		setRuntime(api.runtime);
 		const logger = api?.logger ?? console;
 		installAbortRegistryDiag(logger);
+
+		// 未 bind 时打条提示，便于 hub 装机用户看到下一步动作
+		readConfig().then((cfg) => {
+			if (!cfg?.token) {
+				logger.info?.('[coclaw] not bound — run `openclaw coclaw enroll` to connect to CoClaw');
+			}
+		}).catch(() => {});
 		const manager = createSessionManager({ logger });
 		const topicManager = new TopicManager({ logger });
 		const chatHistoryManager = new ChatHistoryManager({ logger });

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "openclaw-coclaw",
   "name": "CoClaw",
-  "description": "OpenClaw CoClaw channel plugin for remote chat",
+  "description": "OpenClaw CoClaw channel plugin for remote chat. Run `openclaw coclaw enroll` after install to connect to CoClaw.",
   "activation": {
     "onStartup": true
   },
@@ -11,9 +11,6 @@
     "properties": {
       "serverUrl": {
         "type": "string"
-      },
-      "gatewayWsUrl": {
-        "type": "string"
       }
     }
   }

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@coclaw/openclaw-coclaw",
-  "version": "0.21.0",
+  "version": "0.21.3",
   "type": "module",
   "license": "Apache-2.0",
-  "description": "OpenClaw CoClaw channel plugin for remote chat",
+  "description": "OpenClaw CoClaw channel plugin for remote chat. Run `openclaw coclaw enroll` after install to connect to CoClaw.",
   "repository": {
     "type": "git",
     "url": "https://github.com/coclaw/coclaw.git",

package/src/realtime-bridge.js

@@ -23,10 +23,19 @@ const RECONNECT_MS = 10_000;
 const CONNECT_TIMEOUT_MS = 10_000;
 const SERVER_HB_PING_MS = 25_000;
 const SERVER_HB_TIMEOUT_MS = 45_000;
-const SERVER_HB_MAX_MISS = 4; // 连续 4 次无响应才断连（~3 分钟）
+const SERVER_HB_MAX_MISS = 3; // 连续 3 次无响应才断连（~135s）。上游主线程 spike 实测最坏 ~89.5s（issue #75069），余量 ~1.5x
 // gateway 握手失败的指数退避表：每个元素是"上一次失败"之后、"下一次尝试"之前的等待时间。
-// 最多 5 次重试（加上首次尝试共 6 次），全部失败后进入 gave-up 终态，不再自动尝试。
-const GATEWAY_RETRY_DELAYS_MS = [5_000, 10_000, 20_000, 20_000, 20_000];
+// 最多 N 次重试（N=length；加上首次尝试共 N+1 次），全部失败后进入 gave-up 终态，
+// 终态后必须 stop+start 才能恢复（无运行期自动复活）——所以预算要够覆盖慢启动场景。
+// 表前置 4 档（1s + 3×1.5s）专门压低"server 启动期 sidecars 还没就绪"窗口（推荐
+// retryAfterMs=500）；尾段 9 × 20s 把总预算拉到 ~200s（>3 分钟），覆盖 profile 初始化、
+// 笔记本刚开机磁盘忙、pion 子进程首次 spawn 等慢启动场景，避免误判"放弃"。
+// export 是为了让测试 helper 通过同一份常量识别 retry timer，避免硬编码副本与生产代码漂移。
+export const GATEWAY_RETRY_DELAYS_MS = [
+	1_000, 1_500, 1_500, 1_500,
+	5_000, 10_000,
+	20_000, 20_000, 20_000, 20_000, 20_000, 20_000, 20_000, 20_000, 20_000,
+];
 // v3 握手失败时，只有错误消息匹配此正则才回退到不带 device 的 legacy 握手。
 // 严格限定在"签名/设备/scope/协议"相关错误，避免对网络/内部错误做无意义的降级尝试。
 const GATEWAY_HANDSHAKE_FALLBACK_PATTERN = /signature|device|scope|protocol/i;
@@ -90,20 +99,26 @@ function maskUrlToken(url) {
 }
 
 // 仅在未注入 resolveGatewayAuthToken 时使用，依赖 runtime / 环境变量
+// 优先级：config.gateway.auth.token > env OPENCLAW_GATEWAY_TOKEN
+// 与上游 server 的 auth-surface-resolution 同方向：config 主、env 兜底。
+// env 路径保留是为 ensureGatewayStartupAuth 的 env-only 边角（token 由 env 提供时
+// 上游不会写回 cfg），cfg 读不到时仍能拿到正确 token。
 export function defaultResolveGatewayAuthToken() {
-	const envToken = process.env.OPENCLAW_GATEWAY_TOKEN?.trim();
-	if (envToken) {
-		return envToken;
-	}
 	try {
 		const cfg = getClawConfig();
 		const token = cfg?.gateway?.auth?.token;
-		return typeof token === 'string' && token.trim() ? token.trim() : '';
+		if (typeof token === 'string' && token.trim()) {
+			return token.trim();
+		}
 	}
 	catch (err) {
 		console.warn?.(`[coclaw] resolve gateway auth token failed: ${String(err?.message ?? err)}`);
-		return '';
 	}
+	const envToken = process.env.OPENCLAW_GATEWAY_TOKEN?.trim();
+	if (envToken) {
+		return envToken;
+	}
+	return '';
 }
 
 /**
@@ -247,9 +262,7 @@ export class RealtimeBridge {
 	}
 
 	__resolveGatewayWsUrl() {
-		return this.pluginConfig?.gatewayWsUrl
-			?? process.env.COCLAW_GATEWAY_WS_URL
-			?? DEFAULT_GATEWAY_WS_URL;
+		return process.env.COCLAW_GATEWAY_WS_URL ?? DEFAULT_GATEWAY_WS_URL;
 	}
 
 	async __clearTokenLocal(unboundClawId) {
@@ -265,16 +278,11 @@ export class RealtimeBridge {
 	}
 
 	__closeGatewayWs() {
-		// 当 server WS 失效主动关闭 gateway 时，取消任何 pending 重试定时器、把连续失败计数归零：
-		// 新 server 会话应从新预算开始重试 gateway，避免旧会话的零散失败累计吞掉未来的重试机会。
-		// 不清 __gatewayGaveUp / __gatewayLegacyMode —— 那是跨会话的终态/学习，只由 stop() 复位。
-		if (this.__gatewayRetryTimer) {
-			clearTimeout(this.__gatewayRetryTimer);
-			this.__gatewayRetryTimer = null;
-		}
-		this.__gatewayAttempts = 0;
-		// 主动关闭时立即清 lag probe，不依赖 close 事件回调时序，避免 close 事件延迟期间 probe 误报
-		this.__clearAllLagProbes();
+		// 仅由显式销毁路径（stop / refresh）调用：职责单一——关闭当前 gateway WS 实例 +
+		// 结算未完成的 gateway RPC。retry timer / attempts 由 stop() 复位；lag probes 由 stop()
+		// 显式 __clearAllLagProbes 兜底（ws close 事件异步触发，期间 gatewayWs 已被这里置 null，
+		// 走 stale guard 早返不再清理）；P2P 路由表（__dcPendingRequests / __runEventRoutes）
+		// 已不再随内线翻转清理，stop() 会显式 clear / destroy。
 		if (!this.gatewayWs) {
 			return;
 		}
@@ -292,10 +300,6 @@ export class RealtimeBridge {
 			settle({ ok: false, error: 'gateway_closed' });
 		}
 		this.gatewayPendingRequests.clear();
-		// 清空 UI 转发 RPC 路由表：gateway 已断，不会再有响应回来；不主动通知 UI，由 UI 30/60s 超时兜底
-		this.__dcPendingRequests.clear();
-		// 同步清空 runId 路由表（gateway 已断，不会再有 event:agent 推过来）
-		this.__runEventRoutes?.clear();
 	}
 
 	/** 懒加载 WebRtcPeer（promise 锁防并发重复创建） */
@@ -338,16 +342,21 @@ export class RealtimeBridge {
 	}
 	/* c8 ignore stop */
 
-	/* c8 ignore next 7 -- 防御性检查，serverWs 通常在调用时可用 */
 	__forwardToServer(payload) {
 		if (!this.serverWs || this.serverWs.readyState !== 1) {
+			// WS 断窗口期 onSend 调用：webrtcPeer 异步回调（trickle ICE candidate、SDP 应答等）
+			// 本身没有 queue/rollback 机制，丢失对 plugin 端 PC 状态机不致命——UI 端 sig.state
+			// 恢复后会主动触发新一轮 ICE restart，重发完整 candidate set 与 SDP。仅记本地 log
+			// 便于事后排查；TODO 跟进完整方案（queue / rollback connId）。
+			this.logger.warn?.(`[coclaw] forward dropped: ws not ready (type=${payload?.type ?? 'unknown'})`);
 			return;
 		}
 		try {
 			this.serverWs.send(JSON.stringify(payload));
 		}
-		/* c8 ignore next */
-		catch {}
+		catch (e) {
+			this.logger.warn?.(`[coclaw] forward send failed (type=${payload?.type ?? 'unknown'}): ${e?.message ?? e}`);
+		}
 	}
 
 	__nextGatewayReqId(prefix = 'coclaw-rpc') {
@@ -655,7 +664,7 @@ export class RealtimeBridge {
 		// 用 rpcSeq 保证 ID 唯一，避免 v3→legacy 同毫秒内两次调用产生相同 id
 		this.gatewayRpcSeq += 1;
 		this.gatewayConnectReqId = `coclaw-connect-${Date.now()}-${this.gatewayRpcSeq}`;
-		this.__logDebug(`gateway connect request -> id=${this.gatewayConnectReqId} legacy=${legacy}`);
+		this.logger.info?.(`[coclaw] gateway connect request -> id=${this.gatewayConnectReqId} legacy=${legacy}`);
 		try {
 			const authToken = this.__resolveGatewayAuthToken();
 			const params = {
@@ -726,11 +735,13 @@ export class RealtimeBridge {
 		if (this.__gatewayGaveUp || this.__gatewayRetryTimer) {
 			return;
 		}
-		if (this.gatewayWs || !this.serverWs || this.serverWs.readyState !== 1) {
+		// 外/内/P2P 三条线各自独立：内线（plugin↔本机 gateway）的建连节奏不再看外线脸色。
+		// 外线断不影响这里启动，外线即便没起来也允许内线先跑（DC RPC 仍能通过 P2P 直达）。
+		if (this.gatewayWs) {
 			return;
 		}
 		const WebSocketCtor = this.__resolveWebSocket();
-		/* c8 ignore next 3 -- 已在 __connectIfNeeded 中守卫 */
+		/* c8 ignore next 3 -- WebSocketCtor=null 仅测试注入下出现，生产路径 ws 库总能解析 */
 		if (!WebSocketCtor) {
 			return;
 		}
@@ -770,7 +781,7 @@ export class RealtimeBridge {
 				if (payload.type === 'event' && payload.event === 'connect.challenge') {
 					const nonce = payload?.payload?.nonce ?? '';
 					lastChallengeNonce = nonce;
-					this.__logDebug(`gateway event <- connect.challenge legacyMode=${this.__gatewayLegacyMode}`);
+					this.logger.info?.(`[coclaw] gateway event <- connect.challenge legacyMode=${this.__gatewayLegacyMode}`);
 					// 已经学到此 gateway 是 legacy（上一条 WS 回退过）→ 直接发 legacy 握手
 					if (this.__gatewayLegacyMode) {
 						pendingLegacyAttempted = true;
@@ -787,7 +798,7 @@ export class RealtimeBridge {
 						wasReady = true;
 						this.__gatewayAttempts = 0; // 成功握手 → 重置失败计数，让后续瞬态断开有完整重试预算
 						remoteLog('ws.connected peer=gateway');
-						this.__logDebug(`gateway connect ok <- id=${payload.id}`);
+						this.logger.info?.(`[coclaw] gateway connect ok <- id=${payload.id}`);
 						this.gatewayConnectReqId = null;
 						this.__ensureSessionsPromise = this.__ensureAllAgentSessions();
 						this.__pushInstanceInfo();
@@ -918,7 +929,7 @@ export class RealtimeBridge {
 		});
 
 		ws.addEventListener('open', () => {
-			this.__logDebug('gateway ws open, waiting for connect.challenge');
+			this.logger.info?.('[coclaw] gateway ws open, waiting for connect.challenge');
 		});
 		ws.addEventListener('close', (ev) => {
 			// 区分本端 plugin 主动关闭与对端 OpenClaw gateway 关闭：日志/远程上报用不同事件名，
@@ -958,14 +969,11 @@ export class RealtimeBridge {
 				settle({ ok: false, error: 'gateway_closed' });
 			}
 			this.gatewayPendingRequests.clear();
-			// 同步清空 UI 转发 RPC 路由表（同 __closeGatewayWs 语义）
-			this.__dcPendingRequests.clear();
-			// 同步清空 runId 路由表（gateway 已断，不会再有 event:agent 推过来）
-			this.__runEventRoutes?.clear();
-			// 调度下一次尝试：仅在 bridge 仍活着、未 gave-up、server WS 健康时；
-			// 其他场景（如 bridge stop、server WS 已断）由上游流程兜底，不参与 gateway 重试。
+			// P2P 路由表（__dcPendingRequests / __runEventRoutes）不在这里清：
+			// 内线翻转不应级联影响 P2P。已发出去的 RPC 在 UI 侧 30/60s 超时兜底；
+			// 路由表条目由 start() 启动的周期扫描器（24h TTL）回收，stop() 时显式 clear。
+			// 调度下一次尝试：仅在 bridge 仍活着、未 gave-up 时；不再看外线脸色（外/内独立重试）。
 			if (this.started && !this.__gatewayGaveUp
-				&& this.serverWs && this.serverWs.readyState === 1
 				&& (wasReady || connectFailReported)) {
 				if (wasReady) {
 					// 之前握成功过，视为瞬态掉线 → 重置计数，让新一轮拿到完整重试预算
@@ -1241,7 +1249,7 @@ export class RealtimeBridge {
 			this.logger.warn?.(`[coclaw] realtime bridge connect timeout, will retry: ${maskedTarget}`);
 			remoteLog('ws.connect-timeout peer=server');
 			this.serverWs = null;
-			this.__closeGatewayWs();
+			// 外线超时不级联关内线/清 P2P 路由：三条线各自独立。
 			this.__scheduleReconnect();
 			try { sock.close(4000, 'connect_timeout'); }
 			/* c8 ignore next */
@@ -1267,7 +1275,12 @@ export class RealtimeBridge {
 			// __buildEnvLine 内部所有读取均为缓存值，无 native syscall。
 			remoteLog(this.__buildEnvLine());
 			this.__startServerHeartbeat(sock);
-			this.__ensureGatewayConnection();
+			// 三线独立后内线可能先于外线就绪：那次 push 因外线未 open 在 server 路径被 drop，
+			// 故外线 open 时若内线已 ready 补推一次。门控 gatewayReady 是因为 agentModels 依赖
+			// 内线 agents.list RPC，内线没就绪发出去字段不全会污染 admin 仪表盘。
+			if (this.gatewayReady) {
+				this.__pushInstanceInfo();
+			}
 		});
 
 		sock.addEventListener('message', async (event) => {
@@ -1321,20 +1334,26 @@ export class RealtimeBridge {
 			const wasIntentional = this.intentionallyClosed;
 			this.serverWs = null;
 			this.intentionallyClosed = false;
-			this.__closeGatewayWs();
-			if (this.webrtcPeer) {
-				try { await this.webrtcPeer.closeAll(); }
-				/* c8 ignore next 3 -- 防御性兜底，werift close 异常时不可崩溃 gateway */
-				catch (e) { this.logger.warn?.(`[coclaw/rtc] closeAll failed: ${e?.message}`); }
-				this.webrtcPeer = null;
-				this.__webrtcPeerReady = null;
-			}
-			if (this.__fileHandler) {
-				this.__fileHandler.cancelCleanup();
-				this.__fileHandler = null;
-			}
-
-			if (event?.code === 4001 || event?.code === 4003) {
+			// 外线 close 不再级联关内线/清 P2P 路由：内线（plugin↔本机 gateway）与 P2P
+			// 与外线（plugin↔远端 server）解耦，各自独立维护生命周期。auth-close 分支
+			// （下方）是唯一允许级联 PC/fileHandler/token 的路径，因为 plugin 已失资格。
+
+			// auth-close (4001/4003) 语义是 plugin 失去服务资格，必须连同 PC/fileHandler 一起清；
+			// 其它 close code（含 4000 心跳超时、1006 abnormal、1011 等）视为信令通道瞬态不通，
+			// 保留 webrtcPeer / fileHandler 实例供重连后复用，避免雪崩式 PC 重建。
+			const isAuthClose = event?.code === 4001 || event?.code === 4003;
+			if (isAuthClose) {
+				if (this.webrtcPeer) {
+					try { await this.webrtcPeer.closeAll(); }
+					/* c8 ignore next 3 -- 防御性兜底，werift close 异常时不可崩溃 gateway */
+					catch (e) { this.logger.warn?.(`[coclaw/rtc] closeAll failed: ${e?.message}`); }
+					this.webrtcPeer = null;
+					this.__webrtcPeerReady = null;
+				}
+				if (this.__fileHandler) {
+					this.__fileHandler.cancelCleanup();
+					this.__fileHandler = null;
+				}
 				remoteLog(`ws.auth-close peer=server code=${event.code}`);
 				this.logger.warn?.(`[coclaw] server ws auth-close (code=${event.code}), clearing local token`);
 				try {
@@ -1348,8 +1367,9 @@ 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`);
+				const sessionCount = this.webrtcPeer?.__sessions?.size ?? 0;
+				remoteLog(`ws.disconnected peer=server code=${event?.code ?? 'unknown'} reason=${event?.reason ?? 'n/a'} keep-pc=true sessions=${sessionCount}`);
+				this.logger.warn?.(`[coclaw] realtime bridge closed (${event?.code ?? 'unknown'}: ${event?.reason ?? 'n/a'}), will retry in ${RECONNECT_MS}ms (keep-pc, sessions=${sessionCount})`);
 				this.__scheduleReconnect();
 			}
 		});
@@ -1365,7 +1385,7 @@ export class RealtimeBridge {
 			/* c8 ignore next -- ?./?? fallback */
 			this.logger.warn?.(`[coclaw] realtime bridge error, will retry in ${RECONNECT_MS}ms: ${String(err?.message ?? err)}`);
 			this.serverWs = null;
-			this.__closeGatewayWs();
+			// 外线 error 不级联关内线/清 P2P 路由：三条线各自独立。
 			this.__scheduleReconnect();
 			try { sock.close(4000, 'connect_error'); }
 			/* c8 ignore next */
@@ -1502,7 +1522,11 @@ export class RealtimeBridge {
 			scanMs: this.__runEventRoutesScanMs,
 		});
 		this.__runEventRoutes.init();
+		// 外线（plugin↔远端 server）先发起 connectIfNeeded：仅创建 WebSocket 即返回，不阻塞内线。
 		await this.__connectIfNeeded();
+		// 三条线各自独立启动：内线（plugin↔本机 gateway）由 start() 主动触发，
+		// 不再依附于外线 open。即便外线建连失败/未配置 token，内线仍能起来支撑 DC RPC。
+		this.__ensureGatewayConnection();
 	}
 
 	/**
@@ -1533,6 +1557,8 @@ export class RealtimeBridge {
 		this.__clearServerHeartbeat();
 		this.__clearConnectTimer();
 		// stop() / refresh() 兜底回收 lag 探针的 timer，防 unref 仍残留。
+		// 顺序依赖：必须早于下方 __closeGatewayWs；后者会立刻把 gatewayWs 置 null，
+		// 异步触发的 close 事件会被 stale guard 早返而无法走到 __clearAllLagProbes。
 		this.__clearAllLagProbes();
 		if (this.reconnectTimer) {
 			clearTimeout(this.reconnectTimer);
@@ -1557,6 +1583,9 @@ export class RealtimeBridge {
 			this.__runEventRoutes.destroy();
 			this.__runEventRoutes = null;
 		}
+		// stop / refresh 是显式销毁路径：P2P 路由表不再随内线翻转清理（动作 5），
+		// 但显式销毁时必须清干净，避免 refresh 后留下指向旧 connId 的孤儿条目。
+		this.__dcPendingRequests.clear();
 		this.__closeGatewayWs();
 		if (this.webrtcPeer) {
 			await this.webrtcPeer.closeAll().catch(() => {});

package/src/rpc-routing/run-event-routes.js

@@ -14,7 +14,8 @@
  * - timer 必须 unref()——避免 hold 进程退出
  *
  * 与 reqId 路由表（realtime-bridge.js __dcPendingRequests）保持行为对齐：
- * 对 PC 关闭不做联动清理，TTL 兜底；网关 WS 断开走 clear()。
+ * 对 PC 关闭和网关 WS 翻转都不做联动清理（外/内/P2P 三线独立），TTL 兜底；
+ * 仅显式销毁路径（bridge.stop / refresh）会通过 destroy() 清表。
  */
 
 /** 路由条目最大存活时间（24h），与 reqId 表对齐 */