@coclaw/openclaw-coclaw 0.11.6 → 0.12.1

package/README.md

@@ -98,7 +98,7 @@ openclaw coclaw enroll [--server <url>]
 {
   "default": {
     "serverUrl": "https://coclaw.net",
-    "botId": "bot-xxx",
+    "clawId": "claw-xxx",
     "token": "token-xxx",
     "boundAt": "2026-03-05T..."
   }

package/index.js

@@ -1,4 +1,4 @@
-import { bindBot, unbindBot, enrollBot, waitForClaimAndSave } from './src/common/bot-binding.js';
+import { bindClaw, unbindClaw, enrollClaw, waitForClaimAndSave } from './src/common/claw-binding.js';
 import { registerCoclawCli } from './src/cli-registrar.js';
 import { resolveErrorMessage } from './src/common/errors.js';
 import { notBound, bindOk, unbindOk, claimCodeCreated } from './src/common/messages.js';
@@ -116,7 +116,7 @@ const plugin = {
 			await stopRealtimeBridge();
 			let result;
 			try {
-				result = await bindBot({
+				result = await bindClaw({
 					code,
 					serverUrl: serverUrl ?? api.pluginConfig?.serverUrl,
 				});
@@ -133,7 +133,7 @@ const plugin = {
 		}
 
 		async function doUnbind({ serverUrl }) {
-			const result = await unbindBot({
+			const result = await unbindClaw({
 				serverUrl: serverUrl ?? api.pluginConfig?.serverUrl,
 			});
 			await stopRealtimeBridge();
@@ -153,9 +153,9 @@ const plugin = {
 				});
 				respond(true, {
 					status: {
-						botId: result.botId,
+						clawId: result.clawId,
 						rebound: result.rebound,
-						previousBotId: result.previousBotId,
+						previousClawId: result.previousClawId,
 					},
 				});
 			}
@@ -167,7 +167,7 @@ const plugin = {
 		api.registerGatewayMethod('coclaw.unbind', async ({ params, respond }) => {
 			try {
 				const result = await doUnbind({ serverUrl: params?.serverUrl });
-				respond(true, { status: { botId: result.botId } });
+				respond(true, { status: { clawId: result.clawId } });
 			}
 			catch (err) {
 				respondError(respond, err);
@@ -187,7 +187,7 @@ const plugin = {
 				activeEnrollAbort = abortController;
 
 				const serverUrl = params?.serverUrl ?? api.pluginConfig?.serverUrl;
-				const result = await enrollBot({ serverUrl });
+				const result = await enrollClaw({ serverUrl });
 
 				const rawMinutes = Math.round(
 					(new Date(result.expiresAt).getTime() - Date.now()) / 60_000,
@@ -552,7 +552,7 @@ const plugin = {
 						activeEnrollAbort = abortController;
 
 						const serverUrl = options.server ?? api.pluginConfig?.serverUrl;
-						const result = await enrollBot({ serverUrl });
+						const result = await enrollClaw({ serverUrl });
 						const rawMinutes = Math.round(
 							(new Date(result.expiresAt).getTime() - Date.now()) / 60_000,
 						);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coclaw/openclaw-coclaw",
-  "version": "0.11.6",
+  "version": "0.12.1",
   "type": "module",
   "license": "Apache-2.0",
   "description": "OpenClaw CoClaw channel plugin for remote chat",
@@ -59,7 +59,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",
+    "node-datachannel": "0.32.2",
     "werift": "^0.19.0"
   },
   "devDependencies": {

package/src/api.js

@@ -31,7 +31,7 @@ const CLAIM_CODE_TIMEOUT = 15_000;
 const CLAIM_WAIT_TIMEOUT = 30_000;
 
 export async function bindWithServer({ baseUrl, code, name }) {
-	return requestJson(baseUrl, '/api/v1/bots/bind', {
+	return requestJson(baseUrl, '/api/v1/claws/bind', {
 		method: 'POST',
 		headers: { 'content-type': 'application/json' },
 		body: { code, name },
@@ -40,7 +40,7 @@ export async function bindWithServer({ baseUrl, code, name }) {
 }
 
 export async function unbindWithServer({ baseUrl, token, timeout = UNBIND_TIMEOUT }) {
-	return requestJson(baseUrl, '/api/v1/bots/unbind', {
+	return requestJson(baseUrl, '/api/v1/claws/unbind', {
 		method: 'POST',
 		headers: {
 			Authorization: `Bearer ${token}`,

package/src/common/{bot-binding.js → claw-binding.js}

@@ -8,14 +8,14 @@ function resolveServerUrl(serverUrl) {
 	return serverUrl ?? process.env.COCLAW_SERVER_URL ?? DEFAULT_SERVER_URL;
 }
 
-// 这些 HTTP 状态码表示 bot 在 server 端已不存在，视为解绑成功
+// 这些 HTTP 状态码表示 claw 在 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 = {}) {
+export async function bindClaw({ code, serverUrl }, deps = {}) {
 	const {
 		readCfg = readConfig,
 		clearCfg = clearConfig,
@@ -30,10 +30,10 @@ export async function bindBot({ code, serverUrl }, deps = {}) {
 
 	const config = await readCfg();
 
-	// 已绑定时必须先解绑旧 bot，避免产生孤儿记录
-	let previousBotId;
+	// 已绑定时必须先解绑旧 claw，避免产生孤儿记录
+	let previousClawId;
 	if (config?.token) {
-		previousBotId = config.botId || 'unknown';
+		previousClawId = config.clawId || 'unknown';
 		const oldBaseUrl = config.serverUrl;
 		if (oldBaseUrl) {
 			try {
@@ -41,7 +41,7 @@ export async function bindBot({ code, serverUrl }, deps = {}) {
 			} catch (err) {
 				if (!isAlreadyUnbound(err)) {
 					const rebindErr = new Error(
-						`Failed to unbind previous bot (${previousBotId}): ${err.message}. ` +
+						`Failed to unbind previous claw (${previousClawId}): ${err.message}. ` +
 						'Unbind manually first, then retry.',
 					);
 					rebindErr.code = 'UNBIND_FAILED';
@@ -59,25 +59,25 @@ export async function bindBot({ code, serverUrl }, deps = {}) {
 		code,
 	});
 
-	if (!data?.botId || !data?.token) {
+	if (!data?.clawId || !data?.token) {
 		throw new Error('invalid bind response');
 	}
 
 	await writeCfg({
 		serverUrl: baseUrl,
-		botId: data.botId,
+		clawId: data.clawId,
 		token: data.token,
 		boundAt: new Date().toISOString(),
 	});
 
 	return {
-		botId: data.botId,
+		clawId: data.clawId,
 		rebound: Boolean(data.rebound),
-		previousBotId,
+		previousClawId,
 	};
 }
 
-export async function enrollBot({ serverUrl }, deps = {}) {
+export async function enrollClaw({ serverUrl }, deps = {}) {
 	const { createClaimCode = createClaimCodeOnServer, readCfg = readConfig } = deps;
 
 	const config = await readCfg();
@@ -129,14 +129,14 @@ export async function waitForClaimAndSave({ serverUrl, code, waitToken, signal }
 		}
 
 		// 已认领
-		if (data?.botId && data?.token) {
+		if (data?.clawId && data?.token) {
 			await writeCfg({
 				serverUrl: baseUrl,
-				botId: data.botId,
+				clawId: data.clawId,
 				token: data.token,
 				boundAt: new Date().toISOString(),
 			});
-			return { botId: data.botId };
+			return { clawId: data.clawId };
 		}
 
 		// PENDING — 延迟后继续轮询
@@ -150,7 +150,7 @@ export async function waitForClaimAndSave({ serverUrl, code, waitToken, signal }
 	}
 }
 
-export async function unbindBot({ serverUrl }, deps = {}) {
+export async function unbindClaw({ serverUrl }, deps = {}) {
 	const {
 		readCfg = readConfig,
 		clearCfg = clearConfig,
@@ -170,7 +170,7 @@ export async function unbindBot({ serverUrl }, deps = {}) {
 		try {
 			await unbindServer({ baseUrl, token: config.token });
 		} catch (err) {
-			// bot 在 server 已不存在 — 视为解绑成功，继续清理本地
+			// claw 在 server 已不存在 — 视为解绑成功，继续清理本地
 			if (!isAlreadyUnbound(err)) {
 				throw err;
 			}
@@ -179,5 +179,5 @@ export async function unbindBot({ serverUrl }, deps = {}) {
 
 	await clearCfg();
 
-	return { botId: config.botId };
+	return { clawId: config.clawId };
 }

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: 'Claw is blocked, please contact the admin',
+	CLAW_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

@@ -1,15 +1,15 @@
 // bind/unbind CLI 及 command 的用户提示文案（统一出口）
 
-export function bindOk({ botId, rebound, previousBotId }) {
+export function bindOk({ clawId, rebound, previousClawId }) {
 	const action = rebound ? 're-bound' : 'bound';
-	const prev = previousBotId
-		? ` (previous Claw ${previousBotId} was auto-unbound)`
+	const prev = previousClawId
+		? ` (previous Claw ${previousClawId} was auto-unbound)`
 		: '';
-	return `OK. Claw (${botId}) ${action} to CoClaw.${prev}`;
+	return `OK. Claw (${clawId}) ${action} to CoClaw.${prev}`;
 }
 
-export function unbindOk({ botId }) {
-	const id = botId ?? 'unknown';
+export function unbindOk({ clawId }) {
+	const id = clawId ?? 'unknown';
 	return `OK. Claw (${id}) unbound from CoClaw.`;
 }
 

package/src/config.js

@@ -58,7 +58,12 @@ const bindingsMutex = createMutex();
 export async function readConfig(accountId = DEFAULT_ACCOUNT_ID) {
 	const bindingsPath = getBindingsPath();
 	const bindings = await readJson(bindingsPath);
-	return toRecord(bindings[accountId]);
+	const record = toRecord(bindings[accountId]);
+	// 向后兼容：旧 bindings.json 使用 botId，映射到 clawId
+	if (record.botId && !record.clawId) {
+		record.clawId = record.botId;
+	}
+	return record;
 }
 
 export async function writeConfig(nextConfig, accountId = DEFAULT_ACCOUNT_ID) {
@@ -69,7 +74,7 @@ export async function writeConfig(nextConfig, accountId = DEFAULT_ACCOUNT_ID) {
 
 		const next = { ...current };
 		if (nextConfig.serverUrl !== undefined) next.serverUrl = nextConfig.serverUrl;
-		if (nextConfig.botId !== undefined) next.botId = nextConfig.botId;
+		if (nextConfig.clawId !== undefined) next.clawId = nextConfig.clawId;
 		if (nextConfig.token !== undefined) next.token = nextConfig.token;
 		if (nextConfig.boundAt !== undefined) next.boundAt = nextConfig.boundAt;
 

package/src/file-manager/handler.js

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import fsp from 'node:fs/promises';
 import nodePath from 'node:path';
 import { randomUUID, randomBytes } from 'node:crypto';
+import { remoteLog } from '../remote-log.js';
 
 // --- 常量 ---
 
@@ -312,8 +313,9 @@ export function createFileHandler({ resolveWorkspace, logger, deps = {} }) {
 	/**
 	 * 处理 file:<transferId> DataChannel
 	 * @param {object} dc - werift DataChannel
+	 * @param {string} [connId] - 所属 PeerConnection 的连接 ID
 	 */
-	function handleFileChannel(dc) {
+	function handleFileChannel(dc, connId) {
 		let requestTimer = setTimeout(() => {
 			try {
 				dc.send(JSON.stringify({
@@ -353,12 +355,12 @@ export function createFileHandler({ resolveWorkspace, logger, deps = {} }) {
 				});
 			} else if (req.method === 'PUT') {
 				/* c8 ignore next 3 -- handlePut 内部已完整处理异常，此 catch 纯防御 */
-				handlePut(dc, req).catch((err) => {
+				handlePut(dc, req, connId).catch((err) => {
 					log.warn?.(`[coclaw/file] PUT error: ${err.message}`);
 				});
 			} else if (req.method === 'POST') {
 				/* c8 ignore next 3 -- handlePost 内部已完整处理异常，此 catch 纯防御 */
-				handlePost(dc, req).catch((err) => {
+				handlePost(dc, req, connId).catch((err) => {
 					log.warn?.(`[coclaw/file] POST error: ${err.message}`);
 				});
 			} else {
@@ -456,7 +458,7 @@ export function createFileHandler({ resolveWorkspace, logger, deps = {} }) {
 		});
 	}
 
-	async function handlePut(dc, req) {
+	async function handlePut(dc, req, connId) {
 		let workspaceDir, resolved;
 		try {
 			const agentId = req.agentId?.trim?.() || 'main';
@@ -466,10 +468,10 @@ export function createFileHandler({ resolveWorkspace, logger, deps = {} }) {
 			sendError(dc, err.code ?? 'INTERNAL_ERROR', err.message);
 			return;
 		}
-		await receiveUpload(dc, req, resolved);
+		await receiveUpload(dc, req, resolved, undefined, connId);
 	}
 
-	async function handlePost(dc, req) {
+	async function handlePost(dc, req, connId) {
 		let workspaceDir, dirResolved;
 		try {
 			const agentId = req.agentId?.trim?.() || 'main';
@@ -508,7 +510,7 @@ export function createFileHandler({ resolveWorkspace, logger, deps = {} }) {
 		const resolved = nodePath.join(dirResolved, uniqueName);
 		// 计算相对于 workspace 的路径，作为响应中的 path
 		const relativePath = nodePath.relative(workspaceDir, resolved);
-		await receiveUpload(dc, req, resolved, relativePath);
+		await receiveUpload(dc, req, resolved, relativePath, connId);
 	}
 
 	/**
@@ -517,8 +519,9 @@ export function createFileHandler({ resolveWorkspace, logger, deps = {} }) {
 	 * @param {object} req - 请求对象（含 size）
 	 * @param {string} resolved - 目标文件绝对路径
 	 * @param {string} [relativePath] - POST 时附带的相对路径（响应中返回）
+	 * @param {string} [connId] - 所属连接 ID
 	 */
-	async function receiveUpload(dc, req, resolved, relativePath) {
+	async function receiveUpload(dc, req, resolved, relativePath, connId) {
 		const declaredSize = req.size;
 		if (!Number.isFinite(declaredSize) || declaredSize < 0) {
 			sendError(dc, 'INVALID_INPUT', 'size must be a non-negative number');
@@ -550,6 +553,12 @@ export function createFileHandler({ resolveWorkspace, logger, deps = {} }) {
 			return;
 		}
 
+		const logTag = connId ? `conn=${connId} ` : '';
+		remoteLog(`file.up.start ${logTag}id=${transferId} method=${req.method} size=${declaredSize}`);
+		const startTime = Date.now();
+		let nextLogAt = declaredSize > 0 ? Math.floor(declaredSize * 0.25) : Infinity;
+		let logStep = 1; // 25% → 50% → 75%
+
 		// 发送就绪信号
 		try {
 			dc.send(JSON.stringify({ ok: true }));
@@ -557,12 +566,110 @@ export function createFileHandler({ resolveWorkspace, logger, deps = {} }) {
 			// WriteStream 可能尚未完成文件创建，等 close 后再清理
 			ws.on('close', () => safeUnlink(tmpPath));
 			ws.destroy();
+			remoteLog(`file.up.abort ${logTag}id=${transferId} reason=dc-send-failed`);
 			return;
 		}
 
 		let receivedBytes = 0;
 		let doneReceived = false;
 		let dcClosed = false;
+		let wsBackpressureCount = 0;
+		let wsError = false;
+		let finishing = false;
+
+		// --- 受控写入：中间缓冲 + drain 循环 ---
+		const pendingQueue = [];
+		let draining = false;
+
+		function scheduleDrain() {
+			if (draining) return;
+			draining = true;
+			setImmediate(drainLoop);
+		}
+
+		function drainLoop() {
+			if (wsError || dcClosed) { draining = false; return; }
+			const chunk = pendingQueue.shift();
+			if (!chunk) {
+				draining = false;
+				// 队列排空且已收到 done → 结束写入
+				if (doneReceived) finishUpload();
+				return;
+			}
+			let ok;
+			try {
+				ok = ws.write(chunk);
+			} catch (err) {
+				// ws 可能已被销毁（如 SIZE_EXCEEDED 路径竞态），防止 gateway 崩溃
+				wsError = true;
+				draining = false;
+				pendingQueue.length = 0;
+				log.warn?.(`[coclaw/file] drainLoop write error: ${err.message}`);
+				ws.destroy();
+				if (!dcClosed) sendError(dc, 'WRITE_FAILED', err.message);
+				safeUnlink(tmpPath);
+				const elapsed = Date.now() - startTime;
+				remoteLog(`file.up.fail ${logTag}id=${transferId} reason=drain-write-error err=${err.message} received=${receivedBytes}/${declaredSize} elapsed=${elapsed}ms`);
+				return;
+			}
+			if (!ok) {
+				wsBackpressureCount++;
+				// 等待 drain 事件后再继续（尊重磁盘 I/O 速度）
+				ws.once('drain', () => setImmediate(drainLoop));
+			} else {
+				// 每次写入后让出 CPU，防止事件循环饥饿
+				setImmediate(drainLoop);
+			}
+		}
+
+		function finishUpload() {
+			if (finishing) return;
+			finishing = true;
+			ws.end(async () => {
+				const elapsed = Date.now() - startTime;
+				if (dcClosed) {
+					safeUnlink(tmpPath);
+					remoteLog(`file.up.fail ${logTag}id=${transferId} reason=dc-closed-before-flush received=${receivedBytes}/${declaredSize} elapsed=${elapsed}ms bp=${wsBackpressureCount}`);
+					return;
+				}
+				const valid = receivedBytes === declaredSize;
+				if (!valid) {
+					try {
+						dc.send(JSON.stringify({ ok: false, error: { code: 'WRITE_FAILED', message: `Size mismatch: expected ${declaredSize}, got ${receivedBytes}` } }));
+					/* c8 ignore next */
+					} catch { /* ignore */ }
+					safeUnlink(tmpPath);
+					/* c8 ignore next */
+					try { dc.close(); } catch { /* ignore */ }
+					remoteLog(`file.up.fail ${logTag}id=${transferId} reason=size-mismatch expected=${declaredSize} got=${receivedBytes} elapsed=${elapsed}ms`);
+					return;
+				}
+				// 先 rename，再发成功响应（避免 rename 失败时 UI 误认为成功）
+				try {
+					await _rename(tmpPath, resolved);
+				} catch (renameErr) {
+					log.warn?.(`[coclaw/file] rename failed: ${renameErr.message}`);
+					/* c8 ignore next 3 -- dc.send/close 失败属罕见竞态 */
+					try {
+						dc.send(JSON.stringify({ ok: false, error: { code: 'WRITE_FAILED', message: `rename failed: ${renameErr.message}` } }));
+					} catch { /* ignore */ }
+					safeUnlink(tmpPath);
+					/* c8 ignore next */
+					try { dc.close(); } catch { /* ignore */ }
+					remoteLog(`file.up.fail ${logTag}id=${transferId} reason=rename-failed elapsed=${elapsed}ms`);
+					return;
+				}
+				const result = { ok: true, bytes: receivedBytes };
+				if (relativePath) result.path = relativePath;
+				try {
+					dc.send(JSON.stringify(result));
+				/* c8 ignore next */
+				} catch { /* ignore */ }
+				/* c8 ignore next */
+				try { dc.close(); } catch { /* ignore */ }
+				remoteLog(`file.up.ok ${logTag}id=${transferId} bytes=${receivedBytes} elapsed=${elapsed}ms bp=${wsBackpressureCount}`);
+			});
+		}
 
 		// 替换原始 onmessage（文件传输模式）
 		dc.onmessage = (event) => {
@@ -571,54 +678,19 @@ export function createFileHandler({ resolveWorkspace, logger, deps = {} }) {
 				try { msg = JSON.parse(event.data); } catch { return; }
 				if (msg.done) {
 					doneReceived = true;
-					ws.end(async () => {
-						if (dcClosed) {
-							safeUnlink(tmpPath);
-							return;
-						}
-						const valid = receivedBytes === declaredSize;
-						if (!valid) {
-							try {
-								dc.send(JSON.stringify({ ok: false, error: { code: 'WRITE_FAILED', message: `Size mismatch: expected ${declaredSize}, got ${receivedBytes}` } }));
-							/* c8 ignore next */
-							} catch { /* ignore */ }
-							safeUnlink(tmpPath);
-							/* c8 ignore next */
-							try { dc.close(); } catch { /* ignore */ }
-							return;
-						}
-						// 先 rename，再发成功响应（避免 rename 失败时 UI 误认为成功）
-						try {
-							await _rename(tmpPath, resolved);
-						} catch (renameErr) {
-							log.warn?.(`[coclaw/file] rename failed: ${renameErr.message}`);
-							/* c8 ignore next 3 -- dc.send/close 失败属罕见竞态 */
-							try {
-								dc.send(JSON.stringify({ ok: false, error: { code: 'WRITE_FAILED', message: `rename failed: ${renameErr.message}` } }));
-							} catch { /* ignore */ }
-							safeUnlink(tmpPath);
-							/* c8 ignore next */
-							try { dc.close(); } catch { /* ignore */ }
-							return;
-						}
-						const result = { ok: true, bytes: receivedBytes };
-						if (relativePath) result.path = relativePath;
-						try {
-							dc.send(JSON.stringify(result));
-						/* c8 ignore next */
-						} catch { /* ignore */ }
-						/* c8 ignore next */
-						try { dc.close(); } catch { /* ignore */ }
-					});
+					// 队列已空则立即结束，否则等 drainLoop 排空后处理
+					if (pendingQueue.length === 0 && !draining) finishUpload();
 				}
 			} else {
-				// binary 数据帧
+				// binary 数据帧 — 入队，由 drainLoop 按节奏写入
 				const chunk = event.data;
 				const len = chunk.byteLength ?? chunk.length ?? 0;
 				receivedBytes += len;
 
 				// 接收端超限防护
 				if (receivedBytes > MAX_UPLOAD_SIZE || receivedBytes > declaredSize) {
+					wsError = true;
+					pendingQueue.length = 0;
 					ws.destroy();
 					safeUnlink(tmpPath);
 					try {
@@ -628,28 +700,50 @@ export function createFileHandler({ resolveWorkspace, logger, deps = {} }) {
 						}));
 					} catch { /* ignore */ }
 					try { dc.close(); } catch { /* ignore */ }
+					remoteLog(`file.up.reject ${logTag}id=${transferId} reason=size-exceeded received=${receivedBytes}`);
 					return;
 				}
-				ws.write(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+
+				pendingQueue.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+				scheduleDrain();
+
+				// 进度日志（25% / 50% / 75%）
+				if (receivedBytes >= nextLogAt && logStep <= 3) {
+					remoteLog(`file.up.progress ${logTag}id=${transferId} ${logStep * 25}% received=${receivedBytes}/${declaredSize} bp=${wsBackpressureCount}`);
+					logStep++;
+					nextLogAt = declaredSize > 0 ? Math.floor(declaredSize * logStep * 0.25) : Infinity;
+				}
 			}
 		};
 
 		dc.onclose = () => {
 			dcClosed = true;
-			if (!doneReceived) {
+			draining = false;
+			pendingQueue.length = 0;
+			if (doneReceived) {
+				// done 已收到但 drain 未完成 — finishUpload 中会检测 dcClosed 并清理 tmp
+				if (!finishing) finishUpload();
+			} else {
 				ws.destroy();
 				safeUnlink(tmpPath);
+				const elapsed = Date.now() - startTime;
+				remoteLog(`file.up.fail ${logTag}id=${transferId} reason=dc-closed received=${receivedBytes}/${declaredSize} elapsed=${elapsed}ms bp=${wsBackpressureCount}`);
 			}
 		};
 
 		// WriteStream 错误处理
 		ws.on('error', (err) => {
+			wsError = true;
+			draining = false;
+			pendingQueue.length = 0;
 			log.warn?.(`[coclaw/file] write stream error: ${err.message}`);
 			if (!dcClosed) {
 				const code = err.code === 'ENOSPC' ? 'DISK_FULL' : 'WRITE_FAILED';
 				sendError(dc, code, err.message);
 			}
 			safeUnlink(tmpPath);
+			const elapsed = Date.now() - startTime;
+			remoteLog(`file.up.fail ${logTag}id=${transferId} reason=write-error err=${err.code || err.message} received=${receivedBytes}/${declaredSize} elapsed=${elapsed}ms`);
 		});
 	}
 

package/src/realtime-bridge.js

@@ -24,7 +24,7 @@ const SERVER_HB_MAX_MISS = 4; // 连续 4 次无响应才断连（~3 分钟）
 function toServerWsUrl(baseUrl, token) {
 	const url = new URL(baseUrl);
 	url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
-	url.pathname = '/api/v1/bots/stream';
+	url.pathname = '/api/v1/claws/stream';
 	url.searchParams.set('token', token);
 	return url.toString();
 }
@@ -176,13 +176,13 @@ export class RealtimeBridge {
 			?? DEFAULT_GATEWAY_WS_URL;
 	}
 
-	async __clearTokenLocal(unboundBotId) {
+	async __clearTokenLocal(unboundClawId) {
 		const cfg = await this.__readConfig();
 		if (!cfg?.token) {
 			return;
 		}
-		// 只清除匹配的 bot，避免新绑定被误清
-		if (unboundBotId && cfg.botId && cfg.botId !== unboundBotId) {
+		// 只清除匹配的 claw，避免新绑定被误清
+		if (unboundClawId && cfg.clawId && cfg.clawId !== unboundClawId) {
 			return;
 		}
 		await this.__clearConfig();
@@ -232,8 +232,8 @@ export class RealtimeBridge {
 				this.__fileHandler.handleRpcRequest(payload, sendFn)
 					.catch((err) => this.logger.warn?.(`[coclaw/file] rpc error: ${err.message}`));
 			},
-			onFileChannel: (dc) => {
-				this.__fileHandler.handleFileChannel(dc);
+			onFileChannel: (dc, connId) => {
+				this.__fileHandler.handleFileChannel(dc, connId);
 			},
 			PeerConnection,
 			logger: this.logger,
@@ -824,10 +824,10 @@ export class RealtimeBridge {
 			this.__resetServerHbTimeout(sock);
 			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'); }
+				if (payload?.type === 'claw.unbound') {
+					remoteLog('ws.claw-unbound');
+					await this.__clearTokenLocal(payload.clawId);
+					try { sock.close(4001, 'claw_unbound'); }
 					/* c8 ignore next */
 					catch {}
 					return;
@@ -994,7 +994,7 @@ export class RealtimeBridge {
 		if (sock) {
 			this.intentionallyClosed = true;
 			this.serverWs = null;
-			// 等待 WebSocket 真正关闭，避免残留连接收到 bot.unbound 等消息
+			// 等待 WebSocket 真正关闭，避免残留连接收到 claw.unbound 等消息
 			/* c8 ignore next -- readyState === 3 时跳过 */
 			if (sock.readyState === 3) return;
 			await new Promise((resolve) => {