@coclaw/openclaw-coclaw 0.6.1 → 0.7.0

package/README.md

@@ -72,7 +72,8 @@ openclaw coclaw unbind [--server <url>]
 openclaw coclaw enroll [--server <url>]
 ```
 
-- bind/unbind 成功后会通过 gateway RPC 通知插件刷新/停止 bridge 连接（无需重启 gateway）。若 gateway 未运行，通知会失败但不影响绑定结果。
+- bind/unbind/enroll 均为瘦 CLI，通过 gateway RPC（`coclaw.bind`/`coclaw.unbind`/`coclaw.enroll`）在 gateway 内执行，由 gateway 内部管理 bridge 生命周期。若 gateway 未运行，CLI 会自动尝试重启一次再重试；若仍不可用，操作失败。
+- unbind 是强制操作：server 不可达时操作失败（不清理本地 config，避免产生孤儿 bot）。server 返回 401/404/410 视为 bot 已不存在，允许继续。
 - enroll 由 OpenClaw 侧主动发起，生成认领码和链接供用户点击完成绑定。已绑定时需先 unbind 再发起。
 
 ### 方式二：IM 渠道命令
@@ -87,13 +88,15 @@ openclaw coclaw enroll [--server <url>]
 
 需要 gateway 运行中。
 
-### 方式三：独立 CLI（兼容）
+### 方式三：独立 CLI（遗留）
 
 ```bash
 node ~/.openclaw/extensions/coclaw/src/cli.js bind <binding-code> --server <url>
 node ~/.openclaw/extensions/coclaw/src/cli.js unbind --server <url>
 ```
 
+> 注意：独立 CLI 不走 gateway RPC，直接在 CLI 进程中执行 bind/unbind 并通过 `coclaw.refreshBridge`/`coclaw.stopBridge` 通知 gateway。此路径不具备瘦 CLI 的架构保证（所有 config 操作在同一进程内）。推荐使用方式一。
+
 ## 配置存储
 
 绑定信息存储在 `~/.openclaw/coclaw/bindings.json`（通过 `resolveStateDir()` + channel ID 组合路径），**不存储在 `openclaw.json` 中**。

package/index.js

@@ -149,6 +149,70 @@ const plugin = {
 			}
 		});
 
+		// --- bind/unbind 共享逻辑（RPC handler + 斜杠命令共用） ---
+
+		async function doBind({ code, serverUrl }) {
+			await stopRealtimeBridge();
+			let result;
+			try {
+				result = await bindBot({
+					code,
+					serverUrl: serverUrl ?? api.pluginConfig?.serverUrl,
+				});
+			} catch (err) {
+				// bind 失败时恢复 bridge（best-effort，不覆盖原始错误）
+				await restartRealtimeBridge({ logger, pluginConfig: api.pluginConfig }).catch(() => {});
+				throw err;
+			}
+			// bind 已持久化，restart 失败不影响结果
+			await restartRealtimeBridge({ logger, pluginConfig: api.pluginConfig }).catch((err) => {
+				logger.warn?.(`[coclaw] bridge restart failed after bind: ${err?.message ?? err}`);
+			});
+			return result;
+		}
+
+		async function doUnbind({ serverUrl }) {
+			const result = await unbindBot({
+				serverUrl: serverUrl ?? api.pluginConfig?.serverUrl,
+			});
+			await stopRealtimeBridge();
+			return result;
+		}
+
+		api.registerGatewayMethod('coclaw.bind', async ({ params, respond }) => {
+			try {
+				const code = params?.code;
+				if (!code) {
+					respondInvalid(respond, 'code is required');
+					return;
+				}
+				const result = await doBind({
+					code,
+					serverUrl: params?.serverUrl,
+				});
+				respond(true, {
+					status: {
+						botId: result.botId,
+						rebound: result.rebound,
+						previousBotId: result.previousBotId,
+					},
+				});
+			}
+			catch (err) {
+				respondError(respond, err);
+			}
+		});
+
+		api.registerGatewayMethod('coclaw.unbind', async ({ params, respond }) => {
+			try {
+				const result = await doUnbind({ serverUrl: params?.serverUrl });
+				respond(true, { status: { botId: result.botId } });
+			}
+			catch (err) {
+				respondError(respond, err);
+			}
+		});
+
 		// enroll 并发控制：同一时刻只允许一个活跃 enroll
 		let activeEnrollAbort = null;
 
@@ -429,13 +493,10 @@ const plugin = {
 
 				try {
 					if (action === 'bind') {
-						await stopRealtimeBridge(); // 先断开，避免 bindBot 内 unbind 触发 bot.unbound 竞态
-						const serverUrl = options.server ?? api.pluginConfig?.serverUrl;
-						const result = await bindBot({
+						const result = await doBind({
 							code: positionals[0],
-							serverUrl,
+							serverUrl: options.server,
 						});
-						await restartRealtimeBridge({ logger, pluginConfig: api.pluginConfig });
 						return { text: bindOk(result) };
 					}
 
@@ -483,8 +544,7 @@ const plugin = {
 					}
 
 					if (action === 'unbind') {
-						const result = await unbindBot({ serverUrl: options.server });
-						await stopRealtimeBridge();
+						const result = await doUnbind({ serverUrl: options.server });
 						return { text: unbindOk(result) };
 					}
 

package/openclaw.plugin.json

@@ -2,7 +2,6 @@
   "id": "openclaw-coclaw",
   "name": "CoClaw",
   "description": "OpenClaw CoClaw channel plugin for remote chat",
-  "channels": ["coclaw"],
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coclaw/openclaw-coclaw",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "type": "module",
   "license": "Apache-2.0",
   "description": "OpenClaw CoClaw channel plugin for remote chat",
@@ -63,6 +63,9 @@
     "release:check": "bash ./scripts/release-check.sh",
     "release:versions": "npm view @coclaw/openclaw-coclaw versions --json --registry=https://registry.npmjs.org/ && npm view @coclaw/openclaw-coclaw versions --json"
   },
+  "dependencies": {
+    "werift": "^0.19.0"
+  },
   "devDependencies": {
     "c8": "^10.1.3",
     "eslint": "^9.39.2"

package/src/channel-plugin.js

@@ -22,7 +22,7 @@ export const coclawChannelPlugin = {
 	capabilities: {
 		chatTypes: ['direct'],
 		nativeCommands: true,
-		media: false,
+		media: true,
 		reactions: false,
 		threads: false,
 		polls: false,

package/src/cli-registrar.js

@@ -1,9 +1,7 @@
-import { bindBot, unbindBot } from './common/bot-binding.js';
 import { resolveErrorMessage } from './common/errors.js';
 import { callGatewayMethod } from './common/gateway-notify.js';
 import {
 	notBound, bindOk, unbindOk,
-	gatewayNotified, gatewayNotifyFailed,
 	claimCodeCreated,
 } from './common/messages.js';
 
@@ -43,55 +41,82 @@ async function restartGatewayProcess(spawnFn) {
 }
 /* c8 ignore stop */
 
-function resolveServerUrl(opts, config) {
-	return opts?.server
-		?? config?.plugins?.entries?.['openclaw-coclaw']?.config?.serverUrl
-		?? process.env.COCLAW_SERVER_URL;
+// bind/unbind/enroll 的 RPC 超时（覆盖默认 10s）
+// 卡点是 gateway ↔ server 的网络通信，bind 最多两次（先解绑再绑定）
+const RPC_TIMEOUT_MS = 30_000;
+
+/**
+ * 通用 RPC 调用：gateway 不可用时重启重试
+ */
+async function callWithRetry(method, deps, rpcOpts) {
+	const callRpc = () => callGatewayMethod(method, deps.spawn, rpcOpts);
+
+	let result = await callRpc();
+
+	if (isGatewayUnavailable(result)) {
+		const restartFn = deps.restartGateway ?? restartGatewayProcess;
+		try {
+			await restartFn(deps.spawn);
+		} catch {
+			// 重启失败，仍然尝试再次 RPC
+		}
+		result = await callRpc();
+	}
+
+	return result;
 }
 
 /**
- * 注册 `openclaw coclaw bind/unbind` CLI 子命令
+ * 通用 RPC 错误输出
+ */
+function handleRpcError(result, fallbackMsg) {
+	if (isGatewayUnavailable(result)) {
+		console.error('Error: Could not reach gateway. Ensure OpenClaw gateway is running.');
+		console.error('  Try: openclaw gateway start');
+	} else {
+		console.error(`Error: ${extractRpcErrorMessage(result.message) || fallbackMsg}`);
+	}
+	process.exitCode = 1;
+}
+
+/**
+ * 注册 `openclaw coclaw bind/unbind/enroll` CLI 子命令
+ * bind/unbind/enroll 均为瘦 CLI，通过 gateway RPC 执行
  * @param {object} ctx - OpenClaw CLI 注册上下文
  * @param {import('commander').Command} ctx.program - Commander.js Command 实例
- * @param {object} ctx.config - OpenClaw 配置
  * @param {object} ctx.logger - 日志实例
  * @param {object} [deps] - 可注入依赖（测试用）
  */
-export function registerCoclawCli({ program, config, logger }, deps = {}) {
-	const notifyGateway = async (method) => {
-		const action = method.endsWith('refreshBridge') ? 'refresh' : 'stop';
-		try {
-			const result = await callGatewayMethod(method, deps.spawn);
-			if (result.ok) {
-				logger.info?.(`[coclaw] ${gatewayNotified(action)}`);
-			} else {
-				logger.warn?.(`[coclaw] ${gatewayNotifyFailed()}`);
-			}
-		}
-		/* c8 ignore next 3 -- callGatewayMethod 已内部兜底，此处纯防御 */
-		catch {
-			logger.warn?.(`[coclaw] ${gatewayNotifyFailed()}`);
-		}
-	};
-
+export function registerCoclawCli({ program, logger }, deps = {}) {
 	const coclaw = program
 		.command('coclaw')
 		.description('CoClaw bind/unbind commands');
 
 	coclaw
 		.command('bind <code>')
-		.description('Bind this OpenClaw instance to CoClaw')
+		.description('Bind this Claw to CoClaw')
 		.option('--server <url>', 'CoClaw server URL')
 		.action(async (code, opts) => {
 			try {
-				// 先断开 bridge，避免 unbindWithServer 触发的 bot.unbound 竞态
-				await notifyGateway('coclaw.stopBridge');
-				const serverUrl = resolveServerUrl(opts, config);
-				const result = await bindBot({ code, serverUrl });
-				/* c8 ignore next */
-				console.log(bindOk(result));
-				await notifyGateway('coclaw.refreshBridge');
-			} catch (err) {
+				const params = { code };
+				if (opts?.server) params.serverUrl = opts.server;
+				const result = await callWithRetry('coclaw.bind', deps, { params, timeoutMs: RPC_TIMEOUT_MS });
+
+				if (!result.ok) {
+					if (result.message && /NOT_BOUND|UNBIND_FAILED/.test(result.message)) {
+						console.error(`Error: ${extractRpcErrorMessage(result.message) || 'bind failed'}`);
+						process.exitCode = 1;
+						return;
+					}
+					handleRpcError(result, 'bind failed');
+					return;
+				}
+
+				const data = result.status;
+				console.log(bindOk(data));
+			}
+			/* c8 ignore next 4 -- callGatewayMethod 不会抛异常，纯防御 */
+			catch (err) {
 				console.error(`Error: ${resolveErrorMessage(err)}`);
 				process.exitCode = 1;
 			}
@@ -99,36 +124,16 @@ export function registerCoclawCli({ program, config, logger }, deps = {}) {
 
 	coclaw
 		.command('enroll')
-		.description('Enroll this OpenClaw instance with CoClaw (generate a claim code for the user)')
+		.description('Enroll this Claw with CoClaw (generate a claim code for the user)')
 		.option('--server <url>', 'CoClaw server URL')
 		.action(async (opts) => {
 			try {
-				const rpcOpts = opts?.server ? { params: { serverUrl: opts.server } } : undefined;
-				const callRpc = () => callGatewayMethod('coclaw.enroll', deps.spawn, rpcOpts);
-
-				let result = await callRpc();
-
-				// 仅在 gateway 不可用时重启重试，业务错误不重启
-				if (isGatewayUnavailable(result)) {
-					logger.info?.('[coclaw] enroll RPC failed, attempting gateway restart...');
-					const restartFn = deps.restartGateway ?? restartGatewayProcess;
-					try {
-						await restartFn(deps.spawn);
-					} catch {
-						// 重启失败，仍然尝试再次 RPC
-					}
-					result = await callRpc();
-				}
+				const rpcOpts = { timeoutMs: RPC_TIMEOUT_MS };
+				if (opts?.server) rpcOpts.params = { serverUrl: opts.server };
+				const result = await callWithRetry('coclaw.enroll', deps, rpcOpts);
 
 				if (!result.ok) {
-					if (isGatewayUnavailable(result)) {
-						console.error('Error: Could not reach gateway. Ensure OpenClaw gateway is running.');
-						console.error('  Try: openclaw gateway start');
-					} else {
-						// 业务错误（如已绑定）：输出 gateway 返回的错误信息
-						console.error(`Error: ${extractRpcErrorMessage(result.message) || 'enroll failed'}`);
-					}
-					process.exitCode = 1;
+					handleRpcError(result, 'enroll failed');
 					return;
 				}
 
@@ -154,24 +159,31 @@ export function registerCoclawCli({ program, config, logger }, deps = {}) {
 
 	coclaw
 		.command('unbind')
-		.description('Unbind this OpenClaw instance from CoClaw')
+		.description('Unbind this Claw from CoClaw')
 		.option('--server <url>', 'CoClaw server URL')
 		.action(async (opts) => {
 			try {
-				const result = await unbindBot({ serverUrl: opts?.server });
-				/* c8 ignore next */
-				console.log(unbindOk(result));
-				await notifyGateway('coclaw.stopBridge');
-			} catch (err) {
-				if (err.code === 'NOT_BOUND') {
-					console.error(notBound());
+				const rpcOpts = { timeoutMs: RPC_TIMEOUT_MS };
+				if (opts?.server) rpcOpts.params = { serverUrl: opts.server };
+				const result = await callWithRetry('coclaw.unbind', deps, rpcOpts);
+
+				if (!result.ok) {
+					if (result.message && /NOT_BOUND/.test(result.message)) {
+						console.error(notBound());
+					} else {
+						handleRpcError(result, 'unbind failed');
+					}
 					process.exitCode = 1;
 					return;
 				}
-				/* c8 ignore start -- 防御性兜底，unbindBot 当前仅抛 NOT_BOUND */
+
+				const data = result.status;
+				console.log(unbindOk(data));
+			}
+			/* c8 ignore next 4 -- callGatewayMethod 不会抛异常，纯防御 */
+			catch (err) {
 				console.error(`Error: ${resolveErrorMessage(err)}`);
 				process.exitCode = 1;
 			}
-			/* c8 ignore stop */
 		});
 }

package/src/cli.js

@@ -92,7 +92,7 @@ export async function main(argv = process.argv.slice(2), deps = {}) {
 				console.error(notBound());
 				return 1;
 			}
-			/* c8 ignore start -- 防御性兜底，unbindBot 当前仅抛 NOT_BOUND */
+			/* c8 ignore start -- 防御性兜底，unbindBot 主要抛 NOT_BOUND，也可能抛网络/HTTP 错误 */
 			throw err;
 		}
 		/* c8 ignore stop */

package/src/common/bot-binding.js

@@ -8,31 +8,53 @@ function resolveServerUrl(serverUrl) {
 	return serverUrl ?? process.env.COCLAW_SERVER_URL ?? DEFAULT_SERVER_URL;
 }
 
-export async function bindBot({ code, serverUrl }) {
+// 这些 HTTP 状态码表示 bot 在 server 端已不存在，视为解绑成功
+const ALREADY_UNBOUND_STATUSES = new Set([401, 404, 410]);
+
+function isAlreadyUnbound(err) {
+	return ALREADY_UNBOUND_STATUSES.has(err?.response?.status);
+}
+
+export async function bindBot({ code, serverUrl }, deps = {}) {
+	const {
+		readCfg = readConfig,
+		clearCfg = clearConfig,
+		writeCfg = writeConfig,
+		unbindServer = unbindWithServer,
+		bindServer = bindWithServer,
+	} = deps;
+
 	if (!code) {
 		throw new Error('binding code is required');
 	}
 
-	const config = await readConfig();
+	const config = await readCfg();
 
-	// 已绑定时自动解绑再重绑（解绑尽力而为，不阻塞新绑定）
+	// 已绑定时必须先解绑旧 bot，避免产生孤儿记录
 	let previousBotId;
 	if (config?.token) {
 		previousBotId = config.botId || 'unknown';
 		const oldBaseUrl = config.serverUrl;
 		if (oldBaseUrl) {
 			try {
-				await unbindWithServer({ baseUrl: oldBaseUrl, token: config.token });
-			} catch {
-				// 尽力而为，忽略解绑错误
+				await unbindServer({ baseUrl: oldBaseUrl, token: config.token });
+			} catch (err) {
+				if (!isAlreadyUnbound(err)) {
+					const rebindErr = new Error(
+						`Failed to unbind previous bot (${previousBotId}): ${err.message}. ` +
+						'Unbind manually first, then retry.',
+					);
+					rebindErr.code = 'UNBIND_FAILED';
+					throw rebindErr;
+				}
 			}
 		}
-		await clearConfig();
+		await clearCfg();
 	}
 
 	/* c8 ignore next */
 	const baseUrl = serverUrl ?? process.env.COCLAW_SERVER_URL ?? DEFAULT_SERVER_URL;
-	const data = await bindWithServer({
+	const data = await bindServer({
 		baseUrl,
 		code,
 	});
@@ -41,7 +63,7 @@ export async function bindBot({ code, serverUrl }) {
 		throw new Error('invalid bind response');
 	}
 
-	await writeConfig({
+	await writeCfg({
 		serverUrl: baseUrl,
 		botId: data.botId,
 		token: data.token,
@@ -128,8 +150,14 @@ export async function waitForClaimAndSave({ serverUrl, code, waitToken, signal }
 	}
 }
 
-export async function unbindBot({ serverUrl }) {
-	const config = await readConfig();
+export async function unbindBot({ serverUrl }, deps = {}) {
+	const {
+		readCfg = readConfig,
+		clearCfg = clearConfig,
+		unbindServer = unbindWithServer,
+	} = deps;
+
+	const config = await readCfg();
 	if (!config?.token) {
 		const err = new Error('not bound, nothing to unbind');
 		err.code = 'NOT_BOUND';
@@ -138,25 +166,18 @@ export async function unbindBot({ serverUrl }) {
 
 	const baseUrl = serverUrl ?? config.serverUrl;
 
-	// 用户主动解绑：无论 server 通知成功与否，都清理本地绑定
-	let data = null;
-	let serverError = null;
 	if (baseUrl) {
 		try {
-			data = await unbindWithServer({
-				baseUrl,
-				token: config.token,
-			});
-		}
-		catch (err) {
-			serverError = err;
+			await unbindServer({ baseUrl, token: config.token });
+		} catch (err) {
+			// bot 在 server 已不存在 — 视为解绑成功，继续清理本地
+			if (!isAlreadyUnbound(err)) {
+				throw err;
+			}
 		}
 	}
 
-	await clearConfig();
+	await clearCfg();
 
-	return {
-		botId: data?.botId ?? config.botId,
-		serverError,
-	};
+	return { botId: config.botId };
 }

package/src/common/errors.js

@@ -3,7 +3,7 @@ const ERROR_TEXT_MAP = {
 	BINDING_CODE_INVALID: 'Binding code is invalid',
 	BINDING_CODE_EXPIRED: 'Binding code has expired, please get a new one',
 	BINDING_CODE_EXHAUSTED: 'Server cannot generate binding code right now, please try again later',
-	BOT_BLOCKED: 'Bot is blocked, please contact the admin',
+	BOT_BLOCKED: 'Claw is blocked, please contact the admin',
 	UNAUTHORIZED: 'Auth failed, please check token or re-bind',
 	INTERNAL_SERVER_ERROR: 'Server error, please try again later',
 };

package/src/common/messages.js

@@ -3,17 +3,14 @@
 export function bindOk({ botId, rebound, previousBotId }) {
 	const action = rebound ? 're-bound' : 'bound';
 	const prev = previousBotId
-		? ` (previous binding to bot ${previousBotId} was auto-removed)`
+		? ` (previous Claw ${previousBotId} was auto-unbound)`
 		: '';
-	return `OK. Bot (${botId}) ${action} to CoClaw.${prev}`;
+	return `OK. Claw (${botId}) ${action} to CoClaw.${prev}`;
 }
 
-export function unbindOk({ botId, serverError }) {
+export function unbindOk({ botId }) {
 	const id = botId ?? 'unknown';
-	const tag = serverError
-		? ' (server notification failed; you can unbind the orphan bot in the CoClaw app)'
-		: '';
-	return `OK. Bot (${id}) unbound from CoClaw.${tag}`;
+	return `OK. Claw (${id}) unbound from CoClaw.`;
 }
 
 export function notBound() {

package/src/config.js

@@ -3,6 +3,8 @@ import os from 'node:os';
 import nodePath from 'node:path';
 
 import { getRuntime } from './runtime.js';
+import { atomicWriteJsonFile } from './utils/atomic-write.js';
+import { createMutex } from './utils/mutex.js';
 
 export const DEFAULT_ACCOUNT_ID = 'default';
 const CHANNEL_ID = 'coclaw';
@@ -42,11 +44,7 @@ async function readJson(filePath) {
 	}
 }
 
-async function writeJson(filePath, value) {
-	const dirPath = nodePath.dirname(filePath);
-	await fs.mkdir(dirPath, { recursive: true });
-	await fs.writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
-}
+const bindingsMutex = createMutex();
 
 // --- 公共 API ---
 
@@ -57,35 +55,39 @@ export async function readConfig(accountId = DEFAULT_ACCOUNT_ID) {
 }
 
 export async function writeConfig(nextConfig, accountId = DEFAULT_ACCOUNT_ID) {
-	const bindingsPath = getBindingsPath();
-	const bindings = toRecord(await readJson(bindingsPath));
-	const current = toRecord(bindings[accountId]);
+	return bindingsMutex.withLock(async () => {
+		const bindingsPath = getBindingsPath();
+		const bindings = toRecord(await readJson(bindingsPath));
+		const current = toRecord(bindings[accountId]);
 
-	const next = { ...current };
-	if (nextConfig.serverUrl !== undefined) next.serverUrl = nextConfig.serverUrl;
-	if (nextConfig.botId !== undefined) next.botId = nextConfig.botId;
-	if (nextConfig.token !== undefined) next.token = nextConfig.token;
-	if (nextConfig.boundAt !== undefined) next.boundAt = nextConfig.boundAt;
+		const next = { ...current };
+		if (nextConfig.serverUrl !== undefined) next.serverUrl = nextConfig.serverUrl;
+		if (nextConfig.botId !== undefined) next.botId = nextConfig.botId;
+		if (nextConfig.token !== undefined) next.token = nextConfig.token;
+		if (nextConfig.boundAt !== undefined) next.boundAt = nextConfig.boundAt;
 
-	bindings[accountId] = next;
-	await writeJson(bindingsPath, bindings);
+		bindings[accountId] = next;
+		await atomicWriteJsonFile(bindingsPath, bindings);
+	});
 }
 
 export async function clearConfig(accountId = DEFAULT_ACCOUNT_ID) {
-	const bindingsPath = getBindingsPath();
-	const bindings = toRecord(await readJson(bindingsPath));
-	delete bindings[accountId];
+	return bindingsMutex.withLock(async () => {
+		const bindingsPath = getBindingsPath();
+		const bindings = toRecord(await readJson(bindingsPath));
+		delete bindings[accountId];
 
-	const remaining = Object.keys(bindings).length;
-	if (remaining === 0) {
-		try {
-			await fs.unlink(bindingsPath);
+		const remaining = Object.keys(bindings).length;
+		if (remaining === 0) {
+			try {
+				await fs.unlink(bindingsPath);
+			}
+			/* c8 ignore next 4 */
+			catch (err) {
+				if (err?.code !== 'ENOENT') throw err;
+			}
+		} else {
+			await atomicWriteJsonFile(bindingsPath, bindings);
 		}
-		/* c8 ignore next 4 */
-		catch (err) {
-			if (err?.code !== 'ENOENT') throw err;
-		}
-	} else {
-		await writeJson(bindingsPath, bindings);
-	}
+	});
 }

package/src/realtime-bridge.js

@@ -97,6 +97,7 @@ export class RealtimeBridge {
 		this.serverHbTimer = null;
 		this.__serverHbMissCount = 0;
 		this.__deviceIdentity = null;
+		this.webrtcPeer = null;
 	}
 
 	__resolveWebSocket() {
@@ -163,11 +164,15 @@ export class RealtimeBridge {
 			?? DEFAULT_GATEWAY_WS_URL;
 	}
 
-	async __clearTokenLocal() {
+	async __clearTokenLocal(unboundBotId) {
 		const cfg = await this.__readConfig();
 		if (!cfg?.token) {
 			return;
 		}
+		// 只清除匹配的 bot，避免新绑定被误清
+		if (unboundBotId && cfg.botId && cfg.botId !== unboundBotId) {
+			return;
+		}
 		await this.__clearConfig();
 	}
 
@@ -508,6 +513,7 @@ export class RealtimeBridge {
 			}
 			if (payload.type === 'res' || payload.type === 'event') {
 				this.__forwardToServer(payload);
+				this.webrtcPeer?.broadcast(payload);
 			}
 		});
 
@@ -518,6 +524,11 @@ export class RealtimeBridge {
 			this.gatewayWs = null;
 			this.gatewayReady = false;
 			this.gatewayConnectReqId = null;
+			/* c8 ignore next 3 -- gateway 意外断开时结算未完成 RPC，避免等超时 */
+			for (const [, settle] of this.gatewayPendingRequests) {
+				settle({ ok: false, error: 'gateway_closed' });
+			}
+			this.gatewayPendingRequests.clear();
 		});
 		ws.addEventListener('error', () => {});
 	}
@@ -571,7 +582,7 @@ export class RealtimeBridge {
 		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}`);
-			this.__forwardToServer({
+			const errorRes = {
 				type: 'res',
 				id: payload.id,
 				ok: false,
@@ -579,7 +590,9 @@ export class RealtimeBridge {
 					code: 'GATEWAY_OFFLINE',
 					message: 'Gateway is offline',
 				},
-			});
+			};
+			this.__forwardToServer(errorRes);
+			this.webrtcPeer?.broadcast(errorRes);
 			return;
 		}
 		try {
@@ -592,7 +605,7 @@ export class RealtimeBridge {
 			}));
 		}
 		catch {
-			this.__forwardToServer({
+			const errorRes = {
 				type: 'res',
 				id: payload.id,
 				ok: false,
@@ -600,7 +613,9 @@ export class RealtimeBridge {
 					code: 'GATEWAY_SEND_FAILED',
 					message: 'Failed to send request to gateway',
 				},
-			});
+			};
+			this.__forwardToServer(errorRes);
+			this.webrtcPeer?.broadcast(errorRes);
 		}
 	}
 
@@ -681,12 +696,30 @@ export class RealtimeBridge {
 			try {
 				const payload = JSON.parse(String(event.data ?? '{}'));
 				if (payload?.type === 'bot.unbound') {
-					await this.__clearTokenLocal();
+					await this.__clearTokenLocal(payload.botId);
 					try { sock.close(4001, 'bot_unbound'); }
 					/* c8 ignore next */
 					catch {}
 					return;
 				}
+				if (payload?.type?.startsWith('rtc:')) {
+					try {
+						if (!this.webrtcPeer) {
+							const { WebRtcPeer } = await import('./webrtc-peer.js');
+							this.webrtcPeer = new WebRtcPeer({
+								onSend: (msg) => this.__forwardToServer(msg),
+								onRequest: (dcPayload) => {
+									void this.__handleGatewayRequestFromServer(dcPayload);
+								},
+								logger: this.logger,
+							});
+						}
+						await this.webrtcPeer.handleSignaling(payload);
+					} catch (err) {
+						this.logger.warn?.(`[coclaw/rtc] signaling error (or werift not found): ${err?.message}`);
+					}
+					return;
+				}
 				if (payload?.type === 'req' || payload?.type === 'rpc.req') {
 					void this.__handleGatewayRequestFromServer({
 						id: payload.id,
@@ -711,9 +744,21 @@ export class RealtimeBridge {
 			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;
+			}
 
 			if (event?.code === 4001 || event?.code === 4003) {
-				await this.__clearTokenLocal();
+				try {
+					await this.__clearTokenLocal();
+				}
+				/* c8 ignore next 3 -- 防御性兜底，磁盘 I/O 异常时不可崩溃 gateway */
+				catch (e) {
+					this.logger.error?.('[coclaw] clearTokenLocal failed on auth-close', e);
+				}
 				return;
 			}
 
@@ -763,6 +808,10 @@ export class RealtimeBridge {
 			this.reconnectTimer = null;
 		}
 		this.__closeGatewayWs();
+		if (this.webrtcPeer) {
+			await this.webrtcPeer.closeAll().catch(() => {});
+			this.webrtcPeer = null;
+		}
 		const sock = this.serverWs;
 		if (sock) {
 			this.intentionallyClosed = true;

package/src/webrtc-peer.js

@@ -0,0 +1,192 @@
+import { RTCPeerConnection as WeriftRTCPeerConnection } from 'werift';
+
+/**
+ * 管理多个 WebRTC PeerConnection（以 connId 为粒度）。
+ * Plugin 作为被叫方：收到 UI 的 offer → 回复 answer。
+ */
+export class WebRtcPeer {
+	/**
+	 * @param {object} opts
+	 * @param {function} opts.onSend - 将信令消息交给 RealtimeBridge 发送
+	 * @param {function} [opts.onRequest] - DataChannel 收到 req 消息时的回调 (payload, connId) => void
+	 * @param {object} [opts.logger] - pino 风格 logger
+	 * @param {function} [opts.PeerConnection] - 可替换的构造函数（测试用）
+	 */
+	constructor({ onSend, onRequest, logger, PeerConnection }) {
+		this.__onSend = onSend;
+		this.__onRequest = onRequest;
+		this.logger = logger ?? console;
+		this.__PeerConnection = PeerConnection ?? WeriftRTCPeerConnection;
+		/** @type {Map<string, { pc: object, rpcChannel: object|null }>} */
+		this.__sessions = new Map();
+	}
+
+	/** 处理来自 Server 转发的信令消息 */
+	async handleSignaling(msg) {
+		const connId = msg.fromConnId ?? msg.toConnId;
+		if (msg.type === 'rtc:offer') {
+			await this.__handleOffer(msg);
+		} else if (msg.type === 'rtc:ice') {
+			await this.__handleIce(msg);
+		} else if (msg.type === 'rtc:ready' || msg.type === 'rtc:closed') {
+			this.__logDebug(`${msg.type} from ${connId}`);
+			if (msg.type === 'rtc:closed') {
+				await this.closeByConnId(connId);
+			}
+		}
+	}
+
+	/** 关闭指定 connId 的 PeerConnection */
+	async closeByConnId(connId) {
+		const session = this.__sessions.get(connId);
+		if (!session) return;
+		this.__sessions.delete(connId);
+		await session.pc.close();
+		this.logger.info?.(`[coclaw/rtc] [${connId}] closed`);
+	}
+
+	/** 关闭所有 PeerConnection */
+	async closeAll() {
+		const closing = [...this.__sessions.keys()].map((id) => this.closeByConnId(id));
+		await Promise.all(closing);
+	}
+
+	/** 向所有已打开的 rpcChannel 广播 */
+	broadcast(payload) {
+		const data = JSON.stringify(payload);
+		for (const [connId, session] of this.__sessions) {
+			const dc = session.rpcChannel;
+			if (dc?.readyState === 'open') {
+				try { dc.send(data); }
+				catch (err) { this.__logDebug(`[${connId}] broadcast send failed: ${err.message}`); }
+			}
+		}
+	}
+
+	async __handleOffer(msg) {
+		const connId = msg.fromConnId;
+		this.logger.info?.(`[coclaw/rtc] offer received from ${connId}, creating answer`);
+
+		// 同一 connId 重复 offer → 先关闭旧连接
+		if (this.__sessions.has(connId)) {
+			await this.closeByConnId(connId);
+		}
+
+		// 从 Server 注入的 turnCreds 构建 iceServers
+		// werift 的 urls 必须是单个 string，每个 URL 独立一个对象
+		const iceServers = [];
+		if (msg.turnCreds) {
+			const { urls, username, credential } = msg.turnCreds;
+			for (const url of urls) {
+				const server = { urls: url };
+				if (url.startsWith('turn:')) {
+					server.username = username;
+					server.credential = credential;
+				}
+				iceServers.push(server);
+			}
+		}
+
+		const pc = new this.__PeerConnection({ iceServers });
+		const session = { pc, rpcChannel: null };
+		this.__sessions.set(connId, session);
+
+		// ICE candidate → 发给 UI
+		pc.onicecandidate = ({ candidate }) => {
+			if (!candidate) return;
+			this.__onSend({
+				type: 'rtc:ice',
+				toConnId: connId,
+				payload: {
+					candidate: candidate.candidate,
+					sdpMid: candidate.sdpMid,
+					sdpMLineIndex: candidate.sdpMLineIndex,
+				},
+			});
+		};
+
+		// 连接状态变更
+		pc.onconnectionstatechange = () => {
+			const state = pc.connectionState;
+			this.logger.info?.(`[coclaw/rtc] [${connId}] connectionState: ${state}`);
+			if (state === 'connected') {
+				const nominated = pc.iceTransports?.[0]?.connection?.nominated;
+				if (nominated) {
+					const type = nominated.localCandidate?.type ?? 'unknown';
+					this.logger.info?.(`[coclaw/rtc] [${connId}] ICE connected via ${type}`);
+				}
+			} else if (state === 'failed' || state === 'closed') {
+				this.__sessions.delete(connId);
+			}
+		};
+
+		// 监听 UI 创建的 DataChannel
+		pc.ondatachannel = ({ channel }) => {
+			this.logger.info?.(`[coclaw/rtc] [${connId}] DataChannel "${channel.label}" received`);
+			if (channel.label === 'rpc') {
+				session.rpcChannel = channel;
+				this.__setupDataChannel(connId, channel);
+			}
+		};
+
+		// offer → answer
+		try {
+			await pc.setRemoteDescription({ type: 'offer', sdp: msg.payload.sdp });
+			const answer = await pc.createAnswer();
+			await pc.setLocalDescription(answer);
+
+			this.__onSend({
+				type: 'rtc:answer',
+				toConnId: connId,
+				payload: { sdp: answer.sdp },
+			});
+			this.logger.info?.(`[coclaw/rtc] answer sent to ${connId}`);
+		} catch (err) {
+			// SDP 协商失败 → 清理已入 Map 的 session，避免泄漏
+			this.__sessions.delete(connId);
+			await pc.close().catch(() => {});
+			throw err;
+		}
+	}
+
+	async __handleIce(msg) {
+		const connId = msg.fromConnId;
+		const session = this.__sessions.get(connId);
+		if (!session) {
+			this.__logDebug(`ICE candidate from ${connId} but no session`);
+			return;
+		}
+		await session.pc.addIceCandidate(msg.payload);
+		this.__logDebug(`[${connId}] ICE candidate added`);
+	}
+
+	__setupDataChannel(connId, dc) {
+		dc.onopen = () => {
+			this.logger.info?.(`[coclaw/rtc] [${connId}] DataChannel "${dc.label}" opened`);
+		};
+		dc.onclose = () => {
+			this.logger.info?.(`[coclaw/rtc] [${connId}] DataChannel "${dc.label}" closed`);
+			const session = this.__sessions.get(connId);
+			if (session && dc.label === 'rpc') session.rpcChannel = null;
+		};
+		dc.onmessage = (event) => {
+			try {
+				const raw = typeof event.data === 'string' ? event.data : event.data.toString();
+				const payload = JSON.parse(raw);
+				if (payload.type === 'req') {
+					this.__onRequest?.(payload, connId);
+				} else {
+					this.__logDebug(`[${connId}] unknown DC message type: ${payload.type}`);
+				}
+			} catch (err) {
+				this.logger.warn?.(`[coclaw/rtc] [${connId}] DC message parse failed: ${err.message}`);
+			}
+		};
+	}
+
+	__logDebug(message) {
+		if (typeof this.logger?.debug === 'function') {
+			this.logger.debug(`[coclaw/rtc] ${message}`);
+		}
+	}
+}