Vendor OpenClaw source as Adolf fork baseline

Adolf is a fork/vendored clone of github.com/openclaw/openclaw (v2026.6.11),
free to diverge. Tree copied sans upstream .git; upstream remote added for
future syncs. Node pinned to 24 (.nvmrc); engines already require >=22.19.
Preserves docs/ARCHITECTURE.md.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LeqyaxJF2nbRXJtae2kNB2

docs/web/control-ui.md

@@ -0,0 +1,549 @@
+---
+summary: "Browser-based control UI for the Gateway (chat, activity, nodes, config)"
+read_when:
+  - You want to operate the Gateway from a browser
+  - You want Tailnet access without SSH tunnels
+title: "Control UI"
+sidebarTitle: "Control UI"
+---
+
+The Control UI is a small **Vite + Lit** single-page app served by the Gateway:
+
+- default: `http://<host>:18789/`
+- optional prefix: set `gateway.controlUi.basePath` (e.g. `/openclaw`)
+
+It speaks **directly to the Gateway WebSocket** on the same port.
+
+## Quick open (local)
+
+If the Gateway is running on the same computer, open [http://127.0.0.1:18789/](http://127.0.0.1:18789/) (or [http://localhost:18789/](http://localhost:18789/)).
+
+If the page fails to load, start the Gateway first: `openclaw gateway`.
+
+<Note>
+On native Windows LAN binds, Windows Firewall or organization-managed Group Policy can still block the advertised LAN URL even when `127.0.0.1` works on the Gateway host. Run `openclaw gateway status --deep` on the Windows host; it reports likely-blocked ports, profile mismatches, and local firewall rules that policy may ignore.
+</Note>
+
+Auth is supplied during the WebSocket handshake via:
+
+- `connect.params.auth.token`
+- `connect.params.auth.password`
+- Tailscale Serve identity headers when `gateway.auth.allowTailscale: true`
+- trusted-proxy identity headers when `gateway.auth.mode: "trusted-proxy"`
+
+The dashboard settings panel keeps a token for the current browser tab session and selected gateway URL; passwords are not persisted. Onboarding usually generates a gateway token for shared-secret auth on first connect, but password auth works too when `gateway.auth.mode` is `"password"`.
+
+## Device pairing (first connection)
+
+Connecting from a new browser or device usually requires a **one-time pairing approval**, shown as `disconnected (1008): pairing required`.
+
+<Steps>
+  <Step title="List pending requests">
+    ```bash
+    openclaw devices list
+    ```
+  </Step>
+  <Step title="Approve by request ID">
+    ```bash
+    openclaw devices approve <requestId>
+    ```
+  </Step>
+</Steps>
+
+If the browser retries pairing with changed auth details (role/scopes/public key), the previous pending request is superseded and a new `requestId` is created; re-run `openclaw devices list` before approving.
+
+Switching an already-paired browser from read access to write/admin access is treated as an approval upgrade, not a silent reconnect: OpenClaw keeps the old approval active, blocks the broader reconnect, and asks you to approve the new scope set explicitly.
+
+Once approved, the device is remembered and won't require re-approval unless you revoke it with `openclaw devices revoke --device <id> --role <role>`. See [Devices CLI](/cli/devices) for token rotation, revocation, and the Paperclip / `openclaw_gateway` first-run approval flow.
+
+<Note>
+- Direct local loopback browser connections (`127.0.0.1` / `localhost`) are auto-approved.
+- Tailscale Serve can skip the pairing round trip for Control UI operator sessions when `gateway.auth.allowTailscale: true`, Tailscale identity verifies, and the browser presents its device identity. Device-less browsers and node-role connections still follow the normal device checks.
+- Direct Tailnet binds, LAN browser connects, and browser profiles without device identity still require explicit approval.
+- Each browser profile generates a unique device ID, so switching browsers or clearing browser data requires re-pairing.
+
+</Note>
+
+## Pair a mobile device
+
+An already paired administrator can create the iOS/Android connection QR without opening a terminal:
+
+<Steps>
+  <Step title="Open mobile pairing">
+    Select **Nodes**, then click **Pair mobile device** in the **Devices** card.
+  </Step>
+  <Step title="Connect the phone">
+    In the OpenClaw mobile app, open **Settings** → **Gateway** and scan the QR code. You can copy and paste the setup code instead.
+  </Step>
+  <Step title="Confirm the connection">
+    The official iOS/Android app connects automatically. If **Devices** shows a pending request, review its role and scopes before approving it.
+  </Step>
+</Steps>
+
+Creating a setup code requires `operator.admin`; the button is disabled for sessions without it. A setup code contains a short-lived bootstrap credential, so treat the QR and copied code like a password while they are valid. For remote pairing, the Gateway must resolve to `wss://` (for example, through Tailscale Serve/Funnel); plain `ws://` is limited to loopback and private LAN addresses. See [Pairing](/channels/pairing#pair-from-the-control-ui-recommended) for the full security and fallback details.
+
+## Personal identity (browser-local)
+
+The Control UI supports a per-browser personal identity (display name and avatar) attached to outgoing messages, for attribution in shared sessions. It lives in browser storage, scoped to the current browser profile, and is not synced to other devices or persisted server-side beyond the normal transcript authorship metadata on messages you send. Clearing site data or switching browsers resets it to empty.
+
+The assistant avatar override follows the same browser-local pattern: uploaded overrides overlay the gateway-resolved identity locally and never round-trip through `config.patch`. The shared `ui.assistant.avatar` config field is still available for non-UI clients that write the field directly.
+
+## Runtime config endpoint
+
+The Control UI fetches its runtime settings from `/control-ui-config.json`, resolved relative to the gateway's Control UI base path (for example `/__openclaw__/control-ui-config.json` under base path `/__openclaw__/`). That endpoint is gated by the same gateway auth as the rest of the HTTP surface: unauthenticated browsers cannot fetch it, and a successful fetch requires a valid gateway token/password, Tailscale Serve identity, or a trusted-proxy identity.
+
+## Language support
+
+The Control UI localizes itself on first load based on your browser locale. To override it later, open **Overview -> Gateway Access -> Language** (the picker lives in the Gateway Access card, not under Appearance).
+
+- Supported locales: `en`, `ar`, `de`, `es`, `fa`, `fr`, `hi`, `id`, `it`, `ja-JP`, `ko`, `nl`, `pl`, `pt-BR`, `ru`, `th`, `tr`, `uk`, `vi`, `zh-CN`, `zh-TW`
+- Non-English translations are lazy-loaded in the browser.
+- The selected locale is saved in browser storage and reused on future visits.
+- Missing translation keys fall back to English.
+
+Docs translations are generated for the same non-English locale set, but the docs site's built-in Mintlify language picker only lists locale codes Mintlify accepts. Thai (`th`) and Persian (`fa`) docs are still generated in the publish repo; they may not appear in that picker until Mintlify supports those codes.
+
+## Appearance themes
+
+The Appearance panel has the built-in Claw, Knot, and Dash themes (Claw is default), plus one browser-local tweakcn import slot. To import a theme, open the [tweakcn editor](https://tweakcn.com/editor/theme), choose or create a theme, click **Share**, and paste the copied link into Appearance. The importer also accepts `https://tweakcn.com/r/themes/<id>` registry URLs, editor URLs like `https://tweakcn.com/editor/theme?theme=amethyst-haze`, relative `/themes/<id>` paths, raw theme IDs, and default theme names such as `amethyst-haze`.
+
+Imported themes are stored only in the current browser profile; they are not written to gateway config and do not sync across devices. Replacing the imported theme updates the one local slot; clearing it switches back to Claw if the imported theme was active.
+
+Appearance also has a browser-local Text size setting, stored with the rest of Control UI preferences. It applies to chat text, composer text, tool cards, and chat sidebars, and keeps text inputs at least 16px so mobile Safari does not auto-zoom on focus.
+
+## What it can do (today)
+
+<AccordionGroup>
+  <Accordion title="Chat and Talk">
+    - Chat with the model via Gateway WS (`chat.history`, `chat.send`, `chat.abort`, `chat.inject`).
+    - Chat history refreshes request a bounded recent window with per-message text caps, so large sessions do not force the browser to render a full transcript payload before chat becomes usable.
+    - Talk through browser realtime sessions. OpenAI uses direct WebRTC, Google Live uses a constrained one-use browser token over WebSocket, and backend-only realtime voice plugins use the Gateway relay transport. Client-owned provider sessions start with `talk.client.create`; Gateway relay sessions start with `talk.session.create`. The relay keeps provider credentials on the Gateway while the browser streams microphone PCM through `talk.session.appendAudio`, forwards `openclaw_agent_consult` provider tool calls through `talk.client.toolCall` for Gateway policy and the larger configured OpenClaw model, and routes active-run voice steering through `talk.client.steer` or `talk.session.steer`.
+    - Stream tool calls and live tool output cards in Chat (agent events).
+    - Activity tab with browser-local, redaction-first summaries of live tool activity from existing `session.tool` / tool event delivery.
+
+  </Accordion>
+  <Accordion title="Channels, instances, sessions, dreams">
+    - Channels: built-in plus bundled/external plugin channels status, QR login, and per-channel config (`channels.status`, `web.login.*`, `config.patch`).
+    - Channel probe refreshes keep the previous snapshot visible while slow provider checks finish, and label partial snapshots when a probe or audit exceeds its UI budget.
+    - Instances: presence list and refresh (`system-presence`).
+    - Sessions: list configured-agent sessions by default, pin frequent sessions, rename them, archive or restore inactive sessions, fall back from stale unconfigured agent session keys, and apply per-session model/thinking/fast/verbose/trace/reasoning overrides (`sessions.list`, `sessions.patch`). Pinned sessions sort above recent unpinned sessions; archived sessions live in the Sessions page's archived view and keep their transcripts.
+    - Dreams: dreaming status, enable/disable toggle, and Dream Diary reader (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`).
+
+  </Accordion>
+  <Accordion title="Cron, skills, nodes, exec approvals">
+    - Cron jobs: list/add/edit/run/enable/disable plus run history (`cron.*`).
+    - Skills: status, enable/disable, install, API key updates (`skills.*`).
+    - Nodes: list plus caps (`node.list`), create mobile setup codes, and approve device pairing (`device.pair.*`).
+    - Exec approvals: edit gateway or node allowlists and ask policy for `exec host=gateway/node` (`exec.approvals.*`).
+
+  </Accordion>
+  <Accordion title="Config">
+    - View/edit `~/.openclaw/openclaw.json` (`config.get`, `config.set`).
+    - MCP has a dedicated settings page for configured servers, enablement, OAuth/filter/parallel summaries, common operator commands, and the scoped `mcp` config editor.
+    - Apply and restart with validation (`config.apply`), then wake the last active session.
+    - Writes include a base-hash guard to prevent clobbering concurrent edits.
+    - Writes (`config.set`/`config.apply`/`config.patch`) preflight active SecretRef resolution for refs in the submitted config payload; unresolved active submitted refs are rejected before write.
+    - Form saves discard stale redacted placeholders that cannot be restored from the saved config, while preserving redacted values that still map to saved secrets.
+    - Schema and form rendering come from `config.schema` / `config.schema.lookup`, including field `title`/`description`, matched UI hints, immediate child summaries, docs metadata on nested object/wildcard/array/composition nodes, plus plugin and channel schemas when available. Raw JSON editor is available only when the snapshot has a safe raw round-trip; otherwise Control UI forces Form mode.
+    - Raw JSON editor "Reset to saved" preserves the raw-authored shape (formatting, comments, `$include` layout) instead of re-rendering a flattened snapshot, so external edits survive a reset when the snapshot can safely round-trip.
+    - Structured SecretRef object values render read-only in form text inputs, to prevent accidental object-to-string corruption.
+
+  </Accordion>
+  <Accordion title="Debug, logs, update">
+    - Debug: status/health/models snapshots, event log, and manual RPC calls (`status`, `health`, `models.list`).
+    - The event log includes Control UI refresh/RPC timings, slow chat/config render timings, and browser responsiveness entries for long animation frames or long tasks when the browser exposes those PerformanceObserver entry types.
+    - Logs: live tail of gateway file logs with filter/export (`logs.tail`).
+    - Update: run a package/git update plus restart (`update.run`) with a restart report, then poll `update.status` after reconnect to verify the running gateway version.
+
+  </Accordion>
+  <Accordion title="Cron jobs panel notes">
+    - For isolated jobs, delivery defaults to announce summary; switch to none for internal-only runs.
+    - Channel/target fields appear when announce is selected.
+    - Webhook mode uses `delivery.mode = "webhook"` with `delivery.to` set to a valid HTTP(S) webhook URL.
+    - For main-session jobs, webhook and none delivery modes are available.
+    - Advanced edit controls include delete-after-run, clear agent override, cron exact/stagger options, agent model/thinking overrides, and best-effort delivery toggles.
+    - Form validation is inline with field-level errors; invalid values disable the save button until fixed.
+    - Set `cron.webhookToken` to send a dedicated bearer token; if omitted, the webhook is sent without an auth header.
+    - `cron.webhook` is a deprecated legacy fallback: run `openclaw doctor --fix` to migrate stored jobs that still use `notify: true` to explicit per-job webhook or completion delivery.
+
+  </Accordion>
+</AccordionGroup>
+
+## MCP page
+
+The dedicated MCP page is an operator view for OpenClaw-managed MCP servers under `mcp.servers`. It does not start MCP transports by itself; use it to inspect and edit saved config, then use `openclaw mcp doctor --probe` when you need live server proof.
+
+Typical workflow:
+
+1. Open **MCP** from the sidebar.
+2. Check the summary cards for total, enabled, OAuth, and filtered server counts.
+3. Review each server row for transport, enablement, auth, filters, timeouts, and command hints.
+4. Toggle enablement when a server should remain configured but stay out of runtime discovery.
+5. Edit the scoped `mcp` config section for server definitions, headers, TLS/mTLS paths, OAuth metadata, tool filters, and Codex projection metadata.
+6. Use **Save** for a config write, or **Save & Publish** when the running Gateway should apply the changed config.
+7. Run `openclaw mcp status --verbose`, `openclaw mcp doctor --probe`, or `openclaw mcp reload` from a terminal for static diagnostics, live proof, or cached-runtime disposal.
+
+The page redacts credential-bearing URL-like values before rendering and quotes server names in command snippets so copied commands still work with spaces or shell metacharacters. Full CLI and config reference: [MCP](/cli/mcp).
+
+## Activity tab
+
+The Activity tab is an ephemeral browser-local observer for live tool activity, derived from the same Gateway `session.tool` / tool event stream that powers Chat tool cards. It does not add another Gateway event family, endpoint, durable activity store, metrics feed, or external observer stream.
+
+Activity entries keep only sanitized summaries and redacted, truncated output previews. Tool argument values are not stored in Activity state; the UI shows that arguments are hidden and records only the argument field count. The in-memory list follows the current browser tab, survives navigation within the Control UI, and resets on page reload, session switch, or **Clear**.
+
+## Operator terminal
+
+The dockable operator terminal is disabled by default. To enable it, set `gateway.terminal.enabled: true` and restart the Gateway. The terminal requires an `operator.admin` connection and opens a host PTY in the active agent workspace. New tabs follow the currently selected chat agent.
+
+<Warning>
+The terminal is an unconfined host shell and inherits the Gateway process environment. Enable it only for trusted operator deployments. OpenClaw refuses terminal sessions for agents with `sandbox.mode: "all"`; changing an active agent to that mode closes its existing and in-flight terminal sessions.
+</Warning>
+
+Use **Ctrl + backtick** to toggle the dock. The layout supports bottom and right docking, resizes with the browser viewport, and keeps multiple shell tabs. See [Gateway configuration](/gateway/configuration-reference#gateway) for `gateway.terminal.enabled` and the optional `gateway.terminal.shell` override.
+
+Sessions survive disconnects: a page reload, laptop sleep, or network blip detaches the session on the Gateway instead of killing it, and the same browser tab reattaches on reconnect with recent output replayed. Detached sessions are killed after `gateway.terminal.detachedSessionTimeoutSeconds` (default 300 seconds; `0` restores kill-on-disconnect). `terminal.list` shows attachable sessions, `terminal.attach` adopts one (tmux-style take-over), and `terminal.text` reads a session's recent output as plain text without attaching - an agent/tooling affordance.
+
+The terminal is also available as a full-screen, terminal-only document at `/?view=terminal`. The iOS and Android apps embed this page in their Terminal screens, reusing the stored gateway credentials; availability follows the same `gateway.terminal.enabled` and `operator.admin` gate, and the page shows a notice when the connected Gateway does not offer the terminal.
+
+## Chat behavior
+
+<AccordionGroup>
+  <Accordion title="Send and history semantics">
+    - `chat.send` is **non-blocking**: it acks immediately with `{ runId, status: "started" }` and the response streams via `chat` events. Trusted Control UI clients may also receive optional ACK timing metadata for local diagnostics.
+    - Chat uploads accept images plus non-video files. Images keep the native image path; other files are stored as managed media and shown in history as attachment links.
+    - Re-sending with the same `idempotencyKey` returns `{ status: "in_flight" }` while running, and `{ status: "ok" }` after completion.
+    - `chat.history` responses are size-bounded for UI safety. When transcript entries are too large, Gateway may truncate long text fields, omit heavy metadata blocks, and replace oversized messages with a placeholder (`[chat.history omitted: message too large]`).
+    - When a visible assistant message was truncated in `chat.history`, the side reader can fetch the full display-normalized transcript entry on demand through `chat.message.get` by `sessionKey`, active `agentId` when needed, and transcript `messageId`. If the Gateway still cannot return more, the reader shows an explicit unavailable state instead of silently repeating the truncated preview.
+    - Assistant/generated images are persisted as managed media references and served back through authenticated Gateway media URLs, so reloads do not depend on raw base64 image payloads staying in the chat history response.
+    - When rendering `chat.history`, the Control UI strips display-only inline directive tags from visible assistant text (for example `[[reply_to_*]]` and `[[audio_as_voice]]`), plain-text tool-call XML payloads (including `<tool_call>...</tool_call>`, `<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>`, and truncated tool-call blocks), and leaked ASCII/full-width model control tokens. It omits assistant entries whose whole visible text is only the exact silent token `NO_REPLY` / `no_reply` or the heartbeat acknowledgement token `HEARTBEAT_OK`.
+    - During an active send and the final history refresh, the chat view keeps local optimistic user/assistant messages visible if `chat.history` briefly returns an older snapshot; the canonical transcript replaces those local messages once the Gateway history catches up.
+    - Live `chat` events are delivery state, while `chat.history` is rebuilt from the durable session transcript. After tool-final events the Control UI reloads history and merges only a small optimistic tail; the transcript boundary is documented in [WebChat](/web/webchat).
+    - `chat.inject` appends an assistant note to the session transcript and broadcasts a `chat` event for UI-only updates (no agent run, no channel delivery).
+    - The sidebar lists recent sessions with a New Session action, an All Sessions link, and a session search button that opens the full session picker (scoped by the selected agent, with search and pagination). A new dashboard session asynchronously gets a concise generated title from its first non-command message; explicit names are never replaced. Set `agents.defaults.utilityModel` (or `agents.list[].utilityModel`) to route this separate model call to a lower-cost model. Switching agents shows only sessions tied to that agent and falls back to that agent's main session when it has no saved dashboard sessions yet.
+    - Each session-picker row can rename, pin, or archive the session. An active run and an agent's main session cannot be archived. Archiving the currently selected session switches Chat back to that agent's main session.
+    - On desktop widths, chat controls stay on one compact row and collapse while scrolling down the transcript; scrolling up, returning to the top, or reaching the bottom restores the controls.
+    - Consecutive duplicate text-only messages render as one bubble with a count badge. Messages that carry images, attachments, tool output, or canvas previews are left uncollapsed.
+    - The chat header model and thinking pickers patch the active session immediately through `sessions.patch`; they are persistent session overrides, not one-turn-only send options.
+    - If you send a message while a model picker change for the same session is still saving, the composer waits for that session patch before calling `chat.send` so the send uses the selected model.
+    - Typing `/new` creates and switches to the same fresh dashboard session as New Chat, except when `session.dmScope: "main"` is configured and the current parent is the agent's main session; then it resets the main session in place. Typing `/reset` keeps the Gateway's explicit in-place reset for the current session.
+    - The chat model picker requests the Gateway's configured model view. If `agents.defaults.models` is present, that allowlist drives the picker, including `provider/*` entries that keep provider-scoped catalogs dynamic. Otherwise the picker shows explicit `models.providers.*.models` entries plus providers with usable auth. The full catalog stays available through the debug `models.list` RPC with `view: "all"`.
+    - When fresh Gateway session usage reports include current context tokens, the chat composer toolbar shows a small context usage ring with the used percentage; full token detail lives in its tooltip. The ring switches to warning styling at high context pressure and, at recommended compaction levels, shows a compact button that runs the normal session compaction path. Stale token snapshots are hidden until the Gateway reports fresh usage again.
+
+  </Accordion>
+  <Accordion title="Talk mode (browser realtime)">
+    Talk mode uses a registered realtime voice provider. Configure OpenAI with `talk.realtime.provider: "openai"` plus an `openai` API-key auth profile, `talk.realtime.providers.openai.apiKey`, or `OPENAI_API_KEY`; OpenAI OAuth profiles do not configure Realtime voice. Configure Google with `talk.realtime.provider: "google"` plus `talk.realtime.providers.google.apiKey`. The browser never receives a standard provider API key: OpenAI receives an ephemeral Realtime client secret for WebRTC, and Google Live receives a one-use constrained Live API auth token for a browser WebSocket session, with instructions and tool declarations locked into the token by the Gateway. Providers that only expose a backend realtime bridge run through the Gateway relay transport, so credentials and vendor sockets stay server-side while browser audio moves through authenticated Gateway RPCs. The Realtime session prompt is assembled by the Gateway; `talk.client.create` does not accept caller-provided instruction overrides.
+
+    The Chat composer includes a Talk options button next to the Talk start/stop button. Options apply to the next Talk session and can override provider, transport, model, voice, reasoning effort, VAD threshold, silence duration, and prefix padding. A blank option falls back to configured defaults or the provider default. Selecting Gateway relay forces the backend relay path; selecting WebRTC keeps the session client-owned and fails instead of silently falling back to relay if the provider cannot create a browser session.
+
+    The Talk control itself is the waves button next to the microphone dictation button. When Talk starts, the composer status row shows `Connecting Talk...`, then `Talk live` while audio is connected, or `Asking OpenClaw...` while a realtime tool call is consulting the configured larger model through `talk.client.toolCall`.
+
+    Maintainer live smoke: `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` verifies the OpenAI backend WebSocket bridge, OpenAI browser WebRTC SDP exchange, Google Live constrained-token browser WebSocket setup, and the Gateway relay browser adapter with fake microphone media. The command prints provider status only and does not log secrets.
+
+  </Accordion>
+  <Accordion title="Stop and abort">
+    - Click **Stop** (calls `chat.abort`).
+    - While a run is active, normal follow-ups queue. Click **Steer** on a queued message to inject that follow-up into the running turn.
+    - Type `/stop` (or standalone abort phrases like `stop`, `stop action`, `stop run`, `stop openclaw`, `please stop`) to abort out-of-band.
+    - `chat.abort` supports `{ sessionKey }` (no `runId`) to abort all active runs for that session.
+
+  </Accordion>
+  <Accordion title="Abort partial retention">
+    - When a run is aborted, partial assistant text can still be shown in the UI.
+    - Gateway persists aborted partial assistant text into transcript history when buffered output exists.
+    - Persisted entries include abort metadata so transcript consumers can tell abort partials from normal completion output.
+
+  </Accordion>
+</AccordionGroup>
+
+## PWA install and web push
+
+The Control UI ships a `manifest.webmanifest` and a service worker, so modern browsers can install it as a standalone PWA. Web Push lets the Gateway wake the installed PWA with notifications even when the tab or browser window is not open.
+
+If the page shows **Protocol mismatch** right after an OpenClaw update, first reopen the dashboard with `openclaw dashboard` and hard-refresh. If it still fails, clear site data for the dashboard origin or test in a private browser window; an old tab or browser service-worker cache can keep running a pre-update Control UI bundle against the newer Gateway.
+
+| Surface                                               | What it does                                                       |
+| ----------------------------------------------------- | ------------------------------------------------------------------ |
+| `ui/public/manifest.webmanifest`                      | PWA manifest. Browsers offer "Install app" once it is reachable.   |
+| `ui/public/sw.js`                                     | Service worker that handles `push` events and notification clicks. |
+| `push/vapid-keys.json` (under the OpenClaw state dir) | Auto-generated VAPID keypair used to sign Web Push payloads.       |
+| `push/web-push-subscriptions.json`                    | Persisted browser subscription endpoints.                          |
+
+Override the VAPID keypair through env vars on the Gateway process when you want to pin keys (multi-host deployments, secrets rotation, or tests):
+
+- `OPENCLAW_VAPID_PUBLIC_KEY`
+- `OPENCLAW_VAPID_PRIVATE_KEY`
+- `OPENCLAW_VAPID_SUBJECT` (defaults to `https://openclaw.ai`)
+
+The Control UI uses these scope-gated Gateway methods to register and test browser subscriptions:
+
+- `push.web.vapidPublicKey` fetches the active VAPID public key.
+- `push.web.subscribe` registers an `endpoint` plus `keys.p256dh`/`keys.auth`.
+- `push.web.unsubscribe` removes a registered endpoint.
+- `push.web.test` sends a test notification to the caller's subscription.
+
+<Note>
+Web Push is independent of the iOS APNS relay path (see [Configuration](/gateway/configuration) for relay-backed push) and the `push.test` method, which targets native mobile pairing.
+</Note>
+
+## Hosted embeds
+
+Assistant messages can render hosted web content inline with the `[embed ...]` shortcode. The iframe sandbox policy is controlled by `gateway.controlUi.embedSandbox`:
+
+<Tabs>
+  <Tab title="strict">
+    Disables script execution inside hosted embeds.
+  </Tab>
+  <Tab title="scripts (default)">
+    Allows interactive embeds while keeping origin isolation; usually enough for self-contained browser games/widgets.
+  </Tab>
+  <Tab title="trusted">
+    Adds `allow-same-origin` on top of `allow-scripts` for same-site documents that intentionally need stronger privileges.
+  </Tab>
+</Tabs>
+
+```json5
+{
+  gateway: {
+    controlUi: {
+      embedSandbox: "scripts",
+    },
+  },
+}
+```
+
+<Warning>
+Use `trusted` only when the embedded document genuinely needs same-origin behavior. For most agent-generated games and interactive canvases, `scripts` is the safer choice.
+</Warning>
+
+Absolute external `http(s)` embed URLs stay blocked by default. To let `[embed url="https://..."]` load third-party pages, set `gateway.controlUi.allowExternalEmbedUrls: true`.
+
+## Chat message width
+
+Grouped chat messages use a readable default max-width. Wide-monitor deployments can override it without patching bundled CSS by setting `gateway.controlUi.chatMessageMaxWidth`:
+
+```json5
+{
+  gateway: {
+    controlUi: {
+      chatMessageMaxWidth: "min(1280px, 82%)",
+    },
+  },
+}
+```
+
+The value is validated before it reaches the browser. Supported forms include plain lengths and percentages such as `960px` or `82%`, plus constrained `min(...)`, `max(...)`, `clamp(...)`, `calc(...)`, and `fit-content(...)` width expressions.
+
+## Tailnet access (recommended)
+
+<Tabs>
+  <Tab title="Integrated Tailscale Serve (preferred)">
+    Keep the Gateway on loopback and let Tailscale Serve proxy it with HTTPS:
+
+    ```bash
+    openclaw gateway --tailscale serve
+    ```
+
+    Open `https://<magicdns>/` (or your configured `gateway.controlUi.basePath`).
+
+    By default, Control UI/WebSocket Serve requests can authenticate via Tailscale identity headers (`tailscale-user-login`) when `gateway.auth.allowTailscale` is `true`. OpenClaw verifies the identity by resolving the `x-forwarded-for` address with `tailscale whois` and matching it to the header, and only accepts these when the request hits loopback with Tailscale's `x-forwarded-*` headers. For Control UI operator sessions with browser device identity, this verified Serve path also skips the device-pairing round trip; device-less browsers and node-role connections still follow the normal device checks. Set `gateway.auth.allowTailscale: false` if you want to require explicit shared-secret credentials even for Serve traffic, then use `gateway.auth.mode: "token"` or `"password"`.
+
+    For that async Serve identity path, failed auth attempts for the same client IP and auth scope are serialized before rate-limit writes. Concurrent bad retries from the same browser can therefore show `retry later` on the second request instead of two plain mismatches racing in parallel.
+
+    <Warning>
+    Tokenless Serve auth assumes the gateway host is trusted. If untrusted local code may run on that host, require token/password auth.
+    </Warning>
+
+  </Tab>
+  <Tab title="Bind to tailnet + token">
+    ```bash
+    openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)"
+    ```
+
+    Open `http://<tailscale-ip>:18789/` (or your configured `gateway.controlUi.basePath`).
+
+    Paste the matching shared secret into the UI settings (sent as `connect.params.auth.token` or `connect.params.auth.password`).
+
+  </Tab>
+</Tabs>
+
+## Insecure HTTP
+
+If you open the dashboard over plain HTTP (`http://<lan-ip>` or `http://<tailscale-ip>`), the browser runs in a **non-secure context** and blocks WebCrypto. By default, OpenClaw **blocks** Control UI connections without device identity.
+
+Documented exceptions:
+
+- localhost-only insecure HTTP compatibility with `gateway.controlUi.allowInsecureAuth=true`
+- successful operator Control UI auth through `gateway.auth.mode: "trusted-proxy"`
+- break-glass `gateway.controlUi.dangerouslyDisableDeviceAuth=true`
+
+**Recommended fix:** use HTTPS (Tailscale Serve) or open the UI locally at `https://<magicdns>/` (Serve) or `http://127.0.0.1:18789/` (on the gateway host).
+
+<AccordionGroup>
+  <Accordion title="Insecure-auth toggle behavior">
+    ```json5
+    {
+      gateway: {
+        controlUi: { allowInsecureAuth: true },
+        bind: "tailnet",
+        auth: { mode: "token", token: "replace-me" },
+      },
+    }
+    ```
+
+    `allowInsecureAuth` is a local compatibility toggle only:
+
+    - It lets localhost Control UI sessions proceed without device identity in non-secure HTTP contexts.
+    - It does not bypass pairing checks.
+    - It does not relax remote (non-localhost) device identity requirements.
+
+  </Accordion>
+  <Accordion title="Break-glass only">
+    ```json5
+    {
+      gateway: {
+        controlUi: { dangerouslyDisableDeviceAuth: true },
+        bind: "tailnet",
+        auth: { mode: "token", token: "replace-me" },
+      },
+    }
+    ```
+
+    <Warning>
+    `dangerouslyDisableDeviceAuth` disables Control UI device identity checks and is a severe security downgrade. Revert quickly after emergency use.
+    </Warning>
+
+  </Accordion>
+  <Accordion title="Trusted-proxy note">
+    - Successful trusted-proxy auth can admit **operator** Control UI sessions without device identity.
+    - This does **not** extend to node-role Control UI sessions.
+    - Same-host loopback reverse proxies still do not satisfy trusted-proxy auth; see [Trusted proxy auth](/gateway/trusted-proxy-auth).
+
+  </Accordion>
+</AccordionGroup>
+
+See [Tailscale](/gateway/tailscale) for HTTPS setup guidance.
+
+## Content security policy
+
+The Control UI ships a tight `img-src` policy: only **same-origin** assets, `data:` URLs, and locally generated `blob:` URLs are allowed. Remote `http(s)` and protocol-relative image URLs are rejected by the browser and never issue network fetches.
+
+In practice:
+
+- Avatars and images served under relative paths (for example `/avatars/<id>`) still render, including authenticated avatar routes the UI fetches and converts into local `blob:` URLs.
+- Inline `data:image/...` URLs still render.
+- Local `blob:` URLs created by the Control UI still render.
+- Remote avatar URLs emitted by channel metadata are stripped at the Control UI's avatar helpers and replaced with the built-in logo/badge, so a compromised or malicious channel cannot force arbitrary remote image fetches from an operator browser.
+
+This is always on and not configurable.
+
+## Avatar route auth
+
+When gateway auth is configured, the Control UI avatar endpoint requires the same gateway token as the rest of the API:
+
+- `GET /avatar/<agentId>` returns the avatar image only to authenticated callers. `GET /avatar/<agentId>?meta=1` returns the avatar metadata under the same rule.
+- Unauthenticated requests to either route are rejected (matching the sibling assistant-media route), so the avatar route cannot leak agent identity on hosts that are otherwise protected.
+- The Control UI forwards the gateway token as a bearer header when fetching avatars, and uses authenticated blob URLs so the image still renders in dashboards.
+
+If you disable gateway auth (not recommended on shared hosts), the avatar route also becomes unauthenticated, in line with the rest of the gateway.
+
+## Assistant media route auth
+
+When gateway auth is configured, assistant local-media previews use a two-step route:
+
+- `GET /__openclaw__/assistant-media?meta=1&source=<path>` requires the normal Control UI operator auth; the browser sends the gateway token as a bearer header when checking availability.
+- Successful metadata responses include a short-lived `mediaTicket` scoped to that exact source path.
+- Browser-rendered image, audio, video, and document URLs use `mediaTicket=<ticket>` instead of the active gateway token or password. The ticket expires quickly and cannot authorize a different source.
+
+This keeps media rendering compatible with browser-native media elements without putting reusable gateway credentials in visible media URLs.
+
+## Building the UI
+
+The Gateway serves static files from `dist/control-ui`:
+
+```bash
+pnpm ui:build
+```
+
+Optional absolute base (fixed asset URLs):
+
+```bash
+OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build
+```
+
+Local development (separate dev server):
+
+```bash
+pnpm ui:dev
+```
+
+Then point the UI at your Gateway WS URL (e.g. `ws://127.0.0.1:18789`).
+
+## Blank Control UI page
+
+If the browser loads a blank dashboard and DevTools shows no useful error, an extension or early content script may have prevented the JavaScript module app from evaluating. The static page includes a plain HTML recovery panel that appears when `<openclaw-app>` is not registered after startup.
+
+Use the panel's **Try again** action after changing the browser environment, or reload manually after these checks:
+
+- Disable extensions that inject into all pages, especially extensions with `<all_urls>` content scripts.
+- Try a private window, a clean browser profile, or another browser.
+- Keep the Gateway running and verify the same dashboard URL after the browser change.
+
+## Debugging/testing: dev server + remote Gateway
+
+The Control UI is static files; the WebSocket target is configurable and can differ from the HTTP origin. This is handy when you want the Vite dev server locally but the Gateway runs elsewhere.
+
+<Steps>
+  <Step title="Start the UI dev server">
+    ```bash
+    pnpm ui:dev
+    ```
+  </Step>
+  <Step title="Open with gatewayUrl">
+    ```text
+    http://localhost:5173/?gatewayUrl=ws%3A%2F%2F<gateway-host>%3A18789
+    ```
+
+    Optional one-time auth (if needed):
+
+    ```text
+    http://localhost:5173/?gatewayUrl=wss%3A%2F%2F<gateway-host>%3A18789#token=<gateway-token>
+    ```
+
+  </Step>
+</Steps>
+
+<AccordionGroup>
+  <Accordion title="Notes">
+    - `gatewayUrl` is stored in localStorage after load and removed from the URL.
+    - If you pass a full `ws://` or `wss://` endpoint via `gatewayUrl`, URL-encode the value so the browser parses the query string correctly.
+    - `token` should be passed via the URL fragment (`#token=...`) whenever possible. Fragments are not sent to the server, which avoids request-log and Referer leakage. Legacy `?token=` query params are still imported once for compatibility, but only as a fallback, and are stripped immediately after bootstrap.
+    - `password` is kept in memory only.
+    - When `gatewayUrl` is set, the UI does not fall back to config or environment credentials. Provide `token` (or `password`) explicitly; missing explicit credentials is an error.
+    - Use `wss://` when the Gateway is behind TLS (Tailscale Serve, HTTPS proxy, etc.).
+    - `gatewayUrl` is only accepted in a top-level window (not embedded), to prevent clickjacking.
+    - Public non-loopback Control UI deployments must set `gateway.controlUi.allowedOrigins` explicitly (full origins). Private same-origin LAN/Tailnet loads from loopback, RFC1918/link-local, `.local`, `.ts.net`, or Tailscale CGNAT hosts are accepted without enabling Host-header fallback.
+    - Gateway startup may seed local origins such as `http://localhost:<port>` and `http://127.0.0.1:<port>` from the effective runtime bind and port, but remote browser origins still need explicit entries.
+    - Do not use `gateway.controlUi.allowedOrigins: ["*"]` except for tightly controlled local testing; it means allow any browser origin, not "match whatever host I am using."
+    - `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` enables Host-header origin fallback mode, but it is a dangerous security mode.
+
+  </Accordion>
+</AccordionGroup>
+
+```json5
+{
+  gateway: {
+    controlUi: {
+      allowedOrigins: ["http://localhost:5173"],
+    },
+  },
+}
+```
+
+Remote access setup details: [Remote access](/gateway/remote).
+
+## Related
+
+- [Dashboard](/web/dashboard) — gateway dashboard
+- [Health Checks](/gateway/health) — gateway health monitoring
+- [TUI](/web/tui) — terminal user interface
+- [WebChat](/web/webchat) — browser-based chat interface

docs/web/dashboard.md

@@ -0,0 +1,72 @@
+---
+summary: "Gateway dashboard (Control UI) access and auth"
+read_when:
+  - Changing dashboard authentication or exposure modes
+title: "Dashboard"
+---
+
+The Gateway dashboard is the browser Control UI served at `/` by default (override with `gateway.controlUi.basePath`).
+
+Quick open (local Gateway):
+
+- [http://127.0.0.1:18789/](http://127.0.0.1:18789/) (or [http://localhost:18789/](http://localhost:18789/))
+- With `gateway.tls.enabled: true`, use `https://127.0.0.1:18789/` and `wss://127.0.0.1:18789` for the WebSocket endpoint.
+
+Key references:
+
+- [Control UI](/web/control-ui) for usage and UI capabilities.
+- [Tailscale](/gateway/tailscale) for Serve/Funnel automation.
+- [Web surfaces](/web) for bind modes and security notes.
+
+Auth is enforced at the WebSocket handshake via the configured gateway auth path:
+
+- `connect.params.auth.token`
+- `connect.params.auth.password`
+- Tailscale Serve identity headers when `gateway.auth.allowTailscale: true`
+- trusted-proxy identity headers when `gateway.auth.mode: "trusted-proxy"`
+
+See `gateway.auth` in [Gateway configuration](/gateway/configuration).
+
+<Warning>
+The Control UI is an **admin surface** (chat, config, exec approvals). Do not expose it publicly. The UI keeps dashboard URL tokens in sessionStorage for the current browser tab and selected gateway URL, and strips them from the URL after load. Prefer localhost, Tailscale Serve, or an SSH tunnel.
+</Warning>
+
+## Fast path (recommended)
+
+- After onboarding, the CLI auto-opens the dashboard and prints a clean (non-tokenized) link.
+- Re-open anytime: `openclaw dashboard` (copies the link, opens a browser if possible, prints an SSH hint if headless).
+- If clipboard and browser delivery both fail, `openclaw dashboard` still prints the clean URL and tells you to append your token (from `OPENCLAW_GATEWAY_TOKEN` or `gateway.auth.token`) as the URL fragment key `token`; it never prints the token value in logs.
+- If the UI prompts for shared-secret auth, paste the configured token or password into Control UI settings.
+
+## Auth basics (local vs remote)
+
+- **Localhost**: open `http://127.0.0.1:18789/`.
+- **Gateway TLS**: when `gateway.tls.enabled: true`, dashboard/status links use `https://` and Control UI WebSocket links use `wss://`.
+- **Shared-secret token source**: `gateway.auth.token` (or `OPENCLAW_GATEWAY_TOKEN`). `openclaw dashboard` can pass it via URL fragment for one-time bootstrap; the Control UI keeps it in sessionStorage for the current tab and selected gateway URL, not localStorage.
+- If `gateway.auth.token` is SecretRef-managed, `openclaw dashboard` prints/copies/opens a non-tokenized URL by design, to avoid exposing externally managed tokens in shell logs, clipboard history, or browser-launch arguments. If the ref is unresolved in your current shell, it still prints the non-tokenized URL plus actionable auth setup guidance.
+- **Shared-secret password**: use the configured `gateway.auth.password` (or `OPENCLAW_GATEWAY_PASSWORD`). The dashboard does not persist passwords across reloads.
+- **Identity-bearing modes**: Tailscale Serve satisfies Control UI/WebSocket auth via identity headers when `gateway.auth.allowTailscale: true`; a non-loopback identity-aware reverse proxy satisfies `gateway.auth.mode: "trusted-proxy"`. Neither needs a pasted shared secret for the WebSocket.
+- **Not localhost**: use Tailscale Serve, a non-loopback shared-secret bind, a non-loopback identity-aware reverse proxy with `gateway.auth.mode: "trusted-proxy"`, or an SSH tunnel. HTTP APIs still use shared-secret auth unless you intentionally run private-ingress `gateway.auth.mode: "none"` or trusted-proxy HTTP auth. See [Web surfaces](/web).
+
+<a id="if-you-see-unauthorized-1008"></a>
+
+## If you see "unauthorized" / 1008
+
+- Confirm the gateway is reachable: local `openclaw status`; remote, SSH tunnel `ssh -N -L 18789:127.0.0.1:18789 user@gateway-host` then open `http://127.0.0.1:18789/`.
+- For `AUTH_TOKEN_MISMATCH`, clients may do one trusted retry with a cached device token when the gateway returns retry hints; that retry reuses the token's cached approved scopes (explicit `deviceToken`/`scopes` callers keep their requested scope set). If auth still fails after that retry, resolve token drift manually.
+- For `AUTH_SCOPE_MISMATCH`, the device token was recognized but does not carry the requested scopes; re-pair or approve the new scope set instead of rotating the shared gateway token.
+- Outside that retry path, connect auth precedence is: explicit shared token/password, then explicit `deviceToken`, then stored device token, then bootstrap token.
+- On the async Tailscale Serve path, failed attempts for the same `{scope, ip}` are serialized before the failed-auth limiter records them, so a second concurrent bad retry can already show `retry later`.
+- For token drift repair steps, see [Token drift recovery checklist](/cli/devices#token-drift-recovery-checklist).
+- Retrieve or supply the shared secret from the gateway host:
+  - Token: `openclaw config get gateway.auth.token`
+  - Password: resolve the configured `gateway.auth.password` or `OPENCLAW_GATEWAY_PASSWORD`
+  - SecretRef-managed token: resolve the external secret provider, or export `OPENCLAW_GATEWAY_TOKEN` in this shell and rerun `openclaw dashboard`
+  - No shared secret configured: `openclaw doctor --generate-gateway-token`
+- In the dashboard settings, paste the token or password into the auth field, then connect.
+- The UI language picker lives in **Overview -> Gateway Access -> Language**, not under Appearance.
+
+## Related
+
+- [Control UI](/web/control-ui)
+- [WebChat](/web/webchat)

docs/web/index.md

@@ -0,0 +1,115 @@
+---
+summary: "Gateway web surfaces: Control UI, bind modes, and security"
+read_when:
+  - You want to access the Gateway over Tailscale
+  - You want the browser Control UI and config editing
+title: "Web"
+---
+
+The Gateway serves a small **browser Control UI** (Vite + Lit) from the same port as the Gateway WebSocket:
+
+- default: `http://<host>:18789/`
+- with `gateway.tls.enabled: true`: `https://<host>:18789/`
+- optional prefix: set `gateway.controlUi.basePath` (e.g. `/openclaw`)
+
+Capabilities live in [Control UI](/web/control-ui). This page covers bind modes, security, and other web-facing surfaces.
+
+## Config (default-on)
+
+Control UI is **enabled by default** when assets are present (`dist/control-ui`):
+
+```json5
+{
+  gateway: {
+    controlUi: { enabled: true, basePath: "/openclaw" }, // basePath optional
+  },
+}
+```
+
+## Webhooks
+
+When `hooks.enabled=true`, the Gateway also exposes a webhook endpoint on the same HTTP server. See `hooks` in [Gateway configuration reference](/gateway/configuration-reference#hooks) for auth and payloads.
+
+## Admin HTTP RPC
+
+`POST /api/v1/admin/rpc` exposes selected Gateway control-plane methods over HTTP. Off by default; registered only when the `admin-http-rpc` plugin is enabled. See [Admin HTTP RPC](/plugins/admin-http-rpc) for the auth model, allowed methods, and comparison with the WebSocket API.
+
+## Tailscale access
+
+<Tabs>
+  <Tab title="Integrated Serve (recommended)">
+    Keep the Gateway on loopback and let Tailscale Serve proxy it:
+
+    ```json5
+    {
+      gateway: {
+        bind: "loopback",
+        tailscale: { mode: "serve" },
+      },
+    }
+    ```
+
+    Start the gateway:
+
+    ```bash
+    openclaw gateway
+    ```
+
+    Open `https://<magicdns>/` (or your configured `gateway.controlUi.basePath`).
+
+  </Tab>
+  <Tab title="Tailnet bind + token">
+    ```json5
+    {
+      gateway: {
+        bind: "tailnet",
+        controlUi: { enabled: true },
+        auth: { mode: "token", token: "your-token" },
+      },
+    }
+    ```
+
+    Start the gateway (this non-loopback example uses shared-secret token auth):
+
+    ```bash
+    openclaw gateway
+    ```
+
+    Open `http://<tailscale-ip>:18789/` (or your configured `gateway.controlUi.basePath`).
+
+  </Tab>
+  <Tab title="Public internet (Funnel)">
+    ```json5
+    {
+      gateway: {
+        bind: "loopback",
+        tailscale: { mode: "funnel" },
+        auth: { mode: "password" }, // or OPENCLAW_GATEWAY_PASSWORD
+      },
+    }
+    ```
+
+    `tailscale.mode: "funnel"` requires `gateway.auth.mode: "password"`; Serve and Funnel both require `gateway.bind: "loopback"`.
+
+  </Tab>
+</Tabs>
+
+## Security notes
+
+- Gateway auth is required by default: token, password, trusted-proxy, or Tailscale Serve identity headers when enabled.
+- Non-loopback binds still **require** gateway auth: token/password auth or an identity-aware reverse proxy with `gateway.auth.mode: "trusted-proxy"`.
+- The onboarding wizard creates shared-secret auth by default and usually generates a gateway token, even on loopback.
+- In shared-secret mode, the UI sends `connect.params.auth.token` or `connect.params.auth.password` during the WebSocket handshake.
+- With `gateway.tls.enabled: true`, local dashboard/status helpers render `https://` URLs and `wss://` WebSocket URLs.
+- In identity-bearing modes (Tailscale Serve, `trusted-proxy`), the WebSocket auth check is satisfied from request headers instead of a shared secret.
+- For public non-loopback Control UI deployments, set `gateway.controlUi.allowedOrigins` explicitly (full origins). Private same-origin loads are accepted without it for loopback, RFC1918/link-local, `.local`, `.ts.net`, and Tailscale CGNAT hosts.
+- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback: true` enables Host-header origin fallback; this is a dangerous security downgrade.
+- With Serve, Tailscale identity headers satisfy Control UI/WebSocket auth when `gateway.auth.allowTailscale: true` (no token/password required). HTTP API endpoints do not use Tailscale identity headers; they always follow the gateway's normal HTTP auth mode. Set `gateway.auth.allowTailscale: false` to require explicit credentials even over Serve. This tokenless flow assumes the gateway host itself is trusted. See [Tailscale](/gateway/tailscale) and [Security](/gateway/security).
+
+## Building the UI
+
+The Gateway serves static files from `dist/control-ui`:
+
+```bash
+pnpm ui:build
+```

docs/web/tui.md

@@ -0,0 +1,265 @@
+---
+summary: "Terminal UI (TUI): connect to the Gateway or run locally in embedded mode"
+read_when:
+  - You want a beginner-friendly walkthrough of the TUI
+  - You need the complete list of TUI features, commands, and shortcuts
+title: "TUI"
+---
+
+## Quick start
+
+### Gateway mode
+
+1. Start the Gateway.
+
+```bash
+openclaw gateway
+```
+
+2. Open the TUI.
+
+```bash
+openclaw tui
+```
+
+3. Type a message and press Enter.
+
+Remote Gateway:
+
+```bash
+openclaw tui --url ws://<host>:<port> --token <gateway-token>
+```
+
+Use `--password` if your Gateway uses password auth.
+
+### Local mode
+
+Run the TUI without a Gateway:
+
+```bash
+openclaw chat
+# or
+openclaw tui --local
+```
+
+- `openclaw chat` and `openclaw terminal` are aliases for `openclaw tui --local`.
+- `--local` cannot be combined with `--url`, `--token`, or `--password`.
+- Local mode uses the embedded agent runtime directly. Most local tools work, but Gateway-only features are unavailable.
+- Bare `openclaw` (no subcommand) picks a target automatically: unconfigured install runs onboarding; invalid config opens [Crestodian](#crestodian-setup-and-repair-helper); valid config opens this TUI shell in gateway mode if a Gateway is reachable, otherwise in local mode.
+
+## What you see
+
+- Header: connection URL, current agent, current session.
+- Chat log: user messages, assistant replies, system notices, tool cards.
+- Status line: connection/run state (connecting, running, streaming, idle, error).
+- Footer: agent + session + model + goal state + think/fast/verbose/trace/reasoning + token counts + deliver. When `tui.footer.showRemoteHost` is enabled, remote Gateway connections also show the connection host.
+- Input: text editor with autocomplete.
+
+## Mental model: agents + sessions
+
+- Agents are unique slugs (e.g. `main`, `research`). The Gateway exposes the list.
+- Sessions belong to the current agent.
+- Session keys are stored as `agent:<agentId>:<sessionKey>`.
+  - If you type `/session main`, the TUI expands it to `agent:<currentAgent>:main`.
+  - If you type `/session agent:other:main`, you switch to that agent session explicitly.
+- Session scope:
+  - `per-sender` (default): each agent has many sessions.
+  - `global`: the TUI always uses the `global` session (the picker may be empty).
+- The current agent + session are always visible in the footer.
+- To show the Gateway host for non-local URL-backed connections, opt in with:
+
+  ```bash
+  openclaw config set tui.footer.showRemoteHost true
+  ```
+
+  Default is `false`. Loopback and embedded local connections never show a host label.
+
+- If the session has a [goal](/tools/goal), the footer shows its compact state:
+  `Pursuing goal`, `Goal paused (/goal resume)`, `Goal blocked (/goal resume)`, or `Goal achieved`.
+- When started without `--session`, gateway-mode TUI resumes the last selected session for the same gateway, agent, and session scope if that session still exists. Passing `--session`, `/session`, `/new`, or `/reset` remains explicit.
+
+## Sending + delivery
+
+- Messages always go to the Gateway (or embedded runtime in local mode); delivering the assistant's reply back out to a chat provider is a separate, off-by-default step.
+- The TUI is an internal source surface like WebChat, not a generic outbound channel. Harnesses that require `tools.message` for visible replies can satisfy the active TUI turn with a targetless `message.send`; explicit provider delivery still uses normal configured channels and never falls back to `lastChannel`.
+- Delivery is fixed for the whole TUI session at launch: start with `openclaw tui --deliver` to turn it on. There is no `/deliver` slash command or Settings toggle to flip it mid-session; restart the TUI to change it.
+
+## Pickers + overlays
+
+- Model picker: list available models and set the session override.
+- Agent picker: choose a different agent.
+- Session picker: shows up to 50 sessions for the current agent updated in the last 7 days. Use `/session <key>` to jump to an older known session.
+- Settings (`/settings`): toggle tool output expansion and thinking visibility. This panel does not control delivery.
+
+## Keyboard shortcuts
+
+- Enter: send message
+- Esc: abort active run
+- Ctrl+C: clear input (press twice to exit)
+- Ctrl+D: exit
+- Ctrl+L: model picker
+- Ctrl+G: agent picker
+- Ctrl+P: session picker
+- Ctrl+O: toggle tool output expansion
+- Ctrl+T: toggle thinking visibility (reloads history)
+
+## Slash commands
+
+Core:
+
+- `/help`
+- `/status` (Gateway-forwarded; shows session/model summary)
+- `/gateway-status` (alias `/gwstatus`; shows Gateway connection status directly)
+- `/agent <id>` (or `/agents`)
+- `/session <key>` (or `/sessions`)
+- `/model <provider/model>` (or `/models`)
+
+Session controls:
+
+- `/think <off|minimal|low|medium|high>` (higher tiers may add levels like `xhigh`/`max` depending on the model)
+- `/fast <status|auto|on|off>`
+- `/verbose <on|full|off>`
+- `/trace <on|off>`
+- `/reasoning <on|off|stream>`
+- `/usage <off|tokens|full|reset>` (`reset`/`inherit`/`clear`/`default` clears the session override)
+- `/goal [status] | /goal start <objective> | /goal pause|resume|complete|block|clear`
+- `/elevated <on|off|ask|full>` (alias: `/elev`)
+- `/activation <mention|always>`
+
+Session lifecycle:
+
+- `/new` (spawn a fresh, isolated session under a new key; does not affect other TUI clients on the old session)
+- `/reset` (reset the current session key in place)
+- `/abort` (abort the active run)
+- `/settings`
+- `/exit` (or `/quit`)
+
+Local mode only:
+
+- `/auth [provider]` opens the provider auth/login flow inside the TUI.
+
+Crestodian:
+
+- `/crestodian [request]` returns from the normal agent TUI to the [Crestodian](#crestodian-setup-and-repair-helper) setup/repair chat, optionally forwarding one request.
+
+Other Gateway slash commands (for example, `/context`) are forwarded to the Gateway and shown as system output. See [Slash commands](/tools/slash-commands).
+
+## Local shell commands
+
+- Prefix a line with `!` to run a local shell command on the TUI host.
+- The TUI prompts once per session to allow local execution; declining keeps `!` disabled for the session.
+- Commands run in a fresh, non-interactive shell in the TUI working directory (no persistent `cd`/env).
+- Local shell commands receive `OPENCLAW_SHELL=tui-local` in their environment.
+- A lone `!` is sent as a normal message; leading spaces do not trigger local exec.
+
+## Crestodian setup and repair helper
+
+Crestodian is the ring-zero setup/repair assistant, exposed as `openclaw crestodian` (or launched automatically when bare `openclaw` finds an invalid config). It runs inside the same local TUI shell as `openclaw tui --local`, backed by a dedicated dialogue/operations layer instead of a live model+tools session:
+
+```bash
+openclaw crestodian                       # start interactively
+openclaw crestodian -m "status"           # run one request and exit
+openclaw crestodian -m "set default model openai/gpt-5.2" --yes   # apply a config write
+```
+
+- Persistent config writes need approval: either confirm interactively or pass `--yes`.
+- `--json` prints the startup overview as JSON instead of starting the chat.
+- From inside Crestodian, an `open-tui` request (for example, asking to talk to a normal agent) exits Crestodian and opens the regular agent TUI; use `/crestodian` there to come back.
+
+Use local mode when the current config already validates and you want the embedded agent to inspect it on the same machine, compare it against the docs, and help repair drift without depending on a running Gateway.
+
+If `openclaw config validate` is already failing, start with `openclaw configure` or `openclaw doctor --fix` first; `openclaw chat` still needs a loadable config to start.
+
+Typical loop:
+
+1. Start local mode:
+
+```bash
+openclaw chat
+```
+
+2. Ask the agent what you want checked, for example:
+
+```text
+Compare my gateway auth config with the docs and suggest the smallest fix.
+```
+
+3. Use local shell commands for exact evidence and validation:
+
+```text
+!openclaw config file
+!openclaw docs gateway auth token secretref
+!openclaw config validate
+!openclaw doctor
+```
+
+4. Apply narrow changes with `openclaw config set` or `openclaw configure`, then rerun `!openclaw config validate`.
+5. If Doctor recommends an automatic migration or repair, review it and run `!openclaw doctor --fix`.
+
+Tips:
+
+- Prefer `openclaw config set` or `openclaw configure` over hand-editing `openclaw.json`.
+- `openclaw docs "<query>"` searches the live docs index from the same machine.
+- `openclaw config validate --json` is useful when you want structured schema and SecretRef/resolvability errors.
+
+## Tool output
+
+- Tool calls show as cards with args + results.
+- Ctrl+O toggles between collapsed/expanded views.
+- While tools run, partial updates stream into the same card.
+
+## Terminal colors
+
+- The TUI keeps assistant body text in your terminal's default foreground so dark and light terminals both stay readable.
+- If your terminal uses a light background and auto-detection is wrong, set `OPENCLAW_THEME=light` before launching `openclaw tui`.
+- To force the original dark palette instead, set `OPENCLAW_THEME=dark`.
+
+## History + streaming
+
+- On connect, the TUI loads the latest history (default 200 messages).
+- Streaming responses update in place until finalized.
+- The TUI also listens to agent tool events for richer tool cards.
+
+## Connection details
+
+- The TUI connects with client id `openclaw-tui` under the coarse `ui` client mode (the same mode Control UI and WebChat use for Gateway policy).
+- Reconnects show a system message; event gaps are surfaced in the log.
+
+## Options
+
+- `--local`: Run against the local embedded agent runtime
+- `--url <url>`: Gateway WebSocket URL (defaults to `gateway.remote.url` from config, or `ws://127.0.0.1:<port>` on loopback)
+- `--token <token>`: Gateway token (if required)
+- `--password <password>`: Gateway password (if required)
+- `--session <key>`: Session key (default: `main`, or `global` when scope is global)
+- `--deliver`: Deliver assistant replies to the provider (default off)
+- `--thinking <level>`: Override thinking level for sends
+- `--message <text>`: Send an initial message after connecting
+- `--timeout-ms <ms>`: Agent timeout in ms (defaults to `agents.defaults.timeoutSeconds`)
+- `--history-limit <n>`: History entries to load (default `200`)
+
+<Warning>
+When you set `--url`, the TUI does not fall back to config or environment credentials. Pass `--token` or `--password` explicitly. Missing explicit credentials is an error. In local mode, do not pass `--url`, `--token`, or `--password`.
+</Warning>
+
+## Troubleshooting
+
+No output after sending a message:
+
+- Run `/status` in the TUI to confirm the Gateway is connected and idle/busy.
+- Check the Gateway logs: `openclaw logs --follow`.
+- Confirm the agent can run: `openclaw status` and `openclaw models status`.
+- If you expect messages in a chat channel, confirm the TUI was started with `--deliver` (this cannot be turned on later without restarting).
+
+## Connection troubleshooting
+
+- `disconnected`: ensure the Gateway is running and your `--url/--token/--password` are correct.
+- No agents in picker: check `openclaw agents list` and your routing config.
+- Empty session picker: you might be in global scope or have no sessions yet.
+
+## Related
+
+- [Control UI](/web/control-ui) — web-based control interface
+- [Config](/cli/config) — inspect, validate, and edit `openclaw.json`
+- [Doctor](/cli/doctor) — guided repair and migration checks
+- [CLI Reference](/cli) — full CLI command reference

docs/web/webchat.md

@@ -0,0 +1,82 @@
+---
+summary: "Loopback WebChat static host and Gateway WS usage for chat UI"
+read_when:
+  - Debugging or configuring WebChat access
+title: "WebChat"
+---
+
+Status: the macOS/iOS SwiftUI chat UI talks directly to the Gateway WebSocket. No embedded browser, no local static server.
+
+## What it is
+
+- A native chat UI for the gateway.
+- Uses the same sessions and routing rules as other channels.
+- Deterministic routing: replies always go back to WebChat.
+- History is always fetched from the gateway (no local file watching). If the gateway is unreachable, WebChat is read-only.
+
+## Quick start
+
+1. Start the gateway.
+2. Open the WebChat UI (macOS/iOS app) or the Control UI chat tab.
+3. Ensure a valid gateway auth path is configured (shared-secret by default, even on loopback).
+
+## How it works
+
+- The UI connects to the Gateway WebSocket and uses the `chat.history`, `chat.send`, `chat.inject`, and `chat.message.get` RPC methods.
+- `chat.history` is bounded for stability: Gateway may truncate long text fields, omit heavy metadata, and replace oversized entries with `[chat.history omitted: message too large]`. API clients can send a per-request `maxChars` to override the default limit for one call.
+- When a visible assistant message was truncated in `chat.history`, Control UI can open a side reader and fetch the full display-normalized entry on demand through `chat.message.get`, without increasing the default history payload. `chat.message.get` uses the same transcript branch and display rules as `chat.history`, but targets one entry by `messageId` and returns an honest unavailable reason when the full content can no longer be returned.
+- `chat.history` follows the active transcript branch for append-only session files, so abandoned rewrite branches and superseded prompt copies are not rendered in WebChat.
+- Compaction entries render as a "Compacted history" divider explaining that the compacted transcript is preserved as a checkpoint, with an action to open session checkpoints (branch or restore, when permissions allow).
+- Control UI remembers the backing Gateway `sessionId` returned by `chat.history` and includes it on follow-up `chat.send` calls, so reconnects and page refreshes continue the same stored conversation unless the user starts or resets a session.
+- `chat.send` takes an idempotency key (Control UI uses the run id); the Gateway dedupes repeated requests that reuse the same key, so retried or duplicate in-flight submits for the same session/message/attachments do not create a second run.
+- Workspace startup files and pending `BOOTSTRAP.md` instructions are supplied through the agent system prompt's `# Project Context` section, not copied into the WebChat user message. If bootstrap content is truncated, the system prompt gets a short "Bootstrap Context Notice" instead; detailed counts and config knobs stay on diagnostic surfaces.
+- Display normalization on `chat.history` strips: runtime-only OpenClaw context, inbound envelope wrappers, inline delivery directive tags such as `[[reply_to_current]]`, `[[reply_to:<id>]]`, and `[[audio_as_voice]]`, plain-text tool-call XML payloads (`<tool_call>`, `<function_call>`, `<tool_calls>`, `<function_calls>`, including truncated blocks), and leaked ASCII/full-width model control tokens. Assistant entries whose whole visible text is only the silent token `NO_REPLY` (case-insensitive) are omitted.
+- Reasoning-flagged reply payloads (`isReasoning: true`) are excluded from WebChat assistant content, transcript replay text, and audio content blocks, so thinking-only payloads do not surface as visible assistant messages or playable audio.
+- `chat.inject` appends an assistant note directly to the transcript and broadcasts it to the UI (no agent run).
+- Aborted runs can keep partial assistant output visible in the UI. Gateway persists that partial text into transcript history when buffered output exists, and marks the entry with abort metadata.
+
+### Transcript and delivery model
+
+WebChat has two separate data paths:
+
+- The session JSONL file is the durable model/runtime transcript. For normal agent runs, the embedded OpenClaw runtime persists model-visible `user`, `assistant`, and `toolResult` messages through its session manager. WebChat does not write arbitrary delivery, status, or helper text into that transcript.
+- Gateway `ReplyPayload` events are the live delivery projection: normalized for WebChat/channel display, block streaming, directive tags, media embedding, TTS/audio flags, and UI fallback behavior. They are not themselves the canonical session log.
+- Harnesses that require visible replies through `tools.message` still use WebChat as a current-run internal source reply sink. A targetless `message.send` from that active WebChat run is projected into the same chat and mirrored to the session transcript; WebChat does not become a reusable outbound channel and never inherits `lastChannel`.
+- WebChat injects assistant transcript entries only when the Gateway owns a displayed message outside a normal embedded agent turn: `chat.inject`, non-agent command replies, aborted partial output, and WebChat-managed media transcript supplements.
+- If live assistant text appears during a run but disappears after history reload, check in order: whether the raw JSONL contains the assistant text, whether `chat.history` display projection stripped it, then whether the Control UI optimistic-tail merge replaced local delivery state with the persisted snapshot.
+
+Normal agent-run final answers should be durable because the embedded runtime writes the assistant `message_end`. Any fallback that mirrors a delivered final payload into the transcript must first avoid duplicating an assistant turn that the embedded runtime already wrote.
+
+## Control UI agents tools panel
+
+- The Control UI `/agents` Tools panel has an "Available Right Now" view backed by `tools.effective(sessionKey=...)`: a server-derived, read-only projection of the current session's tool inventory, including core, plugin, channel-owned, and already-discovered MCP server tools.
+- A separate config-editing view (backed by `tools.catalog`) covers profiles, per-agent overrides, and catalog semantics.
+- Runtime availability is session-scoped. Switching sessions on the same agent can change the "Available Right Now" list. If configured MCP servers have not been connected or changed since the last discovery, the panel shows a notice instead of silently starting MCP transports from the read path.
+- The config editor does not imply runtime availability; effective access still follows policy precedence (`allow`/`deny`, per-agent and provider/channel overrides).
+
+## Remote use
+
+- Remote mode tunnels the gateway WebSocket over SSH/Tailscale.
+- You do not need to run a separate WebChat server.
+
+## Configuration reference (WebChat)
+
+Full configuration: [Configuration](/gateway/configuration)
+
+WebChat has no persisted config section. Gateway uses the built-in `chat.history` display limit; API clients can send per-request `maxChars` to override it for a single call. Legacy `channels.webchat` and `gateway.webchat` config is retired; run `openclaw doctor --fix` to remove it.
+
+Related global options:
+
+- `gateway.port`, `gateway.bind`: WebSocket host/port.
+- `gateway.auth.mode`, `gateway.auth.token`, `gateway.auth.password`:
+  shared-secret WebSocket auth.
+- `gateway.auth.allowTailscale`: browser Control UI chat tab can use Tailscale
+  Serve identity headers when enabled.
+- `gateway.auth.mode: "trusted-proxy"`: reverse-proxy auth for browser clients behind an identity-aware **non-loopback** proxy source (see [Trusted Proxy Auth](/gateway/trusted-proxy-auth)).
+- `gateway.remote.url`, `gateway.remote.token`, `gateway.remote.password`: remote gateway target.
+- `session.*`: session storage and main key defaults.
+
+## Related
+
+- [Control UI](/web/control-ui)
+- [Dashboard](/web/dashboard)