@coclaw/openclaw-coclaw 0.6.0 → 0.6.2

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;
 
@@ -229,7 +293,10 @@ const plugin = {
 			try {
 				await waitForSessionsReady();
 				const version = await getPluginVersion();
-				respond(true, { version, capabilities: ['topics', 'chatHistory'] });
+				const rawClawVersion = api.runtime?.version;
+				// OpenClaw 打包后 resolveVersion() 路径失配导致返回 'unknown'，此时不传该字段
+				const clawVersion = (rawClawVersion && rawClawVersion !== 'unknown') ? rawClawVersion : undefined;
+				respond(true, { version, clawVersion, capabilities: ['topics', 'chatHistory'] });
 			}
 			catch (err) {
 				respondError(respond, err);
@@ -426,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) };
 					}
 
@@ -480,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coclaw/openclaw-coclaw",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "type": "module",
   "license": "Apache-2.0",
   "description": "OpenClaw CoClaw channel plugin for remote chat",

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

@@ -163,11 +163,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();
 	}
 
@@ -518,6 +522,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', () => {});
 	}
@@ -681,7 +690,7 @@ 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 {}
@@ -713,7 +722,13 @@ export class RealtimeBridge {
 			this.__closeGatewayWs();
 
 			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;
 			}