openclaw-mobile 1.0.0

package/README.md

@@ -0,0 +1,223 @@
+# openclaw-mobile
+
+OpenClaw channel plugin for the Mobile app. Routes messages through a Cloudflare Worker relay.
+
+## Architecture
+
+```
+Mobile App ←WS→ [CF Worker / Durable Object] ←WS→ [OpenClaw Plugin] → Gateway Pipeline
+```
+
+1. Plugin registers an `openclaw-mobile` channel with the Gateway
+2. Gateway manages the channel lifecycle (start, stop, health monitoring)
+3. The plugin connects outbound to the CF Worker relay via WebSocket
+4. User messages from the mobile app flow through the relay into the Gateway's inbound pipeline
+5. AI replies go through `outbound.sendText` — Gateway automatically filters security markers and thinking blocks
+6. Filtered replies are forwarded to the mobile app via the relay
+7. A 30-second ping keepalive prevents the Cloudflare Durable Object from hibernating and dropping the connection
+
+## Prerequisites
+
+- OpenClaw Gateway installed and running (`npm install -g openclaw@latest`)
+- A deployed Cloudflare Worker relay (see `../relay/`)
+- Node.js 22+
+
+## Install
+
+From npm (when published):
+
+```bash
+openclaw plugins install openclaw-mobile
+```
+
+For local development:
+
+```bash
+openclaw plugins install -l ./plugin
+```
+
+## Quick Start
+
+### 1. Deploy the relay
+
+```bash
+cd relay
+npm install
+npx wrangler deploy
+```
+
+Note the deployed URL (e.g. `wss://openclaw-relay.your-name.workers.dev`).
+
+If you want relay authentication, set a secret:
+
+```bash
+npx wrangler secret put RELAY_TOKEN
+```
+
+### 2. Install the plugin
+
+From npm:
+
+```bash
+openclaw plugins install openclaw-mobile
+```
+
+For local development:
+
+```bash
+openclaw plugins install -l ./plugin
+cd plugin && npm install   # installs qrcode-terminal for inline QR display
+```
+
+> When installing from npm, `qrcode-terminal` is installed automatically as an optional dependency.
+
+### 3. Configure
+
+Add to `~/.openclaw/openclaw.json`:
+
+```json
+{
+  "channels": {
+    "openclaw-mobile": {
+      "accounts": {
+        "default": {
+          "enabled": true,
+          "relayUrl": "wss://openclaw-relay.your-name.workers.dev",
+          "relayToken": "your-secret-token",
+          "roomId": "default"
+        }
+      }
+    }
+  }
+}
+```
+
+> **Tip:** Leave `roomId` as `"default"` — the plugin will auto-generate a unique UUID on first start and save it to config automatically.
+
+### 4. Start the Gateway
+
+```bash
+openclaw gateway --port 18789
+```
+
+On startup, the plugin prints a pairing QR code to the terminal:
+
+```
+┌──────────────────────────────────────────────────┐
+│  OpenClaw Mobile — Scan to connect (account: default)
+├──────────────────────────────────────────────────┤
+│  ▄▄▄▄▄ ▄  ▄▄ ▄▄▄▄▄                              │
+│  █   █ ██▄▄█ █   █                              │
+│  ...                                             │
+├──────────────────────────────────────────────────┤
+│  openclaw://relay?url=wss%3A%2F%2F...&room=...   │
+└──────────────────────────────────────────────────┘
+```
+
+### 5. Pair the mobile app
+
+Open the **OpenClaw Mobile** app, tap **Scan QR Code**, and point the camera at the QR code printed in the terminal. The app will automatically connect to the relay using the correct room ID.
+
+### 6. Verify
+
+Open the Control UI at http://127.0.0.1:18789/ and navigate to the **OpenClaw Mobile** channel page. You should see:
+
+- **Running**: Yes
+- **Configured**: Yes
+- **Connected**: Yes
+
+You can also check logs:
+
+```bash
+tail -f ~/.openclaw/logs/gateway.log | grep openclaw-mobile
+```
+
+## Configuration
+
+All config lives under `channels.openclaw-mobile.accounts.<accountId>` in `~/.openclaw/openclaw.json`.
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `enabled` | boolean | No | `true` | Enable/disable this account |
+| `relayUrl` | string | **Yes** | — | CF Worker relay WebSocket URL |
+| `relayToken` | string | No | `""` | Shared secret for relay authentication (must match the Worker's `RELAY_TOKEN` secret) |
+| `roomId` | string | No | `"default"` | Room ID for relay routing (isolates conversations) |
+
+You can also edit these fields directly in the Control UI config form.
+
+## Control UI
+
+The plugin integrates with the OpenClaw Control UI:
+
+- **Status panel** — shows Running, Configured, Connected, Last inbound, and error details
+- **Config form** — editable fields for Relay URL, Relay Token, Room ID, and an Enable/Disable toggle
+- **Enable/Disable** — the toggle in the UI writes `enabled: true/false` to the config and restarts the channel
+
+## How the relay works
+
+The relay is a Cloudflare Worker with a Durable Object (`RelayRoom`):
+
+- Each "room" is a named DO instance that bridges two WebSocket roles: `plugin` (the Gateway) and `app` (the mobile client)
+- Messages from one role are forwarded to all peers of the opposite role
+- The DO uses `setWebSocketAutoResponse("ping", "pong")` for keepalive without waking from hibernation
+- The plugin sends a `ping` every 30 seconds to prevent idle disconnection
+- Optional `RELAY_TOKEN` secret gates access to the relay
+
+## Message Protocol
+
+### App → Plugin (via relay)
+
+```json
+{
+  "type": "message",
+  "content": "Hello",
+  "sessionKey": "relay-session",
+  "senderId": "mobile-user",
+  "senderName": "Mobile User"
+}
+```
+
+- `sessionKey` — the app's local session identifier; the plugin echoes it back in replies so the app can match them
+- `senderId` / `senderName` — optional; defaults to `"mobile-user"` / `"Mobile User"`
+
+### Plugin → App (via relay)
+
+```json
+{
+  "type": "message",
+  "role": "assistant",
+  "content": "AI reply text",
+  "sessionKey": "relay-session"
+}
+```
+
+The plugin echoes back the exact `sessionKey` it received from the app, so the Flutter client can route the reply to the correct chat session.
+
+## Troubleshooting
+
+| Problem | Cause | Fix |
+|---------|-------|-----|
+| "Channel config schema unavailable" in Control UI | Gateway loaded before plugin was installed | Restart the Gateway: `openclaw gateway stop && openclaw gateway` |
+| Running: No | `startAccount` returned early (old plugin version) | Update the plugin and restart Gateway |
+| Connected: No | Relay URL wrong or Worker not deployed | Check `relayUrl` in config; verify Worker is live with `curl https://your-relay.workers.dev/health` |
+| Relay keeps disconnecting | Ping keepalive not working or network issue | Check logs for "WebSocket error"; ensure relay Worker is deployed with Durable Objects enabled |
+| "relayUrl not configured" in logs | Missing `relayUrl` in account config | Add `relayUrl` under `channels.openclaw-mobile.accounts.default` |
+| Enable toggle in UI doesn't match JSON | Missing `setAccountEnabled` adapter (old plugin version) | Update the plugin and restart Gateway |
+| `relayToken` mismatch | Token in config doesn't match Worker secret | Ensure `relayToken` matches the `RELAY_TOKEN` secret set on the Worker |
+| App stuck loading, no reply shown | sessionKey mismatch between app and plugin | Ensure app sends `sessionKey` in message payload and plugin version ≥ current |
+
+### Useful commands
+
+```bash
+# Check plugin is loaded
+openclaw plugins list
+
+# Check channel status
+openclaw channels status --probe
+
+# Live logs
+tail -f ~/.openclaw/logs/gateway.log | grep openclaw-mobile
+
+# Verify relay is reachable
+curl https://openclaw-relay.your-name.workers.dev/health
+```

package/index.ts

@@ -0,0 +1,837 @@
+/**
+ * OpenClaw Mobile Channel Plugin
+ *
+ * Registers "openclaw-mobile" channel that bridges Gateway <-> CF Worker relay <-> Mobile App.
+ * Plugin runs inside the Gateway process, connects outbound to the relay.
+ *
+ * On first start, if roomId is "default", a UUID is auto-generated and saved to config.
+ * A QR code is printed to the terminal so the mobile app can scan and connect.
+ *
+ * Config (in ~/.openclaw/openclaw.json):
+ *   {
+ *     "channels": {
+ *       "openclaw-mobile": {
+ *         "accounts": {
+ *           "default": {
+ *             "enabled": true,
+ *             "relayUrl": "wss://openclaw-relay.xxx.workers.dev",
+ *             "relayToken": "your-secret",
+ *             "roomId": "auto-generated-uuid"
+ *           }
+ *         }
+ *       }
+ *     }
+ *   }
+ */
+
+import { randomUUID } from "node:crypto";
+
+// ── Plugin runtime (set during register) ────────────────────────────────────
+
+let pluginRuntime: any = null;
+
+// ── E2E Encryption (X25519 ECDH + AES-256-GCM) ──────────────────────────────
+// Uses Web Crypto API. Node 18+ uses standalone "X25519" algorithm name,
+// while browsers use { name: "ECDH", namedCurve: "X25519" }.
+
+// Runtime detection — resolved once on first use
+let _x25519Algo: { gen: any; imp: any; derive: string } | null = null;
+async function getX25519Algo() {
+    if (_x25519Algo) return _x25519Algo;
+    try {
+        await crypto.subtle.generateKey({ name: "ECDH", namedCurve: "X25519" } as any, true, ["deriveKey"]);
+        _x25519Algo = { gen: { name: "ECDH", namedCurve: "X25519" }, imp: { name: "ECDH", namedCurve: "X25519" }, derive: "ECDH" };
+    } catch {
+        _x25519Algo = { gen: { name: "X25519" }, imp: { name: "X25519" }, derive: "X25519" };
+    }
+    return _x25519Algo;
+}
+
+interface E2EState {
+    localKeyPair: CryptoKeyPair | null;
+    sharedKey: CryptoKey | null;
+    ready: boolean;
+}
+
+function makeE2EState(): E2EState {
+    return { localKeyPair: null, sharedKey: null, ready: false };
+}
+
+async function e2eInit(state: E2EState): Promise<string> {
+    const algo = await getX25519Algo();
+    state.localKeyPair = await crypto.subtle.generateKey(
+        algo.gen,
+        true,
+        ["deriveKey"]
+    );
+    const pubKeyRaw = await crypto.subtle.exportKey("raw", state.localKeyPair.publicKey);
+    const pubKeyB64 = bufToBase64Url(pubKeyRaw);
+    return JSON.stringify({ type: "handshake", pubkey: pubKeyB64 });
+}
+
+async function e2eHandleHandshake(state: E2EState, peerPubKeyB64: string): Promise<void> {
+    if (!state.localKeyPair) throw new Error("[E2E] Must call e2eInit first");
+    const algo = await getX25519Algo();
+
+    const peerPubKeyBytes = base64UrlToBuf(peerPubKeyB64);
+    const peerPublicKey = await crypto.subtle.importKey(
+        "raw",
+        peerPubKeyBytes.buffer as ArrayBuffer,
+        algo.imp,
+        false,
+        []
+    );
+
+    const ecdhRawKey = await crypto.subtle.deriveKey(
+        { name: algo.derive, public: peerPublicKey },
+        state.localKeyPair.privateKey,
+        { name: "AES-GCM", length: 256 },
+        true,
+        ["encrypt", "decrypt"]
+    );
+    const ecdhRawBytes = await crypto.subtle.exportKey("raw", ecdhRawKey);
+
+    // HKDF-SHA256: salt=empty, info="openclaw-e2e-v1" → AES-256-GCM key
+    const hkdfKey = await crypto.subtle.importKey(
+        "raw", ecdhRawBytes as ArrayBuffer, { name: "HKDF" }, false, ["deriveKey"]
+    );
+    state.sharedKey = await crypto.subtle.deriveKey(
+        {
+            name: "HKDF",
+            hash: "SHA-256",
+            salt: new Uint8Array(0),
+            info: new TextEncoder().encode("openclaw-e2e-v1"),
+        },
+        hkdfKey,
+        { name: "AES-GCM", length: 256 },
+        false,
+        ["encrypt", "decrypt"]
+    );
+
+    state.ready = true;
+}
+
+async function e2eEncrypt(state: E2EState, plaintext: string): Promise<string> {
+    if (!state.sharedKey) throw new Error("[E2E] Not ready");
+    const nonce = crypto.getRandomValues(new Uint8Array(12));
+    const ct = await crypto.subtle.encrypt(
+        { name: "AES-GCM", iv: nonce },
+        state.sharedKey,
+        new TextEncoder().encode(plaintext)
+    );
+    return JSON.stringify({
+        type: "encrypted",
+        nonce: bufToBase64Url(nonce),
+        ct: bufToBase64Url(ct),
+    });
+}
+
+async function e2eDecrypt(state: E2EState, nonceB64: string, ctB64: string): Promise<string> {
+    if (!state.sharedKey) throw new Error("[E2E] Not ready");
+    const nonce = base64UrlToBuf(nonceB64);
+    const ct = base64UrlToBuf(ctB64);
+    const plain = await crypto.subtle.decrypt(
+        { name: "AES-GCM", iv: nonce.buffer as ArrayBuffer },
+        state.sharedKey,
+        ct.buffer as ArrayBuffer
+    );
+    return new TextDecoder().decode(plain);
+}
+
+function bufToBase64Url(buf: ArrayBuffer | Uint8Array): string {
+    const bytes = buf instanceof Uint8Array ? buf : new Uint8Array(buf);
+    let binary = "";
+    for (const b of bytes) binary += String.fromCharCode(b);
+    return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+}
+
+function base64UrlToBuf(b64: string): Uint8Array {
+    const padded = b64.replace(/-/g, "+").replace(/_/g, "/");
+    const pad = (4 - padded.length % 4) % 4;
+    const binary = atob(padded + "=".repeat(pad));
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+    return bytes;
+}
+
+// ── Relay state (per account) ────────────────────────────────────────────────
+
+interface RelayState {
+    ws: WebSocket | null;
+    reconnectTimer: ReturnType<typeof setTimeout> | null;
+    pingTimer: ReturnType<typeof setInterval> | null;
+    statusSink: ((patch: Record<string, unknown>) => void) | null;
+    gatewayCtx: any;
+    /** Last sessionKey received from the app — echoed back in replies */
+    appSessionKey: string | null;
+    /** E2E encryption state for this account */
+    e2e: E2EState;
+}
+
+const relayStates = new Map<string, RelayState>();
+
+const RECONNECT_DELAY = 5000;
+const PING_INTERVAL = 30_000; // 30s keepalive — prevents DO hibernation
+const DEFAULT_ACCOUNT_ID = "default";
+const CHANNEL_ID = "openclaw-mobile";
+
+function getRelayState(accountId: string): RelayState {
+    let state = relayStates.get(accountId);
+    if (!state) {
+        state = { ws: null, reconnectTimer: null, pingTimer: null, statusSink: null, gatewayCtx: null, appSessionKey: null, e2e: makeE2EState() };
+        relayStates.set(accountId, state);
+    }
+    return state;
+}
+
+// ── Account resolution ───────────────────────────────────────────────────────
+
+interface ResolvedAccount {
+    accountId: string;
+    enabled: boolean;
+    relayUrl: string;
+    relayToken: string;
+    roomId: string;
+    configured: boolean;
+}
+
+function listAccountIds(cfg: any): string[] {
+    return Object.keys(
+        cfg.channels?.[CHANNEL_ID]?.accounts ?? {}
+    );
+}
+
+function resolveAccount(cfg: any, accountId?: string): ResolvedAccount {
+    const id = accountId ?? DEFAULT_ACCOUNT_ID;
+    const acct =
+        cfg.channels?.[CHANNEL_ID]?.accounts?.[id] ?? {};
+    return {
+        accountId: id,
+        enabled: acct.enabled !== false,
+        relayUrl: acct.relayUrl ?? "",
+        relayToken: acct.relayToken ?? "",
+        roomId: acct.roomId ?? "default",
+        configured: Boolean(acct.relayUrl),
+    };
+}
+
+// ── Channel config schema (JSON Schema for Control UI) ───────────────────────
+
+const mobileConfigSchema = {
+    schema: {
+        $schema: "http://json-schema.org/draft-07/schema#",
+        type: "object" as const,
+        properties: {
+            accounts: {
+                type: "object" as const,
+                additionalProperties: {
+                    type: "object" as const,
+                    properties: {
+                        enabled: { type: "boolean" as const },
+                        relayUrl: {
+                            type: "string" as const,
+                            description: "CF Worker relay WebSocket URL",
+                        },
+                        relayToken: {
+                            type: "string" as const,
+                            description: "Shared secret for relay authentication",
+                        },
+                        roomId: {
+                            type: "string" as const,
+                            description: "Room ID for relay routing",
+                        },
+                    },
+                    additionalProperties: false,
+                },
+            },
+        },
+        additionalProperties: false,
+    },
+    uiHints: {
+        relayUrl: {
+            label: "Relay URL",
+            placeholder: "wss://openclaw-relay.xxx.workers.dev",
+        },
+        relayToken: {
+            label: "Relay Token",
+            sensitive: true,
+        },
+        roomId: {
+            label: "Room ID",
+            placeholder: "default",
+        },
+    },
+};
+
+// ── QR Code pairing helper ───────────────────────────────────────────────────
+
+/**
+ * Build the openclaw://relay URI that the mobile app scans to connect.
+ */
+function buildPairingUri(relayUrl: string, roomId: string, relayToken?: string): string {
+    const params = new URLSearchParams({ url: relayUrl, room: roomId });
+    if (relayToken) params.set("token", relayToken);
+    return `openclaw://relay?${params.toString()}`;
+}
+
+/**
+ * Print a QR code + pairing URI to stdout.
+ * Uses qrcode-terminal if available; falls back to plain text.
+ */
+async function printPairingQr(uri: string, accountId: string): Promise<void> {
+    const border = "─".repeat(50);
+    console.log(`\n┌${border}┐`);
+    console.log(`│  OpenClaw Mobile — Scan to connect (account: ${accountId.padEnd(Math.max(0, 50 - 38))} │`);
+    console.log(`├${border}┤`);
+
+    try {
+        // Dynamically import qrcode-terminal (optional dependency)
+        const mod = await import("qrcode-terminal");
+        const qr: any = mod.default ?? mod;
+        await new Promise<void>((resolve) => {
+            qr.generate(uri, { small: true }, (qrStr: string) => {
+                const lines = qrStr.split("\n");
+                for (const line of lines) {
+                    console.log(`│  ${line}`);
+                }
+                resolve();
+            });
+        });
+    } catch {
+        // qrcode-terminal not installed — print plain URI
+        console.log(`│`);
+        console.log(`│  (Install qrcode-terminal for inline QR display)`);
+        console.log(`│`);
+    }
+
+    console.log(`├${border}┤`);
+    console.log(`│  ${uri.slice(0, 48).padEnd(48)}  │`);
+    if (uri.length > 48) {
+        console.log(`│  ${uri.slice(48, 96).padEnd(48)}  │`);
+    }
+    console.log(`└${border}┘\n`);
+}
+
+// ── Channel plugin ───────────────────────────────────────────────────────────
+
+const channel = {
+    id: CHANNEL_ID,
+    meta: {
+        id: CHANNEL_ID,
+        label: "OpenClaw Mobile",
+        selectionLabel: "OpenClaw Mobile App",
+        blurb: "Chat via the OpenClaw Mobile app through a relay.",
+        detailLabel: "Mobile App",
+        aliases: ["mobile"],
+    },
+    capabilities: {
+        chatTypes: ["direct"],
+    },
+    reload: { configPrefixes: [`channels.${CHANNEL_ID}`] },
+    configSchema: mobileConfigSchema,
+    config: {
+        listAccountIds: (cfg: any) => listAccountIds(cfg),
+        resolveAccount: (cfg: any, accountId?: string) =>
+            resolveAccount(cfg, accountId),
+        defaultAccountId: () => DEFAULT_ACCOUNT_ID,
+        setAccountEnabled: ({ cfg, accountId, enabled }: { cfg: any; accountId: string; enabled: boolean }) => {
+            const key = accountId || DEFAULT_ACCOUNT_ID;
+            const base = cfg.channels?.[CHANNEL_ID] ?? {};
+            const accounts = base.accounts ?? {};
+            return {
+                ...cfg,
+                channels: {
+                    ...cfg.channels,
+                    [CHANNEL_ID]: {
+                        ...base,
+                        accounts: {
+                            ...accounts,
+                            [key]: {
+                                ...accounts[key],
+                                enabled,
+                            },
+                        },
+                    },
+                },
+            };
+        },
+        isConfigured: (account: ResolvedAccount) => account.configured,
+        describeAccount: (account: ResolvedAccount) => ({
+            accountId: account.accountId,
+            enabled: account.enabled,
+            configured: account.configured,
+            relayUrl: account.relayUrl || "(not set)",
+        }),
+    },
+    outbound: {
+        deliveryMode: "direct" as const,
+
+        sendText: async ({ text, to, accountId, session }: any) => {
+            const aid = accountId ?? session?.accountId ?? DEFAULT_ACCOUNT_ID;
+            const state = getRelayState(aid);
+            if (!state.ws || state.ws.readyState !== WebSocket.OPEN) {
+                return { ok: false, error: "relay not connected" };
+            }
+
+            const runtime = pluginRuntime;
+            let outText = text ?? "";
+            if (runtime) {
+                const cfg = runtime.config.loadConfig();
+                const tableMode = runtime.channel.text.resolveMarkdownTableMode({
+                    cfg,
+                    channel: CHANNEL_ID,
+                    accountId: aid,
+                });
+                outText = runtime.channel.text.convertMarkdownTables(outText, tableMode);
+            }
+
+            const plainMsg = JSON.stringify({
+                type: "message",
+                role: "assistant",
+                content: outText,
+                sessionKey: session?.key,
+            });
+            const outMsg = state.e2e.ready
+                ? await e2eEncrypt(state.e2e, plainMsg)
+                : plainMsg;
+            state.ws.send(outMsg);
+
+            return {
+                channel: CHANNEL_ID,
+                to: to ?? "mobile-user",
+                messageId: `mobile-${Date.now()}`,
+            };
+        },
+    },
+
+    status: {
+        defaultRuntime: {
+            accountId: DEFAULT_ACCOUNT_ID,
+            running: false,
+            connected: false,
+            lastConnectedAt: null,
+            lastDisconnect: null,
+            lastStartAt: null,
+            lastStopAt: null,
+            lastError: null,
+            lastInboundAt: null,
+        },
+        buildChannelSummary: ({ snapshot }: any) => ({
+            configured: snapshot.configured ?? false,
+            running: snapshot.running ?? false,
+            connected: snapshot.connected ?? false,
+            lastInboundAt: snapshot.lastInboundAt ?? null,
+        }),
+        buildAccountSnapshot: ({ account, runtime }: any) => ({
+            accountId: account.accountId,
+            enabled: account.enabled,
+            configured: account.configured,
+            relayUrl: account.relayUrl || "(not set)",
+            running: runtime?.running ?? false,
+            connected: runtime?.connected ?? false,
+            lastStartAt: runtime?.lastStartAt ?? null,
+            lastStopAt: runtime?.lastStopAt ?? null,
+            lastError: runtime?.lastError ?? null,
+            lastInboundAt: runtime?.lastInboundAt ?? null,
+            lastConnectedAt: runtime?.lastConnectedAt ?? null,
+        }),
+    },
+
+    gateway: {
+        startAccount: async (ctx: any) => {
+            let account: ResolvedAccount = ctx.account;
+            const accountId = account.accountId;
+            const state = getRelayState(accountId);
+
+            cleanupRelay(state);
+
+            state.gatewayCtx = ctx;
+            state.statusSink = (patch: Record<string, unknown>) =>
+                ctx.setStatus({ accountId, ...patch });
+
+            ctx.setStatus({ accountId, running: true, lastStartAt: new Date().toISOString() });
+
+            if (!account.configured) {
+                const msg = "relayUrl not configured";
+                ctx.setStatus({ accountId, lastError: msg });
+                ctx.log?.warn?.(`[${CHANNEL_ID}] [${accountId}] ${msg}`);
+                return;
+            }
+
+            // Auto-generate a UUID room ID if still using the placeholder "default"
+            if (account.roomId === "default" || !account.roomId) {
+                const newRoomId = randomUUID();
+                ctx.log?.info?.(`[${CHANNEL_ID}] [${accountId}] Auto-generating room ID: ${newRoomId}`);
+                try {
+                    await ctx.updateAccountConfig?.({ accountId, patch: { roomId: newRoomId } });
+                    account = { ...account, roomId: newRoomId };
+                } catch {
+                    // updateAccountConfig not available in this Gateway version — continue with generated ID
+                    account = { ...account, roomId: newRoomId };
+                }
+            }
+
+            // Print pairing QR code to terminal
+            const pairingUri = buildPairingUri(account.relayUrl, account.roomId, account.relayToken || undefined);
+            printPairingQr(pairingUri, accountId).catch(() => {});
+
+            connectRelay(ctx, account);
+
+            const signal: AbortSignal | undefined = ctx.abortSignal;
+            if (signal) {
+                await new Promise<void>((resolve) => {
+                    if (signal.aborted) { resolve(); return; }
+                    signal.addEventListener("abort", () => resolve(), { once: true });
+                });
+                cleanupRelay(state);
+                ctx.setStatus({ accountId, running: false, connected: false });
+            }
+        },
+        stopAccount: async (ctx: any) => {
+            const accountId = ctx.account?.accountId ?? DEFAULT_ACCOUNT_ID;
+            const state = getRelayState(accountId);
+            cleanupRelay(state);
+
+            ctx.setStatus?.({
+                accountId,
+                running: false,
+                connected: false,
+                lastStopAt: new Date().toISOString(),
+            });
+            ctx.log?.info?.(`[${CHANNEL_ID}] [${accountId}] stopped`);
+        },
+    },
+};
+
+// ── Relay bridge ─────────────────────────────────────────────────────────────
+
+function cleanupRelay(state: RelayState) {
+    if (state.pingTimer) {
+        clearInterval(state.pingTimer);
+        state.pingTimer = null;
+    }
+    if (state.reconnectTimer) {
+        clearTimeout(state.reconnectTimer);
+        state.reconnectTimer = null;
+    }
+    if (state.ws) {
+        try { state.ws.close(); } catch {}
+        state.ws = null;
+    }
+    // Reset E2E state on disconnect — new handshake needed on reconnect
+    state.e2e = makeE2EState();
+}
+
+function connectRelay(ctx: any, account: ResolvedAccount) {
+    const accountId = account.accountId;
+    const state = getRelayState(accountId);
+
+    const base = account.relayUrl.replace(/\/$/, "");
+    const params = new URLSearchParams({
+        role: "plugin",
+        room: account.roomId,
+    });
+    if (account.relayToken) params.set("token", account.relayToken);
+
+    const url = `${base}/ws?${params.toString()}`;
+    ctx.log?.info?.(`[${CHANNEL_ID}] [${accountId}] Connecting to relay: ${url}`);
+
+    try {
+        state.ws = new WebSocket(url);
+    } catch (err) {
+        const msg = `WebSocket create failed: ${err}`;
+        ctx.log?.error?.(`[${CHANNEL_ID}] [${accountId}] ${msg}`);
+        state.statusSink?.({ lastError: msg });
+        scheduleReconnect(ctx, account);
+        return;
+    }
+
+    state.ws.addEventListener("open", () => {
+        ctx.log?.info?.(`[${CHANNEL_ID}] [${accountId}] Relay connected`);
+        if (state.reconnectTimer) {
+            clearTimeout(state.reconnectTimer);
+            state.reconnectTimer = null;
+        }
+        if (state.pingTimer) clearInterval(state.pingTimer);
+        state.pingTimer = setInterval(() => {
+            if (state.ws?.readyState === WebSocket.OPEN) {
+                state.ws.send("ping");
+            }
+        }, PING_INTERVAL);
+
+        state.statusSink?.({
+            connected: true,
+            lastConnectedAt: new Date().toISOString(),
+            lastError: null,
+        });
+
+        // Initiate E2E handshake
+        state.e2e = makeE2EState();
+        e2eInit(state.e2e).then((handshakeMsg) => {
+            if (state.ws?.readyState === WebSocket.OPEN) {
+                state.ws.send(handshakeMsg);
+                ctx.log?.info?.(`[${CHANNEL_ID}] [${accountId}] [E2E] Handshake sent`);
+            }
+        }).catch((err) => {
+            ctx.log?.error?.(`[${CHANNEL_ID}] [${accountId}] [E2E] Init failed: ${err}`);
+        });
+    });
+
+    state.ws.addEventListener("message", (event: MessageEvent) => {
+        handleRelayMessage(ctx, accountId, state, String(event.data)).catch((e) => {
+            ctx.log?.error?.(
+                `[${CHANNEL_ID}] [${accountId}] Failed to handle relay message: ${e}`
+            );
+        });
+    });
+
+    state.ws.addEventListener("close", () => {
+        ctx.log?.info?.(
+            `[${CHANNEL_ID}] [${accountId}] Relay disconnected, reconnecting...`
+        );
+        state.ws = null;
+        if (state.pingTimer) {
+            clearInterval(state.pingTimer);
+            state.pingTimer = null;
+        }
+        state.statusSink?.({
+            connected: false,
+            lastDisconnect: new Date().toISOString(),
+        });
+        scheduleReconnect(ctx, account);
+    });
+
+    state.ws.addEventListener("error", () => {
+        ctx.log?.error?.(`[${CHANNEL_ID}] [${accountId}] Relay WebSocket error`);
+        state.statusSink?.({ lastError: "WebSocket error" });
+    });
+}
+
+function scheduleReconnect(ctx: any, account: ResolvedAccount) {
+    const state = getRelayState(account.accountId);
+    if (state.reconnectTimer) return;
+    state.reconnectTimer = setTimeout(() => {
+        state.reconnectTimer = null;
+        connectRelay(ctx, account);
+    }, RECONNECT_DELAY);
+}
+
+async function handleRelayMessage(ctx: any, accountId: string, state: RelayState, raw: string): Promise<void> {
+    // Skip ping/pong
+    if (raw === "ping" || raw === "pong") return;
+
+    ctx.log?.info?.(`[${CHANNEL_ID}] [${accountId}] Relay message: ${raw.slice(0, 200)}`);
+
+    const msg = JSON.parse(raw);
+
+    // App just joined the room — (re-)send our handshake so it can complete E2E
+    if (msg.type === "peer_joined") {
+        ctx.log?.info?.(`[${CHANNEL_ID}] [${accountId}] [E2E] Peer joined (role=${msg.role}), re-sending handshake`);
+        state.e2e = makeE2EState();
+        const handshakeMsg = await e2eInit(state.e2e);
+        if (state.ws?.readyState === WebSocket.OPEN) {
+            state.ws.send(handshakeMsg);
+        }
+        return;
+    }
+
+    // E2E handshake from app
+    if (msg.type === "handshake") {
+        const peerPubKey = msg.pubkey as string | undefined;
+        if (!peerPubKey) {
+            ctx.log?.warn?.(`[${CHANNEL_ID}] [${accountId}] [E2E] Handshake missing pubkey`);
+            return;
+        }
+        await e2eHandleHandshake(state.e2e, peerPubKey);
+        ctx.log?.info?.(`[${CHANNEL_ID}] [${accountId}] [E2E] Handshake complete — channel encrypted`);
+        return;
+    }
+
+    // E2E encrypted message — decrypt then process
+    if (msg.type === "encrypted") {
+        if (!state.e2e.ready) {
+            ctx.log?.warn?.(`[${CHANNEL_ID}] [${accountId}] [E2E] Received encrypted msg but not ready, dropping`);
+            return;
+        }
+        const plaintext = await e2eDecrypt(state.e2e, msg.nonce, msg.ct);
+        ctx.log?.info?.(`[${CHANNEL_ID}] [${accountId}] [E2E] Decrypted: ${plaintext.slice(0, 200)}`);
+        const innerMsg = JSON.parse(plaintext);
+        await handleInbound(ctx, accountId, innerMsg);
+        return;
+    }
+
+    // Plaintext message (fallback during handshake or if E2E disabled)
+    await handleInbound(ctx, accountId, msg);
+}
+
+async function handleInbound(ctx: any, accountId: string, msg: any) {
+    ctx.log?.info?.(`[${CHANNEL_ID}] [${accountId}] handleInbound: type=${msg.type} content=${String(msg.content ?? "").slice(0, 100)}`);
+
+    if (msg.type !== "message" || !msg.content) {
+        ctx.log?.warn?.(`[${CHANNEL_ID}] [${accountId}] Skipping non-message: type=${msg.type}`);
+        return;
+    }
+
+    const state = getRelayState(accountId);
+    state.statusSink?.({ lastInboundAt: new Date().toISOString() });
+
+    // Remember the sessionKey the app sent so we can echo it back in the reply
+    if (msg.sessionKey) {
+        state.appSessionKey = String(msg.sessionKey);
+    }
+
+    const runtime = pluginRuntime;
+    if (!runtime) {
+        ctx.log?.error?.(`[${CHANNEL_ID}] [${accountId}] Plugin runtime not available, cannot dispatch inbound message`);
+        return;
+    }
+
+    const senderId = msg.senderId ?? "mobile-user";
+    const senderName = msg.senderName ?? "Mobile User";
+    const text = String(msg.content);
+
+    try {
+        const cfg = runtime.config.loadConfig();
+
+        const route = runtime.channel.routing.resolveAgentRoute({
+            cfg,
+            channel: CHANNEL_ID,
+            accountId,
+            peer: { kind: "direct", id: senderId },
+        });
+
+        // If the app specified a sessionKey (UUID-based), derive an isolated
+        // Gateway session so each mobile conversation has its own context.
+        // Format: "agent:main:mobile-<uuid>"
+        // No appSessionKey → use the route's mainSessionKey (default conversation).
+        let sessionKey: string;
+        const appSessionKey = msg.sessionKey ? String(msg.sessionKey) : null;
+        if (appSessionKey) {
+            // Extract agent prefix from mainSessionKey e.g. "agent:main:" from "agent:main:main"
+            const mainKey = route.mainSessionKey as string;
+            const colonIdx = mainKey.lastIndexOf(':');
+            const agentPrefix = colonIdx > 0 ? mainKey.substring(0, colonIdx + 1) : '';
+            sessionKey = `${agentPrefix}mobile-${appSessionKey}`;
+        } else {
+            sessionKey = route.mainSessionKey;
+        }
+        const from = `${CHANNEL_ID}:${senderId}`;
+        const to = `user:${senderId}`;
+
+        runtime.channel.activity.record({
+            channel: CHANNEL_ID,
+            accountId,
+            direction: "inbound",
+        });
+
+        runtime.system.enqueueSystemEvent(
+            `Mobile message from ${senderName}: ${text.slice(0, 160)}`,
+            { sessionKey, contextKey: `${CHANNEL_ID}:message:${Date.now()}` },
+        );
+
+        const body = runtime.channel.reply.formatInboundEnvelope({
+            channel: "OpenClaw Mobile",
+            from: `${senderName} (mobile)`,
+            body: text,
+            chatType: "direct",
+            sender: { name: senderName, id: senderId },
+        });
+
+        const ctxPayload = runtime.channel.reply.finalizeInboundContext({
+            Body: body,
+            BodyForAgent: text,
+            RawBody: text,
+            CommandBody: text,
+            From: from,
+            To: to,
+            SessionKey: sessionKey,
+            AccountId: accountId,
+            ChatType: "direct",
+            ConversationLabel: `Mobile DM from ${senderName}`,
+            SenderName: senderName,
+            SenderId: senderId,
+            Provider: CHANNEL_ID,
+            Surface: CHANNEL_ID,
+            OriginatingChannel: CHANNEL_ID,
+            OriginatingTo: to,
+        });
+
+        const textLimit = runtime.channel.text.resolveTextChunkLimit(
+            cfg, CHANNEL_ID, accountId, { fallbackLimit: 4000 },
+        );
+        const tableMode = runtime.channel.text.resolveMarkdownTableMode({
+            cfg, channel: CHANNEL_ID, accountId,
+        });
+
+        const { dispatcher, replyOptions, markDispatchIdle } =
+            runtime.channel.reply.createReplyDispatcherWithTyping({
+                humanDelay: runtime.channel.reply.resolveHumanDelayConfig(cfg, route.agentId),
+                deliver: async (payload: any) => {
+                    const relayState = getRelayState(accountId);
+                    if (!relayState.ws || relayState.ws.readyState !== WebSocket.OPEN) {
+                        ctx.log?.error?.(`[${CHANNEL_ID}] [${accountId}] Cannot deliver reply: relay not connected`);
+                        return;
+                    }
+                    const replyText = runtime.channel.text.convertMarkdownTables(
+                        payload.text ?? "", tableMode,
+                    );
+                    const chunkMode = runtime.channel.text.resolveChunkMode(cfg, CHANNEL_ID, accountId);
+                    const chunks = runtime.channel.text.chunkMarkdownTextWithMode(replyText, textLimit, chunkMode);
+                    // Echo back the sessionKey the app sent (so the app can match the reply)
+                    const replySessionKey = relayState.appSessionKey ?? sessionKey;
+                    for (const chunk of chunks.length > 0 ? chunks : [replyText]) {
+                        if (!chunk) continue;
+                        const plainMsg = JSON.stringify({
+                            type: "message",
+                            role: "assistant",
+                            content: chunk,
+                            sessionKey: replySessionKey,
+                        });
+                        // Encrypt if E2E handshake is complete
+                        const outMsg = relayState.e2e.ready
+                            ? await e2eEncrypt(relayState.e2e, plainMsg)
+                            : plainMsg;
+                        relayState.ws.send(outMsg);
+                    }
+                    ctx.log?.info?.(`[${CHANNEL_ID}] [${accountId}] Reply delivered (${replyText.length} chars) to sessionKey=${replySessionKey}`);
+                },
+                onError: (err: any, info: any) => {
+                    ctx.log?.error?.(`[${CHANNEL_ID}] [${accountId}] Reply dispatch error (${info?.kind}): ${err}`);
+                },
+            });
+
+        await runtime.channel.reply.dispatchReplyFromConfig({
+            ctx: ctxPayload,
+            cfg,
+            dispatcher,
+            replyOptions,
+        });
+        markDispatchIdle();
+
+        const sessionCfg = cfg.session;
+        const storePath = runtime.channel.session.resolveStorePath(sessionCfg?.store, {
+            agentId: route.agentId,
+        });
+        await runtime.channel.session.updateLastRoute({
+            storePath,
+            sessionKey,
+            deliveryContext: {
+                channel: CHANNEL_ID,
+                to,
+                accountId,
+            },
+        });
+
+        ctx.log?.info?.(`[${CHANNEL_ID}] [${accountId}] Inbound message processed for session ${sessionKey}`);
+    } catch (e) {
+        ctx.log?.error?.(`[${CHANNEL_ID}] [${accountId}] Error processing inbound message: ${e}`);
+    }
+}
+
+// ── Plugin entry ─────────────────────────────────────────────────────────────
+
+export default function register(api: any) {
+    pluginRuntime = api.runtime;
+    api.registerChannel({ plugin: channel });
+    api.logger?.info?.("[openclaw-mobile] Plugin registered");
+}

package/openclaw.plugin.json

@@ -0,0 +1,42 @@
+{
+    "id": "openclaw-mobile",
+    "name": "OpenClaw Mobile",
+    "version": "1.0.0",
+    "description": "Mobile app channel for OpenClaw — chat via the OpenClaw Mobile app through a Cloudflare Worker relay.",
+    "channels": [
+        "openclaw-mobile"
+    ],
+    "configSchema": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+            "relayUrl": {
+                "type": "string",
+                "description": "CF Worker relay WebSocket URL (e.g. wss://openclaw-relay.xxx.workers.dev)"
+            },
+            "relayToken": {
+                "type": "string",
+                "description": "Shared secret for relay authentication"
+            },
+            "roomId": {
+                "type": "string",
+                "description": "Room ID for relay routing",
+                "default": "default"
+            }
+        }
+    },
+    "uiHints": {
+        "relayUrl": {
+            "label": "Relay URL",
+            "placeholder": "wss://openclaw-relay.xxx.workers.dev"
+        },
+        "relayToken": {
+            "label": "Relay Token",
+            "sensitive": true
+        },
+        "roomId": {
+            "label": "Room ID",
+            "placeholder": "default"
+        }
+    }
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "openclaw-mobile",
+  "version": "1.0.0",
+  "description": "OpenClaw Mobile channel plugin — relay bridge for the OpenClaw Mobile app",
+  "main": "index.ts",
+  "type": "module",
+  "files": [
+    "index.ts",
+    "openclaw.plugin.json",
+    "README.md"
+  ],
+  "openclaw": {
+    "plugin": "./openclaw.plugin.json",
+    "extensions": ["./index.ts"]
+  },
+  "keywords": ["openclaw", "plugin", "channel", "mobile"],
+  "license": "MIT",
+  "optionalDependencies": {
+    "qrcode-terminal": "^0.12.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0"
+  },
+  "peerDependencies": {
+    "openclaw": "*"
+  },
+  "peerDependenciesMeta": {
+    "openclaw": {
+      "optional": true
+    }
+  }
+}