@coclaw/openclaw-coclaw 0.1.0

package/LICENSE

@@ -0,0 +1,17 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+Copyright 2026 Chengdu Gongyan Technology Co., Ltd.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,153 @@
+# @coclaw/openclaw-coclaw
+
+CoClaw 的 OpenClaw 插件（npm: `@coclaw/openclaw-coclaw`，plugin id: `openclaw-coclaw`），包含：
+
+- **transport bridge** — CoClaw server 与 OpenClaw gateway 之间的实时消息桥接
+- **session-manager** — 会话列表/读取能力（`nativeui.sessions.listAll` / `nativeui.sessions.get`）
+
+## 安装
+
+### 从 npm 安装（生产推荐）
+
+```bash
+pnpm run plugin:npm:install
+# 或手动：
+openclaw plugins install @coclaw/openclaw-coclaw
+openclaw gateway restart
+```
+
+### 本地开发安装（--link）
+
+```bash
+pnpm run plugin:dev:link
+# 或手动：
+openclaw plugins install --link /path/to/plugins/openclaw
+openclaw gateway restart
+```
+
+安装后确认：
+
+```bash
+openclaw plugins doctor
+openclaw gateway status
+```
+
+## 卸载
+
+### npm 安装的卸载
+
+```bash
+pnpm run plugin:npm:uninstall
+```
+
+### 本地开发安装的卸载
+
+```bash
+pnpm run plugin:dev:unlink
+```
+
+卸载脚本会自动清理：
+- `plugins.entries` / `plugins.installs` 等插件元数据
+- `~/.openclaw/coclaw/bindings.json`（绑定信息）
+- `openclaw.json` 中可能残留的 `channels.coclaw` 节点（旧版兼容）
+
+## 绑定 / 解绑
+
+绑定码从 CoClaw Web 端生成，有效期有限。
+
+### 方式一：OpenClaw CLI 子命令（推荐）
+
+```bash
+openclaw coclaw bind <binding-code> [--server <url>]
+openclaw coclaw unbind [--server <url>]
+```
+
+bind/unbind 成功后会通过 gateway RPC 通知插件刷新/停止 bridge 连接（无需重启 gateway）。若 gateway 未运行，通知会失败但不影响绑定结果。
+
+### 方式二：IM 渠道命令
+
+在已注册 CoClaw channel 的 IM 渠道中发送：
+
+```
+/coclaw bind <binding-code> [--server <url>]
+/coclaw unbind [--server <url>]
+```
+
+需要 gateway 运行中。
+
+### 方式三：独立 CLI（兼容）
+
+```bash
+node ~/.openclaw/extensions/openclaw-coclaw/src/cli.js bind <binding-code> --server <url>
+node ~/.openclaw/extensions/openclaw-coclaw/src/cli.js unbind --server <url>
+```
+
+## 配置存储
+
+绑定信息存储在 `~/.openclaw/coclaw/bindings.json`（通过 `resolveStateDir()` + channel ID 组合路径），**不存储在 `openclaw.json` 中**。
+
+文件结构：
+
+```json
+{
+  "default": {
+    "serverUrl": "https://coclaw.net",
+    "botId": "bot-xxx",
+    "token": "token-xxx",
+    "boundAt": "2026-03-05T..."
+  }
+}
+```
+
+说明：
+- 这一设计是为了避免卸载插件后 `channels.coclaw` 节点残留导致 OpenClaw gateway schema 验证失败。
+- `config.js` 是读写绑定信息的唯一入口。
+- 首次读取时会自动从旧位置（`openclaw.json` 的 `channels.coclaw` / `.coclaw-tunnel.json`）迁移。
+- 绑定时不提交 bot `name`；server 通过 gateway WebSocket 获取 OpenClaw 实例名。若未设置实例名，前端回退显示 `OpenClaw`。
+
+## 运行与排障日志
+
+### 日志级别建议
+
+- 默认（生产推荐）：仅保留 `info/warn`，用于连接、绑定、解绑、鉴权失败等关键事件。
+- 深度排障：开启 `COCLAW_WS_DEBUG=1`，输出 rpc/event 透传细节。
+
+### 开启 `COCLAW_WS_DEBUG`
+
+临时开启（当前 shell）：
+
+```bash
+COCLAW_WS_DEBUG=1 openclaw gateway start
+```
+
+若通过 systemd/user service 运行 gateway，可在服务环境中追加：
+
+```ini
+Environment=COCLAW_WS_DEBUG=1
+```
+
+然后重启 gateway 生效。
+
+### 常用排障命令
+
+```bash
+# 看 plugin 与 server 连接状态
+openclaw logs --limit 300 --plain | rg -n "realtime bridge|coclaw/ws|bind success|unbind success" -i
+
+# 看 gateway 握手/协议问题
+openclaw logs --limit 300 --plain | rg -n "gateway connect failed|protocol mismatch|closed before connect|auth failed" -i
+
+# 看 rpc/event 透传（需先开启 COCLAW_WS_DEBUG=1）
+openclaw logs --limit 300 --plain | rg -n "ui->server req|bot->server res|bot->server event|gateway req" -i
+```
+
+## 测试门禁
+
+```bash
+pnpm check       # lint + typecheck
+pnpm test         # 全部单测
+pnpm coverage     # 覆盖率检查
+pnpm verify       # 完整验证（check → test:standalone → test:plugin → test → coverage）
+```
+
+覆盖率阈值：100%（lines/functions/branches/statements），未通过禁止接入 gateway。

package/index.js

@@ -0,0 +1,156 @@
+import { bindBot, unbindBot } from './src/common/bot-binding.js';
+import { registerCoclawCli } from './src/cli-registrar.js';
+import { resolveErrorMessage } from './src/common/errors.js';
+import { alreadyBound, notBound, bindOk, unbindOk } from './src/common/messages.js';
+import { coclawChannelPlugin } from './src/channel-plugin.js';
+import { refreshRealtimeBridge, startRealtimeBridge, stopRealtimeBridge } from './src/realtime-bridge.js';
+import { setRuntime } from './src/runtime.js';
+import { createSessionManager } from './src/session-manager/manager.js';
+
+
+function parseCommandArgs(args) {
+	/* c8 ignore next */
+	const tokens = (args ?? '').split(/\s+/).filter(Boolean);
+	/* c8 ignore next */
+	const action = tokens[0] ?? 'help';
+	const options = {};
+	const positionals = [];
+
+	for (let i = 1; i < tokens.length; i += 1) {
+		const token = tokens[i];
+		if (token === '--server' && i + 1 < tokens.length) {
+			options.server = tokens[i + 1];
+			i += 1;
+			continue;
+		}
+		positionals.push(token);
+	}
+
+	return { action, positionals, options };
+}
+
+function buildHelpText() {
+	return [
+		'CoClaw command:',
+		'',
+		'/coclaw bind <binding-code> [--server <url>]',
+		'/coclaw unbind [--server <url>]',
+	].join('\n');
+}
+
+function respondError(respond, err) {
+	respond(false, {
+		/* c8 ignore next */
+		error: String(err?.message ?? err),
+	});
+}
+
+/* c8 ignore start */
+const plugin = {
+	id: 'openclaw-coclaw',
+	name: 'CoClaw',
+	description: 'OpenClaw CoClaw channel plugin for remote chat',
+	register(api) {
+		setRuntime(api.runtime);
+		const logger = api?.logger ?? console;
+		const manager = createSessionManager({ logger });
+
+		api.registerChannel({ plugin: coclawChannelPlugin });
+		api.registerService({
+			id: 'coclaw-realtime-bridge',
+			async start() {
+				await startRealtimeBridge({ logger, pluginConfig: api.pluginConfig });
+			},
+			async stop() {
+				await stopRealtimeBridge();
+			},
+		});
+
+		api.registerGatewayMethod('coclaw.refreshBridge', async ({ respond }) => {
+			try {
+				await refreshRealtimeBridge();
+				respond(true, { status: 'refreshed' });
+			}
+			catch (err) {
+				respondError(respond, err);
+			}
+		});
+
+		api.registerGatewayMethod('coclaw.stopBridge', async ({ respond }) => {
+			try {
+				await stopRealtimeBridge();
+				respond(true, { status: 'stopped' });
+			}
+			catch (err) {
+				respondError(respond, err);
+			}
+		});
+
+		api.registerGatewayMethod('nativeui.sessions.listAll', ({ params, respond }) => {
+			try {
+				respond(true, manager.listAll(params ?? {}));
+			}
+			catch (err) {
+				respondError(respond, err);
+			}
+		});
+
+		api.registerGatewayMethod('nativeui.sessions.get', ({ params, respond }) => {
+			try {
+				respond(true, manager.get(params ?? {}));
+			}
+			catch (err) {
+				respondError(respond, err);
+			}
+		});
+
+		api.registerCli(registerCoclawCli, { commands: ['coclaw'] });
+
+		api.registerCommand({
+			name: 'coclaw',
+			description: 'CoClaw bind/unbind command',
+			acceptsArgs: true,
+			handler: async (ctx) => {
+				const { action, positionals, options } = parseCommandArgs(ctx.args);
+				if (action === 'help') {
+					return { text: buildHelpText() };
+				}
+
+				try {
+					const serverUrl = options.server ?? api.pluginConfig?.serverUrl;
+					if (action === 'bind') {
+						const result = await bindBot({
+							code: positionals[0],
+							serverUrl,
+						});
+						await refreshRealtimeBridge();
+						return { text: bindOk(result) };
+					}
+
+					if (action === 'unbind') {
+						const result = await unbindBot({ serverUrl });
+						await stopRealtimeBridge();
+						return { text: unbindOk(result) };
+					}
+
+					return { text: buildHelpText() };
+				}
+				catch (err) {
+					if (err.code === 'ALREADY_BOUND') {
+						return { text: alreadyBound(err) };
+					}
+					if (err.code === 'NOT_BOUND') {
+						return { text: notBound() };
+					}
+					logger.warn?.(`[coclaw] command failed: ${String(err?.message ?? err)}`);
+					return {
+						text: `Error: ${resolveErrorMessage(err)}`,
+					};
+				}
+			},
+		});
+	},
+};
+/* c8 ignore stop */
+
+export default plugin;

package/openclaw.plugin.json

@@ -0,0 +1,18 @@
+{
+  "id": "openclaw-coclaw",
+  "name": "CoClaw",
+  "description": "OpenClaw CoClaw channel plugin for remote chat",
+  "channels": ["coclaw"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "serverUrl": {
+        "type": "string"
+      },
+      "gatewayWsUrl": {
+        "type": "string"
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@coclaw/openclaw-coclaw",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "Apache-2.0",
+  "description": "OpenClaw CoClaw channel plugin for remote chat",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/coclaw/coclaw.git",
+    "directory": "plugins/openclaw"
+  },
+  "homepage": "https://coclaw.net",
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "coclaw",
+    "channel",
+    "chatbot",
+    "bridge",
+    "webchat"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "files": [
+    "index.js",
+    "src/**/*.js",
+    "!src/**/*.test.js",
+    "!src/mock-server.helper.js",
+    "openclaw.plugin.json",
+    "LICENSE"
+  ],
+  "main": "index.js",
+  "openclaw": {
+    "extensions": [
+      "./index.js"
+    ]
+  },
+  "bin": {
+    "coclaw": "src/cli.js"
+  },
+  "scripts": {
+    "dev": "node src/cli.js --help",
+    "build": "echo \"TODO: build coclaw openclaw plugin\"",
+    "lint": "eslint \"**/*.{js,mjs,cjs}\" --no-error-on-unmatched-pattern",
+    "typecheck": "echo \"No typecheck configured yet (coclaw openclaw plugin)\"",
+    "check": "pnpm lint && pnpm typecheck",
+    "test:standalone": "node --test src/standalone-mode.test.js",
+    "test:plugin": "node --test src/plugin-mode.test.js",
+    "test": "node --test",
+    "coverage": "c8 --check-coverage --lines 100 --functions 100 --branches 100 --statements 100 --reporter=text --reporter=lcov node --test",
+    "verify": "pnpm check && pnpm test:standalone && pnpm test:plugin && pnpm test && pnpm coverage",
+    "pub:verify": "pnpm verify",
+    "pub:check": "npm whoami --registry=https://registry.npmjs.org/ && npm ping --registry=https://registry.npmjs.org/ && npm publish --dry-run --access public --registry=https://registry.npmjs.org/",
+    "pub:versions": "npm view @coclaw/openclaw-coclaw versions --json --registry=https://registry.npmjs.org/ && npm view @coclaw/openclaw-coclaw versions --json",
+    "pub:release": "bash ./scripts/publish-npm.sh",
+    "plugin:dev:link": "bash ./scripts/dev-link-install.sh",
+    "plugin:dev:unlink": "bash ./scripts/dev-link-uninstall.sh",
+    "plugin:npm:install": "bash ./scripts/npm-install.sh",
+    "plugin:npm:uninstall": "bash ./scripts/npm-uninstall.sh"
+  },
+  "devDependencies": {
+    "c8": "^10.1.3",
+    "eslint": "^9.39.2"
+  }
+}

package/src/api.js

@@ -0,0 +1,57 @@
+async function requestJson(baseUrl, path, { method = 'GET', headers, body } = {}) {
+	const url = new URL(path, baseUrl).toString();
+	const res = await fetch(url, {
+		method,
+		headers,
+		body: body == null ? undefined : JSON.stringify(body),
+	});
+	let data = null;
+	try {
+		data = await res.json();
+	}
+	/* c8 ignore next 3 */
+	catch {
+		data = null;
+	}
+	if (!res.ok) {
+		const err = new Error(data?.message || `HTTP ${res.status}`);
+		err.response = { status: res.status, data };
+		throw err;
+	}
+	return data;
+}
+
+export async function bindWithServer({ baseUrl, code, name }) {
+	return requestJson(baseUrl, '/api/v1/bots/bind', {
+		method: 'POST',
+		headers: { 'content-type': 'application/json' },
+		body: { code, name },
+	});
+}
+
+export async function unbindWithServer({ baseUrl, token }) {
+	return requestJson(baseUrl, '/api/v1/bots/unbind', {
+		method: 'POST',
+		headers: {
+			Authorization: `Bearer ${token}`,
+		},
+	});
+}
+
+export async function listBotsWithServer({ baseUrl, cookie }) {
+	return requestJson(baseUrl, '/api/v1/bots', {
+		headers: cookie
+			? {
+				Cookie: cookie,
+			}
+			: undefined,
+	});
+}
+
+export async function getBotSelfWithServer({ baseUrl, token }) {
+	return requestJson(baseUrl, '/api/v1/bots/self', {
+		headers: {
+			Authorization: `Bearer ${token}`,
+		},
+	});
+}

package/src/channel-plugin.js

@@ -0,0 +1,71 @@
+import { DEFAULT_ACCOUNT_ID } from './config.js';
+import { createTransportAdapter } from './transport-adapter.js';
+
+function resolveAccount(_cfg, accountId) {
+	const resolvedAccountId = accountId ?? DEFAULT_ACCOUNT_ID;
+	return {
+		accountId: resolvedAccountId,
+		enabled: true,
+		configured: true,
+		name: 'CoClaw',
+	};
+}
+
+const transport = createTransportAdapter();
+
+export const coclawChannelPlugin = {
+	id: 'coclaw',
+	meta: {
+		id: 'coclaw',
+		label: 'CoClaw',
+		selectionLabel: 'CoClaw',
+		docsPath: 'https://docs.coclaw.net',
+		blurb: 'CoClaw channel plugin for remote chat',
+	},
+	capabilities: {
+		chatTypes: ['direct'],
+		nativeCommands: true,
+		media: false,
+		reactions: false,
+		threads: false,
+		polls: false,
+	},
+	config: {
+		listAccountIds: () => [DEFAULT_ACCOUNT_ID],
+		resolveAccount: (cfg, accountId) => resolveAccount(cfg, accountId),
+		defaultAccountId: () => DEFAULT_ACCOUNT_ID,
+		isConfigured: () => true,
+		describeAccount: (account) => ({
+			accountId: account.accountId,
+			name: account.name,
+			enabled: account.enabled,
+			configured: true,
+		}),
+	},
+	outbound: {
+		deliveryMode: 'direct',
+		sendText: async ({ to, text }) => {
+			const result = await transport.safeDispatchOutbound({
+				channel: 'coclaw',
+				to,
+				text,
+			});
+			return {
+				channel: 'coclaw',
+				messageId: result.messageId ?? `coclaw-local-${Date.now()}`,
+				to,
+				text,
+				accepted: Boolean(result.accepted),
+			};
+		},
+	},
+	status: {
+		defaultRuntime: {
+			accountId: DEFAULT_ACCOUNT_ID,
+			running: true,
+			lastStartAt: null,
+			lastStopAt: null,
+			lastError: null,
+		},
+	},
+};

package/src/cli-registrar.js

@@ -0,0 +1,87 @@
+import { bindBot, unbindBot } from './common/bot-binding.js';
+import { resolveErrorMessage } from './common/errors.js';
+import { callGatewayMethod } from './common/gateway-notify.js';
+import {
+	alreadyBound, notBound, bindOk, unbindOk,
+	gatewayNotified, gatewayNotifyFailed,
+} from './common/messages.js';
+
+function resolveServerUrl(opts, config) {
+	return opts?.server
+		?? config?.plugins?.entries?.['openclaw-coclaw']?.config?.serverUrl
+		?? process.env.COCLAW_SERVER_URL;
+}
+
+/**
+ * 注册 `openclaw coclaw bind/unbind` CLI 子命令
+ * @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()}`);
+		}
+	};
+
+	const coclaw = program
+		.command('coclaw')
+		.description('CoClaw bind/unbind commands');
+
+	coclaw
+		.command('bind <code>')
+		.description('Bind this OpenClaw instance to CoClaw')
+		.option('--server <url>', 'CoClaw server URL')
+		.action(async (code, opts) => {
+			try {
+				const serverUrl = resolveServerUrl(opts, config);
+				const result = await bindBot({ code, serverUrl });
+				/* c8 ignore next */
+				console.log(bindOk(result));
+				await notifyGateway('coclaw.refreshBridge');
+			} catch (err) {
+				if (err.code === 'ALREADY_BOUND') {
+					console.error(alreadyBound(err));
+					process.exitCode = 1;
+					return;
+				}
+				console.error(`Error: ${resolveErrorMessage(err)}`);
+				process.exitCode = 1;
+			}
+		});
+
+	coclaw
+		.command('unbind')
+		.description('Unbind this OpenClaw instance from CoClaw')
+		.option('--server <url>', 'CoClaw server URL')
+		.action(async (opts) => {
+			try {
+				const serverUrl = resolveServerUrl(opts, config);
+				const result = await unbindBot({ serverUrl });
+				/* c8 ignore next */
+				console.log(unbindOk(result));
+				await notifyGateway('coclaw.stopBridge');
+			} catch (err) {
+				if (err.code === 'NOT_BOUND') {
+					console.error(notBound());
+					process.exitCode = 1;
+					return;
+				}
+				console.error(`Error: ${resolveErrorMessage(err)}`);
+				process.exitCode = 1;
+			}
+		});
+}