openclaw-mobile 1.0.2 → 1.0.3

package/README.md

@@ -1,4 +1,4 @@
-# openclaw-mobile
+# @openclaw/mobile
 
 OpenClaw channel plugin for the Mobile app. Routes messages through a Cloudflare Worker relay.
 
@@ -8,66 +8,61 @@ OpenClaw channel plugin for the Mobile app. Routes messages through a Cloudflare
 Mobile App ←WS→ [CF Worker / Durable Object] ←WS→ [OpenClaw Plugin] → Gateway Pipeline
 ```
 
-1. The plugin registers an `openclaw-mobile` channel with the Gateway and connects to the relay as `role=plugin`.
-2. Each mobile app session connects to the relay as `role=app&session=<uuid>` with its own UUID.
-3. **App → Plugin**: the relay stamps every inbound message with the sender's `sessionKey`, then forwards to the plugin.
-4. **Plugin → App**: the plugin echoes `sessionKey` in every reply; the relay delivers it only to the matching app session.
-5. Multiple users can share the same relay without message cross-talk — isolation is per `sessionKey`, not per room.
-6. AI replies go through `outbound.sendText` — Gateway automatically filters security markers and thinking blocks.
-7. A 30-second ping keepalive prevents the Cloudflare Durable Object from hibernating.
+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
 
-```bash
-openclaw plugins install openclaw-mobile
-```
-
-That's it. The plugin ships with a built-in public relay — **no configuration required to get started**.
-
-## Quick Start
-
-### 1. Install the plugin
+From npm (when published):
 
 ```bash
-openclaw plugins install openclaw-mobile
+openclaw plugins install @openclaw/mobile
 ```
 
-### 2. Start the Gateway
+For local development:
 
 ```bash
-openclaw gateway
+openclaw plugins install -l ./plugin
 ```
 
-The `openclaw-mobile` channel will appear in the Control UI at http://127.0.0.1:18789/ with status **Running: Yes** and **Connected: Yes**.
-
-### 3. Connect the mobile app
+## Quick Start
 
-The app connects directly to the relay — no QR code or pairing step needed:
+### 1. Deploy the relay
 
-```
-wss://openclaw-relay.eldermoo8718.workers.dev/ws?role=app&room=default&session=<uuid>
+```bash
+cd relay
+npm install
+npx wrangler deploy
 ```
 
-The app generates its own `session` UUID on first launch and reuses it. Each session is fully isolated.
+Note the deployed URL (e.g. `wss://openclaw-relay.your-name.workers.dev`).
 
-### 4. Verify
+If you want relay authentication, set a secret:
 
-Open the Control UI and navigate to the **OpenClaw Mobile** channel. You should see:
+```bash
+npx wrangler secret put RELAY_TOKEN
+```
 
-- **Running**: Yes
-- **Configured**: Yes
-- **Connected**: Yes
+### 2. Install the plugin
 
-## Configuration
+```bash
+openclaw plugins install -l ./plugin
+```
 
-Configuration is optional. The plugin works out of the box with the built-in public relay.
+### 3. Configure
 
-To use your own self-hosted relay, add to `~/.openclaw/openclaw.json`:
+Add to `~/.openclaw/openclaw.json`:
 
 ```json
 {
@@ -75,8 +70,10 @@ To use your own self-hosted relay, add to `~/.openclaw/openclaw.json`:
     "openclaw-mobile": {
       "accounts": {
         "default": {
-          "relayUrl": "wss://your-relay.workers.dev",
-          "relayToken": "your-secret-token"
+          "enabled": true,
+          "relayUrl": "wss://openclaw-relay.your-name.workers.dev",
+          "relayToken": "your-secret-token",
+          "roomId": "default"
         }
       }
     }
@@ -84,66 +81,74 @@ To use your own self-hosted relay, add to `~/.openclaw/openclaw.json`:
 }
 ```
 
-You can also edit these fields in the Control UI config form — changes take effect immediately without restarting the Gateway.
+### 4. Restart the Gateway
 
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `enabled` | boolean | `true` | Enable/disable this account |
-| `relayUrl` | string | built-in public relay | CF Worker relay WebSocket URL |
-| `relayToken` | string | `""` | Shared secret (only needed for self-hosted relay with auth) |
+```bash
+openclaw gateway stop
+openclaw gateway --port 18789
+```
 
-## Self-hosting the relay
+### 5. Verify
 
-If you want to run your own relay instead of using the built-in public one:
+Open the Control UI at http://127.0.0.1:18789/ and navigate to the **OpenClaw Mobile** channel page. You should see:
 
-```bash
-cd relay
-npm install
-npx wrangler deploy
-```
+- **Running**: Yes
+- **Configured**: Yes
+- **Connected**: Yes
 
-Note the deployed URL and set it as `relayUrl` in your config. To add authentication:
+You can also check logs:
 
 ```bash
-npx wrangler secret put RELAY_TOKEN
+tail -f ~/.openclaw/logs/gateway.log | grep openclaw-mobile
 ```
 
-Then set the same value as `relayToken` in your config.
+## 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, and an Enable/Disable toggle
+- **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`):
 
-- The plugin connects as `role=plugin`.
-- Each app session connects as `role=app&session=<uuid>`.
-- **App → Plugin**: the relay injects `sessionKey` into the message JSON before forwarding.
-- **Plugin → App**: the relay reads `sessionKey` from the reply and delivers only to the matching app WebSocket.
-- The DO uses `setWebSocketAutoResponse("ping", "pong")` for keepalive without waking from hibernation.
-- Optional `RELAY_TOKEN` secret gates access to the relay.
+- 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)
 
-The app sends:
-
 ```json
 {
   "type": "message",
   "content": "Hello",
+  "sessionKey": "relay-session",
   "senderId": "mobile-user",
   "senderName": "Mobile User"
 }
 ```
 
-The relay automatically stamps `sessionKey` from the `?session=` query param. The app does not need to include it.
+- `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)
 
@@ -152,25 +157,24 @@ The relay automatically stamps `sessionKey` from the `?session=` query param. Th
   "type": "message",
   "role": "assistant",
   "content": "AI reply text",
-  "sessionKey": "<uuid>"
+  "sessionKey": "relay-session"
 }
 ```
 
-The relay uses `sessionKey` to route the reply only to the originating app session.
-
-## E2E Encryption
-
-The plugin performs an X25519 ECDH key exchange with each app session independently, deriving a per-session AES-256-GCM key via HKDF-SHA256. All messages after the handshake are encrypted. Each session has its own key.
+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 | `relayUrl` unreachable | Check logs; verify the relay Worker is deployed |
-| Connected: No | Relay URL wrong or Worker not deployed | Verify with `curl https://openclaw-relay.eldermoo8718.workers.dev/health` |
-| App messages not received | App not sending `?session=<uuid>` | Ensure the app includes a `session` query param when connecting |
+| 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
 
@@ -185,5 +189,5 @@ openclaw channels status --probe
 tail -f ~/.openclaw/logs/gateway.log | grep openclaw-mobile
 
 # Verify relay is reachable
-curl https://openclaw-relay.eldermoo8718.workers.dev/health
+curl https://openclaw-relay.your-name.workers.dev/health
 ```

package/index.ts

@@ -1,15 +1,9 @@
 /**
  * OpenClaw Mobile Channel Plugin
  *
- * Bridges Gateway ↔ CF Worker relay ↔ Mobile App via WebSocket.
- *
- * Routing model (no QR pairing):
- *   - Plugin connects to the relay as "plugin" role using the configured relayUrl.
- *   - Each mobile app session connects as "app" role with its own sessionKey UUID.
- *   - The relay stamps every inbound app message with the sender's sessionKey.
- *   - The plugin echoes that sessionKey back in every reply so the relay routes
- *     the response only to the originating app session.
- *   - Multiple app sessions share the same relay room without interference.
+ * 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):
  *   {
@@ -19,7 +13,8 @@
  *           "default": {
  *             "enabled": true,
  *             "relayUrl": "wss://openclaw-relay.xxx.workers.dev",
- *             "relayToken": "your-secret"
+ *             "relayToken": "your-secret",
+ *             "roomId": "default"
  *           }
  *         }
  *       }
@@ -27,14 +22,15 @@
  *   }
  */
 
-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;
@@ -59,16 +55,29 @@ function makeE2EState(): E2EState {
 
 async function e2eInit(state: E2EState): Promise<string> {
     const algo = await getX25519Algo();
-    state.localKeyPair = await crypto.subtle.generateKey(algo.gen, true, ["deriveKey"]);
+    state.localKeyPair = await crypto.subtle.generateKey(
+        algo.gen,
+        true,
+        ["deriveKey"]
+    );
     const pubKeyRaw = await crypto.subtle.exportKey("raw", state.localKeyPair.publicKey);
-    return JSON.stringify({ type: "handshake", pubkey: bufToBase64Url(pubKeyRaw) });
+    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 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,
@@ -77,29 +86,51 @@ async function e2eHandleHandshake(state: E2EState, peerPubKeyB64: string): Promi
         ["encrypt", "decrypt"]
     );
     const ecdhRawBytes = await crypto.subtle.exportKey("raw", ecdhRawKey);
-    const hkdfKey = await crypto.subtle.importKey("raw", ecdhRawBytes as ArrayBuffer, { name: "HKDF" }, false, ["deriveKey"]);
+
+    // 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") },
+        {
+            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) });
+    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);
+    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);
 }
 
@@ -119,26 +150,6 @@ function base64UrlToBuf(b64: string): Uint8Array {
     return bytes;
 }
 
-// ── Per-session E2E state ────────────────────────────────────────────────────
-//
-// Each app session gets its own E2E key exchange. The plugin maintains a map
-// of sessionKey → E2EState so concurrent sessions are independently encrypted.
-
-const sessionE2E = new Map<string, E2EState>();
-
-function getSessionE2E(sessionKey: string): E2EState {
-    let state = sessionE2E.get(sessionKey);
-    if (!state) {
-        state = makeE2EState();
-        sessionE2E.set(sessionKey, state);
-    }
-    return state;
-}
-
-function dropSessionE2E(sessionKey: string): void {
-    sessionE2E.delete(sessionKey);
-}
-
 // ── Relay state (per account) ────────────────────────────────────────────────
 
 interface RelayState {
@@ -147,20 +158,25 @@ interface RelayState {
     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;
+const PING_INTERVAL = 30_000; // 30s keepalive — prevents DO hibernation
 const DEFAULT_ACCOUNT_ID = "default";
 const CHANNEL_ID = "openclaw-mobile";
-const DEFAULT_RELAY_URL = "wss://openclaw-relay.eldermoo8718.workers.dev";
 
 function getRelayState(accountId: string): RelayState {
     let state = relayStates.get(accountId);
     if (!state) {
-        state = { ws: null, reconnectTimer: null, pingTimer: null, statusSink: null, gatewayCtx: null };
+        state = { ws: null, reconnectTimer: null, pingTimer: null, statusSink: null, gatewayCtx: null, e2eSessions: new Map() };
         relayStates.set(accountId, state);
     }
     return state;
@@ -173,25 +189,27 @@ interface ResolvedAccount {
     enabled: boolean;
     relayUrl: string;
     relayToken: string;
-    room: string;
+    roomId: string;
     configured: boolean;
 }
 
 function listAccountIds(cfg: any): string[] {
-    return Object.keys(cfg.channels?.[CHANNEL_ID]?.accounts ?? {});
+    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] ?? {};
-    const relayUrl = acct.relayUrl || DEFAULT_RELAY_URL;
+    const acct =
+        cfg.channels?.[CHANNEL_ID]?.accounts?.[id] ?? {};
     return {
         accountId: id,
         enabled: acct.enabled !== false,
-        relayUrl,
+        relayUrl: acct.relayUrl ?? "",
         relayToken: acct.relayToken ?? "",
-        room: acct.room || "default",
-        configured: true, // always configured — default relay is built-in
+        roomId: acct.roomId ?? "default",
+        configured: Boolean(acct.relayUrl),
     };
 }
 
@@ -216,9 +234,9 @@ const mobileConfigSchema = {
                             type: "string" as const,
                             description: "Shared secret for relay authentication",
                         },
-                        room: {
+                        roomId: {
                             type: "string" as const,
-                            description: "Relay room name — isolates this gateway from others sharing the same relay",
+                            description: "Room ID for relay routing",
                         },
                     },
                     additionalProperties: false,
@@ -230,14 +248,14 @@ const mobileConfigSchema = {
     uiHints: {
         relayUrl: {
             label: "Relay URL",
-            placeholder: DEFAULT_RELAY_URL,
+            placeholder: "wss://openclaw-relay.xxx.workers.dev",
         },
         relayToken: {
             label: "Relay Token",
             sensitive: true,
         },
-        room: {
-            label: "Room",
+        roomId: {
+            label: "Room ID",
             placeholder: "default",
         },
     },
@@ -262,7 +280,8 @@ const channel = {
     configSchema: mobileConfigSchema,
     config: {
         listAccountIds: (cfg: any) => listAccountIds(cfg),
-        resolveAccount: (cfg: any, accountId?: string) => resolveAccount(cfg, accountId),
+        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;
@@ -274,7 +293,13 @@ const channel = {
                     ...cfg.channels,
                     [CHANNEL_ID]: {
                         ...base,
-                        accounts: { ...accounts, [key]: { ...accounts[key], enabled } },
+                        accounts: {
+                            ...accounts,
+                            [key]: {
+                                ...accounts[key],
+                                enabled,
+                            },
+                        },
                     },
                 },
             };
@@ -301,17 +326,32 @@ const channel = {
             let outText = text ?? "";
             if (runtime) {
                 const cfg = runtime.config.loadConfig();
-                const tableMode = runtime.channel.text.resolveMarkdownTableMode({ cfg, channel: CHANNEL_ID, accountId: aid });
+                const tableMode = runtime.channel.text.resolveMarkdownTableMode({
+                    cfg,
+                    channel: CHANNEL_ID,
+                    accountId: aid,
+                });
                 outText = runtime.channel.text.convertMarkdownTables(outText, tableMode);
             }
 
-            const sessionKey = session?.key ?? null;
-            const plainMsg = JSON.stringify({ type: "message", role: "assistant", content: outText, sessionKey });
-            const e2e = sessionKey ? sessionE2E.get(sessionKey) : null;
-            const outMsg = e2e?.ready ? await e2eEncrypt(e2e, plainMsg) : plainMsg;
+            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,
+            });
+            const outMsg = sessionE2E?.ready
+                ? await e2eEncrypt(sessionE2E, plainMsg)
+                : plainMsg;
             state.ws.send(outMsg);
 
-            return { channel: CHANNEL_ID, to: to ?? "mobile-user", messageId: `mobile-${Date.now()}` };
+            return {
+                channel: CHANNEL_ID,
+                to: to ?? "mobile-user",
+                messageId: `mobile-${Date.now()}`,
+            };
         },
     },
 
@@ -338,7 +378,6 @@ const channel = {
             enabled: account.enabled,
             configured: account.configured,
             relayUrl: account.relayUrl || "(not set)",
-            room: account.room || "default",
             running: runtime?.running ?? false,
             connected: runtime?.connected ?? false,
             lastStartAt: runtime?.lastStartAt ?? null,
@@ -358,7 +397,8 @@ const channel = {
             cleanupRelay(state);
 
             state.gatewayCtx = ctx;
-            state.statusSink = (patch: Record<string, unknown>) => ctx.setStatus({ accountId, ...patch });
+            state.statusSink = (patch: Record<string, unknown>) =>
+                ctx.setStatus({ accountId, ...patch });
 
             ctx.setStatus({ accountId, running: true, lastStartAt: new Date().toISOString() });
 
@@ -383,8 +423,15 @@ const channel = {
         },
         stopAccount: async (ctx: any) => {
             const accountId = ctx.account?.accountId ?? DEFAULT_ACCOUNT_ID;
-            cleanupRelay(getRelayState(accountId));
-            ctx.setStatus?.({ accountId, running: false, connected: false, lastStopAt: new Date().toISOString() });
+            const state = getRelayState(accountId);
+            cleanupRelay(state);
+
+            ctx.setStatus?.({
+                accountId,
+                running: false,
+                connected: false,
+                lastStopAt: new Date().toISOString(),
+            });
             ctx.log?.info?.(`[${CHANNEL_ID}] [${accountId}] stopped`);
         },
     },
@@ -393,11 +440,20 @@ const channel = {
 // ── 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; }
-    // Drop all per-session E2E state
-    sessionE2E.clear();
+    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) {
@@ -405,7 +461,10 @@ function connectRelay(ctx: any, account: ResolvedAccount) {
     const state = getRelayState(accountId);
 
     const base = account.relayUrl.replace(/\/$/, "");
-    const params = new URLSearchParams({ role: "plugin", room: account.room });
+    const params = new URLSearchParams({
+        role: "plugin",
+        room: account.roomId,
+    });
     if (account.relayToken) params.set("token", account.relayToken);
 
     const url = `${base}/ws?${params.toString()}`;
@@ -423,25 +482,48 @@ function connectRelay(ctx: any, account: ResolvedAccount) {
 
     state.ws.addEventListener("open", () => {
         ctx.log?.info?.(`[${CHANNEL_ID}] [${accountId}] Relay connected`);
-        if (state.reconnectTimer) { clearTimeout(state.reconnectTimer); state.reconnectTimer = null; }
+        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");
+            if (state.ws?.readyState === WebSocket.OPEN) {
+                state.ws.send("ping");
+            }
         }, PING_INTERVAL);
-        state.statusSink?.({ connected: true, lastConnectedAt: new Date().toISOString(), lastError: null });
+
+        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}`);
+            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...`);
+        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() });
+        if (state.pingTimer) {
+            clearInterval(state.pingTimer);
+            state.pingTimer = null;
+        }
+        state.statusSink?.({
+            connected: false,
+            lastDisconnect: new Date().toISOString(),
+        });
         scheduleReconnect(ctx, account);
     });
 
@@ -461,22 +543,29 @@ function scheduleReconnect(ctx: any, account: ResolvedAccount) {
 }
 
 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);
 
-    // New app session joined — initiate E2E handshake for that session
+    // App session joined — initiate per-session E2E handshake
     if (msg.type === "peer_joined") {
         const sessionKey = msg.sessionKey as string | undefined;
-        ctx.log?.info?.(`[${CHANNEL_ID}] [${accountId}] [E2E] App session joined (sessionKey=${sessionKey}), sending handshake`);
-        if (sessionKey) dropSessionE2E(sessionKey);
-        const e2eState = sessionKey ? getSessionE2E(sessionKey) : makeE2EState();
-        const handshakeMsg = await e2eInit(e2eState);
-        // Wrap handshake with the sessionKey so the relay routes it to the right app
-        const wrappedHandshake = JSON.stringify({ ...JSON.parse(handshakeMsg), sessionKey });
-        if (state.ws?.readyState === WebSocket.OPEN) state.ws.send(wrappedHandshake);
+        if (!sessionKey) {
+            ctx.log?.warn?.(`[${CHANNEL_ID}] [${accountId}] [E2E] peer_joined missing sessionKey, ignoring`);
+            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);
+        // Attach sessionKey so the relay can route the handshake back to the right app
+        const handshakeWithSession = JSON.stringify({ ...JSON.parse(handshakeMsg), sessionKey });
+        if (state.ws?.readyState === WebSocket.OPEN) {
+            state.ws.send(handshakeWithSession);
+        }
         return;
     }
 
@@ -484,34 +573,44 @@ async function handleRelayMessage(ctx: any, accountId: string, state: RelayState
     if (msg.type === "handshake") {
         const sessionKey = msg.sessionKey as string | undefined;
         const peerPubKey = msg.pubkey as string | undefined;
-        if (!peerPubKey) {
-            ctx.log?.warn?.(`[${CHANNEL_ID}] [${accountId}] [E2E] Handshake missing pubkey`);
+        if (!sessionKey || !peerPubKey) {
+            ctx.log?.warn?.(`[${CHANNEL_ID}] [${accountId}] [E2E] Handshake missing sessionKey or pubkey`);
             return;
         }
-        const e2eState = sessionKey ? getSessionE2E(sessionKey) : makeE2EState();
-        await e2eHandleHandshake(e2eState, peerPubKey);
-        ctx.log?.info?.(`[${CHANNEL_ID}] [${accountId}] [E2E] Handshake complete for session=${sessionKey}`);
+        let sessionE2E = state.e2eSessions.get(sessionKey);
+        if (!sessionE2E) {
+            // App initiated handshake without a prior peer_joined (e.g. plugin reconnected)
+            sessionE2E = makeE2EState();
+            await e2eInit(sessionE2E);
+            state.e2eSessions.set(sessionKey, sessionE2E);
+        }
+        await e2eHandleHandshake(sessionE2E, peerPubKey);
+        ctx.log?.info?.(`[${CHANNEL_ID}] [${accountId}] [E2E] Session ${sessionKey} handshake complete`);
         return;
     }
 
-    // Encrypted message from an app session
+    // E2E encrypted message — decrypt using the per-session key
     if (msg.type === "encrypted") {
         const sessionKey = msg.sessionKey as string | undefined;
-        const e2eState = sessionKey ? sessionE2E.get(sessionKey) : null;
-        if (!e2eState?.ready) {
-            ctx.log?.warn?.(`[${CHANNEL_ID}] [${accountId}] [E2E] Encrypted msg but session not ready (session=${sessionKey}), dropping`);
+        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(e2eState, msg.nonce, msg.ct);
-        ctx.log?.info?.(`[${CHANNEL_ID}] [${accountId}] [E2E] Decrypted (session=${sessionKey}): ${plaintext.slice(0, 200)}`);
+        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 from the outer envelope
-        if (sessionKey && !innerMsg.sessionKey) innerMsg.sessionKey = sessionKey;
+        // Preserve sessionKey through decryption so handleInbound can use it
+        if (!innerMsg.sessionKey) innerMsg.sessionKey = sessionKey;
         await handleInbound(ctx, accountId, innerMsg);
         return;
     }
 
-    // Plaintext message
+    // Plaintext message (no E2E or during handshake)
     await handleInbound(ctx, accountId, msg);
 }
 
@@ -528,15 +627,13 @@ async function handleInbound(ctx: any, accountId: string, msg: any) {
 
     const runtime = pluginRuntime;
     if (!runtime) {
-        ctx.log?.error?.(`[${CHANNEL_ID}] [${accountId}] Plugin runtime not available`);
+        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);
-    // sessionKey from the relay-stamped message — used to route the reply back
-    const appSessionKey = msg.sessionKey ? String(msg.sessionKey) : null;
 
     try {
         const cfg = runtime.config.loadConfig();
@@ -548,26 +645,33 @@ async function handleInbound(ctx: any, accountId: string, msg: any) {
             peer: { kind: "direct", id: senderId },
         });
 
-        // Derive an isolated Gateway session per app sessionKey so each mobile
-        // conversation has its own context. Format: "agent:main:mobile-<uuid>"
-        let gatewaySessionKey: string;
+        // 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) : "";
-            gatewaySessionKey = `${agentPrefix}mobile-${appSessionKey}`;
+            const colonIdx = mainKey.lastIndexOf(':');
+            const agentPrefix = colonIdx > 0 ? mainKey.substring(0, colonIdx + 1) : '';
+            sessionKey = `${agentPrefix}mobile-${appSessionKey}`;
         } else {
-            gatewaySessionKey = route.mainSessionKey;
+            sessionKey = route.mainSessionKey;
         }
-
         const from = `${CHANNEL_ID}:${senderId}`;
         const to = `user:${senderId}`;
 
-        runtime.channel.activity.record({ channel: CHANNEL_ID, accountId, direction: "inbound" });
+        runtime.channel.activity.record({
+            channel: CHANNEL_ID,
+            accountId,
+            direction: "inbound",
+        });
 
         runtime.system.enqueueSystemEvent(
             `Mobile message from ${senderName}: ${text.slice(0, 160)}`,
-            { sessionKey: gatewaySessionKey, contextKey: `${CHANNEL_ID}:message:${Date.now()}` },
+            { sessionKey, contextKey: `${CHANNEL_ID}:message:${Date.now()}` },
         );
 
         const body = runtime.channel.reply.formatInboundEnvelope({
@@ -585,7 +689,7 @@ async function handleInbound(ctx: any, accountId: string, msg: any) {
             CommandBody: text,
             From: from,
             To: to,
-            SessionKey: gatewaySessionKey,
+            SessionKey: sessionKey,
             AccountId: accountId,
             ChatType: "direct",
             ConversationLabel: `Mobile DM from ${senderName}`,
@@ -597,8 +701,12 @@ async function handleInbound(ctx: any, accountId: string, msg: any) {
             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 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({
@@ -609,40 +717,58 @@ async function handleInbound(ctx: any, accountId: string, msg: any) {
                         ctx.log?.error?.(`[${CHANNEL_ID}] [${accountId}] Cannot deliver reply: relay not connected`);
                         return;
                     }
-                    const replyText = runtime.channel.text.convertMarkdownTables(payload.text ?? "", tableMode);
+                    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: appSessionKey,  // relay uses this to route to the right app
+                            sessionKey: replySessionKey,
                         });
-                        const e2e = appSessionKey ? sessionE2E.get(appSessionKey) : null;
-                        const outMsg = e2e?.ready ? await e2eEncrypt(e2e, plainMsg) : plainMsg;
+                        // Encrypt with the per-session key if handshake is complete
+                        const outMsg = sessionE2E?.ready
+                            ? await e2eEncrypt(sessionE2E, plainMsg)
+                            : plainMsg;
                         relayState.ws.send(outMsg);
                     }
-                    ctx.log?.info?.(`[${CHANNEL_ID}] [${accountId}] Reply delivered (${replyText.length} chars) to session=${appSessionKey}`);
+                    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 });
+        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 });
+        const storePath = runtime.channel.session.resolveStorePath(sessionCfg?.store, {
+            agentId: route.agentId,
+        });
         await runtime.channel.session.updateLastRoute({
             storePath,
-            sessionKey: gatewaySessionKey,
-            deliveryContext: { channel: CHANNEL_ID, to, accountId },
+            sessionKey,
+            deliveryContext: {
+                channel: CHANNEL_ID,
+                to,
+                accountId,
+            },
         });
 
-        ctx.log?.info?.(`[${CHANNEL_ID}] [${accountId}] Inbound processed, gatewaySession=${gatewaySessionKey} appSession=${appSessionKey}`);
+        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}`);
     }
@@ -654,36 +780,4 @@ export default function register(api: any) {
     pluginRuntime = api.runtime;
     api.registerChannel({ plugin: channel });
     api.logger?.info?.("[openclaw-mobile] Plugin registered");
-
-    // On first install (no channel config yet), write the default account so
-    // Control UI shows it immediately without requiring a gateway restart.
-    try {
-        const cfg = api.runtime.config.loadConfig();
-        const channelCfg = cfg.channels?.[CHANNEL_ID] ?? {};
-        const accounts = (channelCfg as any).accounts ?? {};
-        if (!accounts[DEFAULT_ACCOUNT_ID]) {
-            const updatedCfg = {
-                ...cfg,
-                channels: {
-                    ...cfg.channels,
-                    [CHANNEL_ID]: {
-                        ...channelCfg,
-                        accounts: {
-                            ...accounts,
-                            [DEFAULT_ACCOUNT_ID]: {
-                                enabled: true,
-                                relayUrl: DEFAULT_RELAY_URL,
-                                relayToken: "",
-                                room: "default",
-                            },
-                        },
-                    },
-                },
-            };
-            api.runtime.config.writeConfigFile(updatedCfg);
-            api.logger?.info?.(`[${CHANNEL_ID}] Wrote default account config on first install`);
-        }
-    } catch (err) {
-        api.logger?.warn?.(`[${CHANNEL_ID}] Could not write default account config: ${err}`);
-    }
 }

package/openclaw.plugin.json

@@ -12,30 +12,31 @@
         "properties": {
             "relayUrl": {
                 "type": "string",
-                "description": "CF Worker relay WebSocket URL. Leave empty to use the default public relay."
+                "description": "CF Worker relay WebSocket URL (e.g. wss://openclaw-relay.xxx.workers.dev)"
             },
             "relayToken": {
                 "type": "string",
-                "description": "Shared secret for relay authentication (only needed if you self-host the relay with a token)"
+                "description": "Shared secret for relay authentication"
             },
-            "room": {
+            "roomId": {
                 "type": "string",
-                "description": "Relay room name — isolates this gateway from others sharing the same relay (default: \"default\")"
+                "description": "Room ID for relay routing",
+                "default": "default"
             }
         }
     },
     "uiHints": {
         "relayUrl": {
             "label": "Relay URL",
-            "placeholder": "wss://openclaw-relay.eldermoo8718.workers.dev"
+            "placeholder": "wss://openclaw-relay.xxx.workers.dev"
         },
         "relayToken": {
             "label": "Relay Token",
             "sensitive": true
         },
-        "room": {
-            "label": "Room",
+        "roomId": {
+            "label": "Room ID",
             "placeholder": "default"
         }
     }
-}
+}

package/package.json

@@ -1,29 +1,31 @@
 {
-  "name": "openclaw-mobile",
-  "version": "1.0.2",
-  "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",
-  "devDependencies": {
-    "typescript": "^5.7.0"
-  },
-  "peerDependencies": {
-    "openclaw": "*"
-  },
-  "peerDependenciesMeta": {
+    "name": "openclaw-mobile",
+    "version": "1.0.3",
+    "description": "OpenClaw Mobile channel plugin — relay bridge for the OpenClaw Mobile app",
+    "main": "index.ts",
+    "type": "module",
     "openclaw": {
-      "optional": true
+        "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,
+  }
+}