@iml1s/claw-link 0.1.0

package/README.md

@@ -0,0 +1,30 @@
+# @openclaw/claw-link
+
+Cloud relay bridge plugin for [OpenClaw](https://github.com/anthropics/openclaw) — connects mobile devices to local gateways via a WebSocket relay server.
+
+## Install
+
+```bash
+openclaw plugins install @openclaw/claw-link
+```
+
+## How it works
+
+1. Plugin registers with the cloud relay server on gateway startup
+2. A QR code / connection string is printed in the terminal
+3. Scan the QR code with the OpenClaw Dashboard mobile app
+4. Mobile app connects through the relay to your local gateway
+
+## Configuration
+
+**Zero configuration required** — the plugin connects to the default cloud relay automatically.
+
+To use a custom relay server, set the environment variable:
+
+```bash
+CLAW_LINK_RELAY_URL=wss://your-relay.example.com/register openclaw gateway
+```
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.start = start;
+exports.stop = stop;
+const relay_client_js_1 = require("./relay-client.js");
+let client = null;
+function start() {
+    console.log('Claw Link Plugin started');
+    // Uses production Cloud Relay by default; override with CLAW_LINK_RELAY_URL env var for local dev.
+    const gatewayToken = process.env.OPENCLAW_GATEWAY_TOKEN;
+    client = new relay_client_js_1.RelayClient(undefined, gatewayToken);
+    client.connect();
+}
+function stop() {
+    console.log('Claw Link Plugin stopped');
+    if (client) {
+        client.disconnect();
+        client = null;
+    }
+}

package/dist/openclaw-plugin.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * OpenClaw Plugin Adapter for Claw Link
+ *
+ * This module exports the OpenClaw plugin definition that integrates
+ * the Claw Link relay service into the OpenClaw gateway lifecycle.
+ * When the gateway starts, the plugin registers as a service that
+ * connects to the Cloud Relay server and bridges traffic to the
+ * local gateway.
+ */
+const relay_client_js_1 = require("./relay-client.js");
+let client = null;
+const plugin = {
+    id: 'claw-link',
+    name: 'Claw Link',
+    description: 'Cloud relay bridge \u2014 connects mobile devices to the local gateway via a relay server.',
+    configSchema: {
+        safeParse: (value) => ({ success: true, data: value }),
+        parse: (value) => value,
+        uiHints: {
+            relayUrl: {
+                label: 'Relay Server URL',
+                description: 'WebSocket URL of the Cloud Relay server (e.g. ws://relay.example.com:8080)',
+                type: 'string',
+            },
+        },
+    },
+    register(api) {
+        const logger = api.logger ?? console;
+        api.registerService({
+            id: 'claw-link',
+            start(_ctx) {
+                const relayUrl = api.pluginConfig?.relayUrl ??
+                    process.env.CLAW_LINK_RELAY_URL ??
+                    undefined;
+                // Try multiple sources for the gateway token:
+                // 1. OpenClaw plugin API (may not expose it)
+                // 2. Environment variable
+                // 3. Read from config file directly
+                let gatewayToken = api.config?.get?.('gateway.auth.token') ??
+                    process.env.OPENCLAW_GATEWAY_TOKEN ??
+                    undefined;
+                if (!gatewayToken) {
+                    try {
+                        const os = require('os');
+                        const path = require('path');
+                        const fs = require('fs');
+                        const configPath = path.join(os.homedir(), '.openclaw', 'openclaw.json');
+                        const raw = fs.readFileSync(configPath, 'utf-8');
+                        const config = JSON.parse(raw);
+                        gatewayToken = config?.gateway?.auth?.token ?? undefined;
+                    }
+                    catch {
+                        // Config file not readable — token will be omitted from QR code
+                    }
+                }
+                logger.info('[claw-link] Starting Cloud Relay bridge...');
+                client = new relay_client_js_1.RelayClient(relayUrl, gatewayToken);
+                client.connect();
+            },
+            stop(_ctx) {
+                logger.info('[claw-link] Stopping Cloud Relay bridge...');
+                if (client) {
+                    client.disconnect();
+                    client = null;
+                }
+            },
+        });
+    },
+};
+exports.default = plugin;

package/dist/relay-client.js

@@ -0,0 +1,218 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RelayClient = void 0;
+exports.buildRegisterUrl = buildRegisterUrl;
+exports.buildJoinUrlFromRegister = buildJoinUrlFromRegister;
+exports.buildConnectionString = buildConnectionString;
+const ws_1 = __importDefault(require("ws"));
+const qrcode_terminal_1 = require("qrcode-terminal");
+const node_crypto_1 = require("node:crypto");
+function buildRegisterUrl(relayUrl, sessionId) {
+    const registerUrl = new URL(relayUrl);
+    registerUrl.searchParams.set('session_id', sessionId);
+    return registerUrl.toString();
+}
+function buildJoinUrlFromRegister(relayUrl, sessionId) {
+    const joinUrl = new URL(relayUrl);
+    const path = joinUrl.pathname;
+    if (path.endsWith('/register')) {
+        joinUrl.pathname = path.substring(0, path.length - '/register'.length) + '/join';
+    }
+    else if (path.endsWith('/register/')) {
+        joinUrl.pathname =
+            path.substring(0, path.length - '/register/'.length) + '/join';
+    }
+    else if (!path.endsWith('/join')) {
+        joinUrl.pathname = path.endsWith('/') ? `${path}join` : `${path}/join`;
+    }
+    joinUrl.searchParams.set('session_id', sessionId);
+    return joinUrl.toString();
+}
+function buildConnectionString(relayUrl, sessionId, gatewayToken) {
+    const joinUrl = buildJoinUrlFromRegister(relayUrl, sessionId);
+    const outer = new URL('claw://connect');
+    outer.searchParams.set('relay', joinUrl.toString());
+    if (gatewayToken != null && gatewayToken.length > 0) {
+        outer.searchParams.set('gateway_token', gatewayToken);
+    }
+    return outer.toString();
+}
+class RelayClient {
+    static localQueueLimit = 64;
+    relayWs = null;
+    localWs = null;
+    sessionId;
+    pendingToLocal = [];
+    relayUrl;
+    localGatewayUrl = 'ws://localhost:18789';
+    gatewayToken;
+    isDisconnecting = false;
+    hasPrintedQrCode = false;
+    constructor(relayUrl = 'wss://claw-cloud-relay-374931447815.asia-east1.run.app/register', gatewayToken) {
+        this.sessionId = (0, node_crypto_1.randomUUID)();
+        this.relayUrl = relayUrl;
+        this.gatewayToken = gatewayToken;
+    }
+    connect() {
+        this.isDisconnecting = false;
+        console.log(`[RelayClient] Connecting to Relay Server at ${this.relayUrl}...`);
+        // Append session_id using URL API to avoid malformed query strings.
+        this.relayWs = new ws_1.default(buildRegisterUrl(this.relayUrl, this.sessionId));
+        this.relayWs.on('open', () => {
+            console.log('[RelayClient] Connected to Relay Server.');
+            if (!this.hasPrintedQrCode) {
+                this.displayQrCode();
+                this.hasPrintedQrCode = true;
+            }
+            this.ensureLocalGatewayConnected();
+        });
+        this.relayWs.on('message', (data, isBinary) => {
+            if (isBinary) {
+                // Binary data: forward to local gateway preserving binary type
+                this.forwardToLocal(data, true);
+            }
+            else {
+                // Text data could be control messages or text traffic
+                const message = data.toString();
+                try {
+                    const parsed = JSON.parse(message);
+                    if (parsed.type === 'pipe_start') {
+                        this.ensureLocalGatewayConnected();
+                    }
+                    else {
+                        this.forwardToLocal(data, false);
+                    }
+                }
+                catch (e) {
+                    // Not JSON, treat as data
+                    this.forwardToLocal(data, false);
+                }
+            }
+        });
+        this.relayWs.on('close', () => {
+            console.log('[RelayClient] Disconnected from Relay Server.');
+            this.cleanup();
+            if (!this.isDisconnecting) {
+                console.log('[RelayClient] Connection lost. Attempting to reconnect in 1 second...');
+                setTimeout(() => {
+                    this.connect();
+                }, 1000);
+            }
+        });
+        this.relayWs.on('error', (error) => {
+            console.error('[RelayClient] Relay WebSocket error:', error.message);
+        });
+    }
+    ensureLocalGatewayConnected() {
+        if (this.localWs) {
+            if (this.localWs.readyState === ws_1.default.OPEN ||
+                this.localWs.readyState === ws_1.default.CONNECTING) {
+                return;
+            }
+            this.localWs = null;
+        }
+        console.log('[RelayClient] Connecting to Local Gateway for byte forwarding...');
+        this.localWs = new ws_1.default(this.localGatewayUrl);
+        this.localWs.on('open', () => {
+            console.log(`[RelayClient] Connected to Local Gateway at ${this.localGatewayUrl}`);
+            this.flushPendingToLocal();
+        });
+        this.localWs.on('message', (data, isBinary) => {
+            // Forward data from Local Gateway to Relay, preserving text/binary type
+            if (this.relayWs && this.relayWs.readyState === ws_1.default.OPEN) {
+                // CRITICAL: preserve the message type (text vs binary)
+                // ws library sends Buffer as binary by default, which Flutter drops
+                this.relayWs.send(data, { binary: isBinary });
+            }
+        });
+        this.localWs.on('close', () => {
+            console.log('[RelayClient] Local Gateway disconnected.');
+            this.localWs = null;
+            // Keep relay socket alive; reconnect local gateway lazily when data arrives.
+        });
+        this.localWs.on('error', (error) => {
+            console.error('[RelayClient] Local Gateway WebSocket error:', error.message);
+            // Reset to allow retry on next event.
+            this.localWs = null;
+        });
+    }
+    forwardToLocal(data, isBinary = false) {
+        // Recover from protocol mismatch: server currently behaves as dumb byte pipe
+        // and may not send control messages like `pipe_start`.
+        this.ensureLocalGatewayConnected();
+        if (this.localWs && this.localWs.readyState === ws_1.default.OPEN) {
+            // CRITICAL: preserve text/binary type so Gateway processes correctly
+            this.localWs.send(data, { binary: isBinary });
+            return;
+        }
+        // Queue frames while local gateway is connecting.
+        const frame = this.toBuffer(data);
+        if (this.pendingToLocal.length >= RelayClient.localQueueLimit) {
+            this.pendingToLocal.shift();
+        }
+        this.pendingToLocal.push({ data: frame, isBinary });
+    }
+    flushPendingToLocal() {
+        if (!this.localWs || this.localWs.readyState !== ws_1.default.OPEN) {
+            return;
+        }
+        while (this.pendingToLocal.length > 0) {
+            const item = this.pendingToLocal.shift();
+            if (item == null) {
+                continue;
+            }
+            // Preserve text/binary type from original message
+            this.localWs.send(item.data, { binary: item.isBinary });
+        }
+    }
+    toBuffer(data) {
+        if (Buffer.isBuffer(data)) {
+            return data;
+        }
+        if (data instanceof ArrayBuffer) {
+            return Buffer.from(data);
+        }
+        if (Array.isArray(data)) {
+            return Buffer.concat(data);
+        }
+        if (typeof data === 'string') {
+            return Buffer.from(data);
+        }
+        return Buffer.alloc(0);
+    }
+    displayQrCode() {
+        const connectionString = buildConnectionString(this.relayUrl, this.sessionId, this.gatewayToken);
+        console.log('\nScan this QR Code with your mobile app to connect:\n');
+        try {
+            // For very long URLs, qrcode-terminal can crash with { small: true }
+            (0, qrcode_terminal_1.generate)(connectionString);
+        }
+        catch (e) {
+            console.log('(Terminal too small or string too long to render QR code)');
+        }
+        console.log(`\nConnection String: ${connectionString}\n`);
+    }
+    disconnect() {
+        this.isDisconnecting = true;
+        this.cleanup();
+    }
+    cleanup() {
+        if (this.relayWs) {
+            // Remove generic 'close' listener so we don't trigger reconnect logic
+            // during a manual disconnect/cleanup process. Note: We only do this
+            // if `isDisconnecting` is true, otherwise we let the standard `on('close')`
+            // handle the reconnect. Actually, we shouldn't remove it here, the
+            // 'close' handler already checks `this.isDisconnecting`.
+            this.relayWs.close();
+            this.relayWs = null;
+        }
+        if (this.localWs) {
+            this.localWs.close();
+            this.localWs = null;
+        }
+    }
+}
+exports.RelayClient = RelayClient;

package/openclaw.plugin.json

@@ -0,0 +1,22 @@
+{
+  "id": "claw-link",
+  "name": "Claw Link",
+  "version": "0.1.0",
+  "description": "Cloud relay bridge — connects mobile devices to the local gateway via a relay server.",
+  "configSchema": {
+    "type": "object",
+    "properties": {
+      "relayUrl": {
+        "type": "string",
+        "description": "WebSocket URL of the Cloud Relay server"
+      }
+    }
+  },
+  "uiHints": {
+    "relayUrl": {
+      "label": "Relay Server URL",
+      "description": "WebSocket URL of the Cloud Relay server (e.g. ws://relay.example.com:8080)",
+      "type": "string"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@iml1s/claw-link",
+  "version": "0.1.0",
+  "description": "Cloud relay bridge plugin for OpenClaw — connects mobile devices to local gateways via a relay server.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/**/*.js",
+    "!dist/**/*.test.js",
+    "openclaw.plugin.json"
+  ],
+  "keywords": [
+    "openclaw",
+    "plugin",
+    "relay",
+    "websocket",
+    "mobile"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/anthropics/openclaw-dashboard",
+    "directory": "plugins/claw-link"
+  },
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc -w",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "qrcode-terminal": "^0.12.0",
+    "ws": "^8.16.0"
+  },
+  "openclaw": {
+    "extensions": [
+      "./dist/openclaw-plugin.js"
+    ]
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/qrcode-terminal": "^0.12.2",
+    "@types/ws": "^8.5.10",
+    "typescript": "^5.0.0",
+    "vitest": "^2.1.8"
+  }
+}