openclaw/docs/webchat.md

# Web Chat architecture (local + remote)

Date: 2025-12-08 · Status: draft plan

## Goal
- Serve the Clawdis Web Chat UI from the Node relay (loopback-only HTTP), while the macOS app keeps the same UX by embedding it in a WKWebView.
- Keep remote mode working: when Clawdis runs on a remote host via SSH, the mac app should still show the web chat backed by that remote relay (via an SSH tunnel).

## Proposed architecture
1) **Server location**
   - A tiny HTTP server lives in the Node relay process.
   - Bind to 127.0.0.1 on a chosen port (fixed or random with discovery endpoint).
   - Serve static assets for `/webchat/` and a JSON RPC endpoint for sending messages.

2) **Endpoints**
   - `GET /webchat/*`: serves bundled web assets (current WebChat build, moved from mac bundle into the Node package, e.g., `src/webchat/dist`).
   - `GET /webchat/info`: returns `{ baseUrl, token? }` for the mac app to embed (token optional; see security below).
   - `POST /webchat/rpc`: accepts `{ text, session, thinking?, deliver?, to? }` and replies with `{ ok, payloads?, error? }`. Internally calls the same agent pipeline that `clawdis rpc` uses today (in-process, no subprocess).
   - (Optional) `GET /webchat/history?session=<key>`: returns pre-serialized message history so the mac app doesn’t scrape JSONL. Can be folded into `/webchat/info` as an `initialMessages` field.

3) **Sessions & history**
   - Use the relay’s own session store (default `~/.clawdis/sessions/sessions.json` on the relay host). No SSH file reads from the mac app anymore.
   - When the page loads, it receives `initialMessages` from the server (either embedded in `info` or via a history endpoint).
   - Remote mode automatically shows the remote session because the remote relay owns that store.

4) **Mac app embedding**
   - On WebChatWindow init, the mac app calls `/webchat/info`:
     - Local mode: directly over loopback (127.0.0.1:port chosen by relay).
     - Remote mode: establish/reuse an SSH tunnel forwarding the relay’s webchat port to a local ephemeral port, then call `/webchat/info` through the tunnel and load the returned `baseUrl`.
   - WKWebView loads `baseUrl` (e.g., `http://127.0.0.1:<forward>/webchat/`).
   - Web page sends messages to `/webchat/rpc` (same origin as the static assets), so no extra mac plumbing.

5) **Security**
   - Bind to loopback only. For extra hardening, issue a random short-lived token in `/webchat/info` and require it as a header/query on `/webchat/rpc` and history.
   - Remote mode relies on SSH port forwarding; no WAN exposure.

6) **Failure handling**
   - If `/webchat/info` fails, show an in-app error (“Web chat server unreachable”).
   - Log the chosen port/URL and tunnel target in mac logs for debugging.
   - History fetch failures fall back to an empty transcript but keep sending enabled.

7) **Migration steps**
   - Move WebChat bundle into the Node project (e.g., `src/webchat/dist`) and serve statically.
   - Add the loopback HTTP server and `/webchat` routes to the relay startup.
   - Expose `/webchat/info` (port + token + optional initialMessages).
   - Mac app: replace local asset load with the fetched `baseUrl`; use SSH tunnel in remote mode.
   - Remove mac-side JSONL scraping and `AgentRPC` usage for web chat; keep other agent uses intact.
   - Tests: webchat loads + sends in local and remote modes; tunnel discovery works; history returns non-empty when sessions exist.

8) **Current behavior (for reference, to be replaced)**
   - Mac app reads remote session files over SSH (`clawdis sessions --json`, then `cat` the `.jsonl`) and injects history; sends via `clawdis rpc` subprocess. This document tracks the plan to move both pieces into the relay server instead.

## Open questions
- Fixed port vs random per run? (Random + info endpoint is safer.)
- Token enforcement default on/off? (Recommended on when remote tunneling isn’t used.)
- Should `/webchat/rpc` also expose typing/streaming? (Nice-to-have; not required for parity.)