openclaw-app 1.0.0

package/README.md

@@ -0,0 +1,193 @@
+# @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
+
+```bash
+openclaw plugins install -l ./plugin
+```
+
+### 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"
+        }
+      }
+    }
+  }
+}
+```
+
+### 4. Restart the Gateway
+
+```bash
+openclaw gateway stop
+openclaw gateway --port 18789
+```
+
+### 5. 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,866 @@
+/**
+ * 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.
+ * No external dependencies — uses Node.js built-in WebSocket.
+ *
+ * Config (in ~/.openclaw/openclaw.json):
+ *   {
+ *     "channels": {
+ *       "openclaw-mobile": {
+ *         "accounts": {
+ *           "default": {
+ *             "enabled": true,
+ *             "relayUrl": "wss://openclaw-relay.xxx.workers.dev",
+ *             "relayToken": "your-secret",
+ *             "roomId": "default"
+ *           }
+ *         }
+ *       }
+ *     }
+ *   }
+ */
+
+// ── 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;
+    /**
+     * Per-session E2E state keyed by the app's session UUID.
+     * Each app connection gets its own X25519 keypair + AES-256-GCM shared key
+     * so multiple users can be active simultaneously without key collisions.
+     */
+    e2eSessions: Map<string, 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, e2eSessions: new Map() };
+        relayStates.set(accountId, state);
+    }
+    return state;
+}
+
+// ── Account resolution ───────────────────────────────────────────────────────
+
+/** Default relay deployed at https://github.com/openclaw/openclaw-mobile */
+const DEFAULT_RELAY_URL = "wss://openclaw-relay.eldermoo8718.workers.dev";
+const DEFAULT_ROOM_ID = "default";
+
+interface ResolvedAccount {
+    accountId: string;
+    enabled: boolean;
+    relayUrl: string;
+    relayToken: string;
+    roomId: string;
+    configured: boolean;
+}
+
+function listAccountIds(cfg: any): string[] {
+    const ids = Object.keys(
+        cfg.channels?.[CHANNEL_ID]?.accounts ?? {}
+    );
+    // Always expose at least the default account so the Control UI
+    // shows a pre-filled entry without the user having to click "Add Entry".
+    if (!ids.includes(DEFAULT_ACCOUNT_ID)) ids.unshift(DEFAULT_ACCOUNT_ID);
+    return ids;
+}
+
+function resolveAccount(cfg: any, accountId?: string): ResolvedAccount {
+    const id = accountId ?? DEFAULT_ACCOUNT_ID;
+    const acct =
+        cfg.channels?.[CHANNEL_ID]?.accounts?.[id] ?? {};
+    const relayUrl = acct.relayUrl || DEFAULT_RELAY_URL;
+    const roomId = acct.roomId || DEFAULT_ROOM_ID;
+    return {
+        accountId: id,
+        enabled: acct.enabled !== false,
+        relayUrl,
+        relayToken: acct.relayToken ?? "",
+        roomId,
+        configured: true, // always ready out of the box with the default relay
+    };
+}
+
+// ── 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: DEFAULT_RELAY_URL,
+        },
+        relayToken: {
+            label: "Relay Token",
+            sensitive: true,
+        },
+        roomId: {
+            label: "Room ID",
+            placeholder: DEFAULT_ROOM_ID,
+        },
+    },
+};
+
+// ── 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,
+            roomId: account.roomId,
+        }),
+    },
+    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 replySessionKey = session?.key ?? null;
+            const sessionE2E = replySessionKey ? state.e2eSessions.get(replySessionKey) : undefined;
+            const plainMsg = JSON.stringify({
+                type: "message",
+                role: "assistant",
+                content: outText,
+                sessionKey: replySessionKey,
+            });
+            let outMsg: string;
+            if (sessionE2E?.ready) {
+                const encrypted = JSON.parse(await e2eEncrypt(sessionE2E, plainMsg));
+                encrypted.sessionKey = replySessionKey;
+                outMsg = JSON.stringify(encrypted);
+            } else {
+                outMsg = 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) => {
+            const 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;
+            }
+
+            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;
+    }
+    // Clear all per-session E2E states — new handshakes needed on reconnect
+    state.e2eSessions.clear();
+}
+
+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,
+        });
+
+        // E2E handshakes are initiated per-session when `peer_joined` arrives
+        // (each app connection carries its own sessionKey UUID).
+    });
+
+    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 session joined — initiate per-session E2E handshake
+    // 프로토콜: plugin이 먼저 handshake를 보내고, app이 자신의 pubkey로 응답.
+    // peer_joined가 중복으로 올 수 있으므로 이미 진행 중인 세션은 재시작하지 않음.
+    if (msg.type === "peer_joined") {
+        const sessionKey = msg.sessionKey as string | undefined;
+        if (!sessionKey) {
+            ctx.log?.warn?.(`[${CHANNEL_ID}] [${accountId}] [E2E] peer_joined missing sessionKey, ignoring`);
+            return;
+        }
+        // 이미 해당 session E2E가 진행 중이면 재시작하지 않음 (중복 peer_joined 방지)
+        if (state.e2eSessions.has(sessionKey)) {
+            ctx.log?.info?.(`[${CHANNEL_ID}] [${accountId}] [E2E] Session ${sessionKey} already exists, skipping duplicate peer_joined`);
+            return;
+        }
+        ctx.log?.info?.(`[${CHANNEL_ID}] [${accountId}] [E2E] App session joined (${sessionKey}), sending handshake`);
+        const sessionE2E = makeE2EState();
+        state.e2eSessions.set(sessionKey, sessionE2E);
+        const handshakeMsg = await e2eInit(sessionE2E);
+        // sessionKey를 포함시켜 relay가 올바른 app으로 라우팅하도록 함
+        const handshakeWithSession = JSON.stringify({ ...JSON.parse(handshakeMsg), sessionKey });
+        if (state.ws?.readyState === WebSocket.OPEN) {
+            state.ws.send(handshakeWithSession);
+        }
+        return;
+    }
+
+    // App의 handshake 응답 수신 — ECDH 완성
+    if (msg.type === "handshake") {
+        const sessionKey = msg.sessionKey as string | undefined;
+        const peerPubKey = msg.pubkey as string | undefined;
+        if (!sessionKey || !peerPubKey) {
+            ctx.log?.warn?.(`[${CHANNEL_ID}] [${accountId}] [E2E] Handshake missing sessionKey or pubkey`);
+            return;
+        }
+        let sessionE2E = state.e2eSessions.get(sessionKey);
+        if (!sessionE2E) {
+            // peer_joined 없이 app이 먼저 handshake를 보낸 경우 (예: plugin 재연결)
+            // 새 세션을 만들고 plugin의 pubkey를 먼저 전송한 후 ECDH 완성
+            sessionE2E = makeE2EState();
+            state.e2eSessions.set(sessionKey, sessionE2E);
+            const handshakeMsg = await e2eInit(sessionE2E);
+            const handshakeWithSession = JSON.stringify({ ...JSON.parse(handshakeMsg), sessionKey });
+            if (state.ws?.readyState === WebSocket.OPEN) {
+                state.ws.send(handshakeWithSession);
+                ctx.log?.info?.(`[${CHANNEL_ID}] [${accountId}] [E2E] Session ${sessionKey} — sent handshake (reactive, no prior peer_joined)`);
+            }
+        }
+        if (sessionE2E.ready) {
+            ctx.log?.info?.(`[${CHANNEL_ID}] [${accountId}] [E2E] Session ${sessionKey} already ready, ignoring duplicate handshake`);
+            return;
+        }
+        if (!sessionE2E.localKeyPair) {
+            ctx.log?.warn?.(`[${CHANNEL_ID}] [${accountId}] [E2E] Session ${sessionKey} has no local keypair yet, dropping handshake`);
+            return;
+        }
+        await e2eHandleHandshake(sessionE2E, peerPubKey);
+        ctx.log?.info?.(`[${CHANNEL_ID}] [${accountId}] [E2E] Session ${sessionKey} handshake complete`);
+        return;
+    }
+
+    // E2E encrypted message — decrypt using the per-session key
+    if (msg.type === "encrypted") {
+        const sessionKey = msg.sessionKey as string | undefined;
+        if (!sessionKey) {
+            ctx.log?.warn?.(`[${CHANNEL_ID}] [${accountId}] [E2E] Encrypted msg missing sessionKey, dropping`);
+            return;
+        }
+        const sessionE2E = state.e2eSessions.get(sessionKey);
+        if (!sessionE2E?.ready) {
+            ctx.log?.warn?.(`[${CHANNEL_ID}] [${accountId}] [E2E] Session ${sessionKey} not ready, dropping`);
+            return;
+        }
+        const plaintext = await e2eDecrypt(sessionE2E, msg.nonce, msg.ct);
+        ctx.log?.info?.(`[${CHANNEL_ID}] [${accountId}] [E2E] Session ${sessionKey} decrypted: ${plaintext.slice(0, 200)}`);
+        const innerMsg = JSON.parse(plaintext);
+        // Preserve sessionKey through decryption so handleInbound can use it
+        if (!innerMsg.sessionKey) innerMsg.sessionKey = sessionKey;
+        await handleInbound(ctx, accountId, innerMsg);
+        return;
+    }
+
+    // Plaintext message (no E2E or during handshake)
+    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() });
+
+    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);
+                    // The relay routes plugin→app by sessionKey in the JSON payload
+                    const replySessionKey = appSessionKey ?? sessionKey;
+                    const sessionE2E = relayState.e2eSessions.get(replySessionKey);
+                    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 with the per-session key if handshake is complete.
+                        // The outer envelope must carry sessionKey so the relay can route
+                        // the message to the correct app connection.
+                        let outMsg: string;
+                        if (sessionE2E?.ready) {
+                            const encrypted = JSON.parse(await e2eEncrypt(sessionE2E, plainMsg));
+                            encrypted.sessionKey = replySessionKey;
+                            outMsg = JSON.stringify(encrypted);
+                        } else {
+                            outMsg = 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 });
+
+    // On gateway start, ensure the default account config exists so the
+    // Control UI shows pre-filled values without any manual JSON editing.
+    api.on("gateway_start", async () => {
+        try {
+            const runtime = pluginRuntime;
+            if (!runtime) return;
+
+            const cfg = runtime.config.loadConfig();
+            const existing = cfg.channels?.[CHANNEL_ID]?.accounts?.[DEFAULT_ACCOUNT_ID];
+
+            // Only write defaults if the account entry is completely absent
+            if (existing !== undefined) return;
+
+            const patched = {
+                ...cfg,
+                channels: {
+                    ...cfg.channels,
+                    [CHANNEL_ID]: {
+                        ...(cfg.channels?.[CHANNEL_ID] ?? {}),
+                        accounts: {
+                            ...(cfg.channels?.[CHANNEL_ID]?.accounts ?? {}),
+                            [DEFAULT_ACCOUNT_ID]: {
+                                enabled: true,
+                                relayUrl: DEFAULT_RELAY_URL,
+                                roomId: DEFAULT_ROOM_ID,
+                            },
+                        },
+                    },
+                },
+            };
+
+            await runtime.config.writeConfigFile(patched);
+            api.logger?.info?.(`[openclaw-mobile] Wrote default account config (relayUrl=${DEFAULT_RELAY_URL}, roomId=${DEFAULT_ROOM_ID})`);
+        } catch (err) {
+            api.logger?.warn?.(`[openclaw-mobile] Could not write default config: ${err}`);
+        }
+    });
+
+    api.logger?.info?.("[openclaw-mobile] Plugin registered");
+}

package/openclaw.plugin.json

@@ -0,0 +1,42 @@
+{
+    "id": "openclaw-app",
+    "name": "OpenClaw App",
+    "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,31 @@
+{
+    "name": "openclaw-app",
+    "version": "1.0.0",
+    "description": "OpenClaw Mobile channel plugin — relay bridge for the OpenClaw Mobile app",
+    "main": "index.ts",
+    "type": "module",
+    "openclaw": {
+        "plugin": "./openclaw.plugin.json",
+        "extensions": [
+            "./index.ts"
+        ]
+    },
+    "keywords": [
+        "openclaw",
+        "plugin",
+        "channel",
+        "mobile"
+    ],
+    "license": "MIT",
+    "devDependencies": {
+        "typescript": "^5.7.0"
+    },
+    "peerDependencies": {
+        "openclaw": "*"
+    },
+    "peerDependenciesMeta": {
+        "openclaw": {
+            "optional": true
+        }
+    }
+}

package/tsconfig.json

@@ -0,0 +1,44 @@
+{
+  // Visit https://aka.ms/tsconfig to read more about this file
+  "compilerOptions": {
+    // File Layout
+    // "rootDir": "./src",
+    // "outDir": "./dist",
+
+    // Environment Settings
+    // See also https://aka.ms/tsconfig/module
+    "module": "nodenext",
+    "target": "esnext",
+    "types": [],
+    // For nodejs:
+    // "lib": ["esnext"],
+    // "types": ["node"],
+    // and npm install -D @types/node
+
+    // Other Outputs
+    "sourceMap": true,
+    "declaration": true,
+    "declarationMap": true,
+
+    // Stricter Typechecking Options
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+
+    // Style Options
+    // "noImplicitReturns": true,
+    // "noImplicitOverride": true,
+    // "noUnusedLocals": true,
+    // "noUnusedParameters": true,
+    // "noFallthroughCasesInSwitch": true,
+    // "noPropertyAccessFromIndexSignature": true,
+
+    // Recommended Options
+    "strict": true,
+    "jsx": "react-jsx",
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "noUncheckedSideEffectImports": true,
+    "moduleDetection": "force",
+    "skipLibCheck": true,
+  }
+}