@coclaw/openclaw-coclaw 0.5.2 → 0.6.0

package/README.md

@@ -69,9 +69,11 @@ pnpm run release:versions                  # 显示所有已发布版本
 ```bash
 openclaw coclaw bind <binding-code> [--server <url>]
 openclaw coclaw unbind [--server <url>]
+openclaw coclaw enroll [--server <url>]
 ```
 
-bind/unbind 成功后会通过 gateway RPC 通知插件刷新/停止 bridge 连接（无需重启 gateway）。若 gateway 未运行，通知会失败但不影响绑定结果。
+- bind/unbind 成功后会通过 gateway RPC 通知插件刷新/停止 bridge 连接（无需重启 gateway）。若 gateway 未运行，通知会失败但不影响绑定结果。
+- enroll 由 OpenClaw 侧主动发起，生成认领码和链接供用户点击完成绑定。已绑定时需先 unbind 再发起。
 
 ### 方式二：IM 渠道命令
 
@@ -80,6 +82,7 @@ bind/unbind 成功后会通过 gateway RPC 通知插件刷新/停止 bridge 连
 ```
 /coclaw bind <binding-code> [--server <url>]
 /coclaw unbind [--server <url>]
+/coclaw enroll [--server <url>]
 ```
 
 需要 gateway 运行中。

package/index.js

@@ -1,10 +1,10 @@
 import fs from 'node:fs/promises';
 import nodePath from 'node:path';
 
-import { bindBot, unbindBot } from './src/common/bot-binding.js';
+import { bindBot, unbindBot, enrollBot, waitForClaimAndSave } from './src/common/bot-binding.js';
 import { registerCoclawCli } from './src/cli-registrar.js';
 import { resolveErrorMessage } from './src/common/errors.js';
-import { notBound, bindOk, unbindOk } from './src/common/messages.js';
+import { notBound, bindOk, unbindOk, claimCodeCreated } from './src/common/messages.js';
 import { coclawChannelPlugin } from './src/channel-plugin.js';
 import { ensureAgentSession, gatewayAgentRpc, restartRealtimeBridge, stopRealtimeBridge, waitForSessionsReady } from './src/realtime-bridge.js';
 import { setRuntime } from './src/runtime.js';
@@ -59,16 +59,22 @@ function buildHelpText() {
 		'',
 		'/coclaw bind <binding-code> [--server <url>]',
 		'/coclaw unbind [--server <url>]',
+		'/coclaw enroll [--server <url>]',
 	].join('\n');
 }
 
 function respondError(respond, err) {
-	respond(false, {
+	respond(false, undefined, {
+		code: err?.code ?? 'INTERNAL_ERROR',
 		/* c8 ignore next */
-		error: String(err?.message ?? err),
+		message: String(err?.message ?? err),
 	});
 }
 
+function respondInvalid(respond, message) {
+	respond(false, undefined, { code: 'INVALID_INPUT', message });
+}
+
 /* c8 ignore start */
 const plugin = {
 	id: 'openclaw-coclaw',
@@ -143,6 +149,60 @@ const plugin = {
 			}
 		});
 
+		// enroll 并发控制：同一时刻只允许一个活跃 enroll
+		let activeEnrollAbort = null;
+
+		api.registerGatewayMethod('coclaw.enroll', async ({ params, respond }) => {
+			try {
+				// 取消前一个 enroll
+				if (activeEnrollAbort) {
+					activeEnrollAbort.abort();
+				}
+				const abortController = new AbortController();
+				activeEnrollAbort = abortController;
+
+				const serverUrl = params?.serverUrl ?? api.pluginConfig?.serverUrl;
+				const result = await enrollBot({ serverUrl });
+
+				const rawMinutes = Math.round(
+					(new Date(result.expiresAt).getTime() - Date.now()) / 60_000,
+				);
+				const expiresMinutes = Number.isFinite(rawMinutes) ? rawMinutes : 30;
+
+				// 立即返回认领码给 CLI
+				respond(true, {
+					status: {
+						code: result.code,
+						appUrl: result.appUrl,
+						expiresAt: result.expiresAt,
+						expiresMinutes,
+					},
+				});
+
+				// 后台 fire-and-forget：等待认领并保存 config + 启 bridge
+				waitForClaimAndSave({
+					serverUrl: result.serverUrl,
+					code: result.code,
+					waitToken: result.waitToken,
+					signal: abortController.signal,
+				}).then(async () => {
+					if (abortController.signal.aborted) return;
+					await restartRealtimeBridge({ logger, pluginConfig: api.pluginConfig });
+					logger.info?.('[coclaw] enroll completed, bridge restarted');
+				}).catch((err) => {
+					if (abortController.signal.aborted) return;
+					logger.warn?.(`[coclaw] enroll wait failed: ${String(err?.message ?? err)}`);
+				}).finally(() => {
+					if (activeEnrollAbort === abortController) {
+						activeEnrollAbort = null;
+					}
+				});
+			}
+			catch (err) {
+				respondError(respond, err);
+			}
+		});
+
 		api.registerGatewayMethod('nativeui.sessions.listAll', async ({ params, respond }) => {
 			try {
 				const agentId = params?.agentId?.trim?.() || 'main';
@@ -208,7 +268,7 @@ const plugin = {
 			try {
 				const topicId = params?.topicId?.trim?.();
 				if (!topicId) {
-					respond(false, { error: 'topicId required' });
+					respondInvalid(respond, 'topicId required');
 					return;
 				}
 				respond(true, topicManager.get({ topicId }));
@@ -222,7 +282,7 @@ const plugin = {
 			try {
 				const topicId = params?.topicId?.trim?.();
 				if (!topicId) {
-					respond(false, { error: 'topicId required' });
+					respondInvalid(respond, 'topicId required');
 					return;
 				}
 				const agentId = params?.agentId?.trim?.() || 'main';
@@ -238,23 +298,23 @@ const plugin = {
 			try {
 				const topicId = params?.topicId?.trim?.();
 				if (!topicId) {
-					respond(false, { error: 'topicId required' });
+					respondInvalid(respond, 'topicId required');
 					return;
 				}
 				const changes = params?.changes;
 				if (!changes || typeof changes !== 'object') {
-					respond(false, { error: 'changes required' });
+					respondInvalid(respond, 'changes required');
 					return;
 				}
 				// 当前版本仅处理 title
 				if (typeof changes.title !== 'string') {
-					respond(false, { error: 'No valid change field provided (supported: title)' });
+					respondInvalid(respond, 'No valid change field provided (supported: title)');
 					return;
 				}
 				await topicManager.updateTitle({ topicId, title: changes.title });
 				const { topic } = topicManager.get({ topicId });
 				if (!topic) {
-					respond(false, { error: `Topic not found: ${topicId}` });
+					respondInvalid(respond, `Topic not found: ${topicId}`);
 					return;
 				}
 				respond(true, { topic });
@@ -268,7 +328,7 @@ const plugin = {
 			try {
 				const topicId = params?.topicId?.trim?.();
 				if (!topicId) {
-					respond(false, { error: 'topicId required' });
+					respondInvalid(respond, 'topicId required');
 					return;
 				}
 				const result = await generateTitle({
@@ -288,7 +348,7 @@ const plugin = {
 			try {
 				const topicId = params?.topicId?.trim?.();
 				if (!topicId) {
-					respond(false, { error: 'topicId required' });
+					respondInvalid(respond, 'topicId required');
 					return;
 				}
 				const result = await topicManager.delete({ topicId });
@@ -304,7 +364,7 @@ const plugin = {
 				const agentId = params?.agentId?.trim?.() || 'main';
 				const sessionKey = params?.sessionKey?.trim?.();
 				if (!sessionKey) {
-					respond(false, { error: 'sessionKey required' });
+					respondInvalid(respond, 'sessionKey required');
 					return;
 				}
 				if (!chatHistoryManager.__cache.has(agentId)) {
@@ -323,7 +383,7 @@ const plugin = {
 			try {
 				const sessionId = params?.sessionId?.trim?.();
 				if (!sessionId) {
-					respond(false, { error: 'sessionId required' });
+					respondInvalid(respond, 'sessionId required');
 					return;
 				}
 				const agentId = params?.agentId?.trim?.() || 'main';
@@ -376,6 +436,49 @@ const plugin = {
 						return { text: bindOk(result) };
 					}
 
+					if (action === 'enroll') {
+						// 并发控制：取消前一个 enroll（与 RPC 路径共享）
+						if (activeEnrollAbort) {
+							activeEnrollAbort.abort();
+						}
+						const abortController = new AbortController();
+						activeEnrollAbort = abortController;
+
+						const serverUrl = options.server ?? api.pluginConfig?.serverUrl;
+						const result = await enrollBot({ serverUrl });
+						const rawMinutes = Math.round(
+							(new Date(result.expiresAt).getTime() - Date.now()) / 60_000,
+						);
+						const expiresMinutes = Number.isFinite(rawMinutes) ? rawMinutes : 30;
+
+						// 后台 fire-and-forget：等待认领完成后写 config + 启 bridge
+						waitForClaimAndSave({
+							serverUrl: result.serverUrl,
+							code: result.code,
+							waitToken: result.waitToken,
+							signal: abortController.signal,
+						}).then(async () => {
+							if (abortController.signal.aborted) return;
+							await restartRealtimeBridge({ logger, pluginConfig: api.pluginConfig });
+							logger.info?.('[coclaw] enroll completed via slash command, bridge restarted');
+						}).catch((err) => {
+							if (abortController.signal.aborted) return;
+							logger.warn?.(`[coclaw] enroll wait failed: ${String(err?.message ?? err)}`);
+						}).finally(() => {
+							if (activeEnrollAbort === abortController) {
+								activeEnrollAbort = null;
+							}
+						});
+
+						return {
+							text: claimCodeCreated({
+								code: result.code,
+								appUrl: result.appUrl,
+								expiresMinutes,
+							}),
+						};
+					}
+
 					if (action === 'unbind') {
 						const result = await unbindBot({ serverUrl: options.server });
 						await stopRealtimeBridge();

package/package.json

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

package/src/api.js

@@ -27,6 +27,8 @@ async function requestJson(baseUrl, path, { method = 'GET', headers, body, timeo
 
 const BIND_TIMEOUT = 30_000;
 const UNBIND_TIMEOUT = 15_000;
+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', {
@@ -47,3 +49,20 @@ export async function unbindWithServer({ baseUrl, token, timeout = UNBIND_TIMEOU
 	});
 }
 
+export async function createClaimCodeOnServer({ baseUrl, timeout = CLAIM_CODE_TIMEOUT }) {
+	return requestJson(baseUrl, '/api/v1/claws/claim-codes', {
+		method: 'POST',
+		headers: { 'content-type': 'application/json' },
+		timeout,
+	});
+}
+
+export async function waitClaimCodeOnServer({ baseUrl, code, waitToken, timeout = CLAIM_WAIT_TIMEOUT }) {
+	return requestJson(baseUrl, '/api/v1/claws/claim-codes/wait', {
+		method: 'POST',
+		headers: { 'content-type': 'application/json' },
+		body: { code, waitToken },
+		timeout,
+	});
+}
+

package/src/cli-registrar.js

@@ -4,8 +4,45 @@ import { callGatewayMethod } from './common/gateway-notify.js';
 import {
 	notBound, bindOk, unbindOk,
 	gatewayNotified, gatewayNotifyFailed,
+	claimCodeCreated,
 } from './common/messages.js';
 
+/**
+ * 从 `openclaw gateway call` stderr 中提取核心错误信息
+ * stderr 格式：`Gateway call failed: GatewayClientRequestError: <message>`
+ */
+function extractRpcErrorMessage(raw) {
+	if (!raw) return '';
+	const match = raw.match(/GatewayClientRequestError:\s*(.+)/);
+	return match ? match[1].trim() : raw;
+}
+
+const GATEWAY_UNAVAILABLE_ERRORS = new Set([
+	'spawn_error', 'spawn_failed', 'timeout', 'empty_output',
+]);
+
+function isGatewayUnavailable(result) {
+	// exit_code_* 不视为 gateway 不可用：进程已启动成功，非零退出通常是业务错误
+	return !result.ok && GATEWAY_UNAVAILABLE_ERRORS.has(result.error);
+}
+
+/* c8 ignore start -- 集成级函数，测试通过 deps.restartGateway 注入替代 */
+async function restartGatewayProcess(spawnFn) {
+	const { spawn: nodeSpawn } = await import('node:child_process');
+	const doSpawn = spawnFn ?? nodeSpawn;
+	await new Promise((resolve, reject) => {
+		const child = doSpawn('openclaw', ['gateway', 'restart'], {
+			stdio: 'ignore',
+			shell: process.platform === 'win32',
+		});
+		child.on('close', (exitCode) => exitCode === 0 ? resolve() : reject(new Error(`exit ${exitCode}`)));
+		child.on('error', reject);
+	});
+	// 等待 gateway 就绪
+	await new Promise((r) => setTimeout(r, 3000));
+}
+/* c8 ignore stop */
+
 function resolveServerUrl(opts, config) {
 	return opts?.server
 		?? config?.plugins?.entries?.['openclaw-coclaw']?.config?.serverUrl
@@ -60,6 +97,61 @@ export function registerCoclawCli({ program, config, logger }, deps = {}) {
 			}
 		});
 
+	coclaw
+		.command('enroll')
+		.description('Enroll this OpenClaw instance 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();
+				}
+
+				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;
+					return;
+				}
+
+				// RPC 成功：输出认领码信息
+				// gateway method 的 respond 数据包含 status 字段
+				const data = result.status;
+				if (data?.code && data?.appUrl) {
+					console.log(claimCodeCreated({
+						code: data.code,
+						appUrl: data.appUrl,
+						expiresMinutes: data.expiresMinutes ?? 30,
+					}));
+				} else {
+					console.log('Enroll request sent to gateway.');
+				}
+			}
+			/* c8 ignore next 4 -- callGatewayMethod 不会抛异常，纯防御 */
+			catch (err) {
+				console.error(`Error: ${resolveErrorMessage(err)}`);
+				process.exitCode = 1;
+			}
+		});
+
 	coclaw
 		.command('unbind')
 		.description('Unbind this OpenClaw instance from CoClaw')

package/src/common/bot-binding.js

@@ -1,8 +1,13 @@
-import { bindWithServer, unbindWithServer } from '../api.js';
+import { bindWithServer, unbindWithServer, createClaimCodeOnServer, waitClaimCodeOnServer } from '../api.js';
 import { clearConfig, readConfig, writeConfig } from '../config.js';
 
 const DEFAULT_SERVER_URL = 'https://im.coclaw.net';
 
+function resolveServerUrl(serverUrl) {
+	/* c8 ignore next */
+	return serverUrl ?? process.env.COCLAW_SERVER_URL ?? DEFAULT_SERVER_URL;
+}
+
 export async function bindBot({ code, serverUrl }) {
 	if (!code) {
 		throw new Error('binding code is required');
@@ -50,6 +55,79 @@ export async function bindBot({ code, serverUrl }) {
 	};
 }
 
+export async function enrollBot({ serverUrl }, deps = {}) {
+	const { createClaimCode = createClaimCodeOnServer, readCfg = readConfig } = deps;
+
+	const config = await readCfg();
+	if (config?.token) {
+		const err = new Error('Already bound. Run `openclaw coclaw unbind` to unbind first, then retry.');
+		err.code = 'ALREADY_BOUND';
+		throw err;
+	}
+
+	const baseUrl = resolveServerUrl(serverUrl);
+	const data = await createClaimCode({ baseUrl });
+
+	if (!data?.code || !data?.waitToken) {
+		throw new Error('invalid enroll response');
+	}
+
+	const appUrl = `${baseUrl}/claim?code=${data.code}`;
+	return {
+		code: data.code,
+		expiresAt: data.expiresAt,
+		waitToken: data.waitToken,
+		appUrl,
+		serverUrl: baseUrl,
+	};
+}
+
+export async function waitForClaimAndSave({ serverUrl, code, waitToken, signal }, deps = {}) {
+	const { waitClaimCode = waitClaimCodeOnServer, writeCfg = writeConfig, retryDelayMs = 2000 } = deps;
+	const baseUrl = resolveServerUrl(serverUrl);
+
+	// 循环长轮询，直到成功或超时
+	for (;;) {
+		if (signal?.aborted) {
+			throw new Error('enroll cancelled');
+		}
+
+		let data;
+		try {
+			data = await waitClaimCode({ baseUrl, code, waitToken });
+		} catch (err) {
+			// 认领码已失效 — 不可恢复，退出循环
+			if (err?.response?.status === 404) {
+				throw new Error('claim code not found or expired');
+			}
+			// 其他所有错误（HTTP 408/500、网络超时、TimeoutError 等）延迟后重试，
+			// 确保后台等待不会因瞬时故障而终止
+			await new Promise((r) => setTimeout(r, retryDelayMs));
+			continue;
+		}
+
+		// 已认领
+		if (data?.botId && data?.token) {
+			await writeCfg({
+				serverUrl: baseUrl,
+				botId: data.botId,
+				token: data.token,
+				boundAt: new Date().toISOString(),
+			});
+			return { botId: data.botId };
+		}
+
+		// PENDING — 延迟后继续轮询
+		if (data?.code === 'CLAIM_PENDING') {
+			await new Promise((r) => setTimeout(r, retryDelayMs));
+			continue;
+		}
+
+		// 其他未知状态
+		throw new Error(`unexpected claim wait response: ${JSON.stringify(data)}`);
+	}
+}
+
 export async function unbindBot({ serverUrl }) {
 	const config = await readConfig();
 	if (!config?.token) {

package/src/common/gateway-notify.js

@@ -2,6 +2,15 @@ import { spawn as nodeSpawn } from 'node:child_process';
 
 const NOTIFY_TIMEOUT_MS = 10_000;
 const KILL_DELAY_MS = 2000;
+const IS_WIN = process.platform === 'win32';
+
+/**
+ * Windows cmd.exe 下转义 JSON 字符串，使其作为单个参数传递
+ * 双引号用 \" 转义，外层包裹双引号（与 cross-spawn 策略一致）
+ */
+export function escapeJsonForCmd(json) {
+	return `"${json.replace(/"/g, '\\"')}"`;
+}
 
 /**
  * 通过 spawn 调用 `openclaw gateway call <method> --json`
@@ -27,9 +36,16 @@ export function callGatewayMethod(method, spawnFn, opts) {
 	return new Promise((resolve) => {
 		let child;
 		try {
-			child = doSpawn('openclaw', ['gateway', 'call', method, '--json'], {
+			const isWin = opts?.isWin ?? IS_WIN;
+			const args = ['gateway', 'call', method, '--json'];
+			if (opts?.params) {
+				const json = JSON.stringify(opts.params);
+				// Windows 需 shell 解析 .cmd → 必须转义 JSON；非 Windows 不经 shell，直传
+				args.push('--params', isWin ? escapeJsonForCmd(json) : json);
+			}
+			child = doSpawn('openclaw', args, {
 				stdio: ['ignore', 'pipe', 'pipe'],
-				shell: true, // Windows 上 npm 全局安装生成 .cmd，需经 shell 解析
+				shell: isWin, // 仅 Windows 需 shell 以解析 npm 全局安装的 .cmd
 			});
 		} catch {
 			resolve({ ok: false, error: 'spawn_failed' });
@@ -37,6 +53,7 @@ export function callGatewayMethod(method, spawnFn, opts) {
 		}
 
 		let stdout = '';
+		let stderr = '';
 		let settled = false;
 		let graceTimer = null;
 		const killDelayMs = opts?.killDelayMs ?? KILL_DELAY_MS;
@@ -79,7 +96,7 @@ export function callGatewayMethod(method, spawnFn, opts) {
 			}
 		});
 
-		child.stderr?.on('data', () => {});
+		child.stderr?.on('data', (chunk) => { stderr += String(chunk); });
 
 		child.on('error', () => finish({ ok: false, error: 'spawn_error' }));
 
@@ -88,7 +105,8 @@ export function callGatewayMethod(method, spawnFn, opts) {
 			if (code === 0 || stdout.trim()) {
 				finish(parseResult());
 			} else {
-				finish({ ok: false, error: `exit_code_${code}` });
+				const stderrMsg = stderr.trim();
+				finish({ ok: false, error: `exit_code_${code}`, message: stderrMsg || undefined });
 			}
 		});
 

package/src/common/messages.js

@@ -29,3 +29,13 @@ export function gatewayNotified(action) {
 export function gatewayNotifyFailed() {
 	return 'Note: could not notify the running gateway. If it is running, restart it manually.';
 }
+
+export function claimCodeCreated({ code, appUrl, expiresMinutes }) {
+	return [
+		`Claim code: ${code}`,
+		`Open this URL to complete binding: ${appUrl}`,
+		`The code expires in ${expiresMinutes} minutes.`,
+		'',
+		"If you don't have a CoClaw account yet, you can register on that page.",
+	].join('\n');
+}