> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wednesdayai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Web client hosting

> Deploy and host the WednesdayAI web client (static bundle, container, or gateway route) with administrator operational controls

# Web client hosting

The WednesdayAI web client is a **static bundle**. It contains no gateway address, no credentials
and no server code: everything environment-specific arrives at runtime from a small `config.json`
served next to `index.html`. One build therefore serves every deployment - a CDN, a static host, a
container, or the gateway itself.

The client talks to the gateway over the WebSocket RPC protocol only. It authenticates with a
bounded device credential it mints and redeems itself during onboarding, so the host that serves the
files never handles a secret. See [Protocol](https://docs.wednesdayai.dev/next/admin/gateway/protocol.md) for the client identity rules.

## The bundle ships with WednesdayAI

A published install already contains the built client at `<install>/dist/web-client`, packaged
next to the Control UI. Nothing has to be built or downloaded first:

```bash theme={"dark"}
wednesdayai web serve --gateway-url wss://gateway.example.com
```

That is the default for both hosting shapes WednesdayAI runs itself: `wednesdayai web serve`
without `--root` and the gateway route without `gateway.webClient.root` both serve the packaged
bundle. Pointing either at your own directory always wins over the packaged one.

From a **source checkout** the packaged bundle does not exist until you build it, and `pnpm build`
empties `dist/`, so build it after:

```bash theme={"dark"}
pnpm web:build:packaged        # writes dist/web-client (the packaged location)
pnpm --dir apps/web build      # writes apps/web/dist (for a CDN or your own host)
```

Without either, `web serve` exits non-zero and the gateway route answers `503` - both naming
`pnpm web:build:packaged`.

Anyone packaging the web client from source should also pass its bundle budget gate:
`pnpm web:budget` reads the built bundle's Vite manifest and compares the gzipped entry chunk and
the gzipped total initial JavaScript against the limits in `apps/web/bundle-budget.json`, printing
a per-chunk table and failing on a breach. `pnpm web:build:packaged` runs the same check for the
web app and deletes the manifest afterwards, so it never ships; `pnpm web:budget:update` reseeds
the limits from a fresh build (measured size plus a 5% margin, rounded up to the next KiB).

## Choose a deployment

| Shape | Use when | How |
| - | - | - |
| Standalone server | You want one small process next to your other services | `wednesdayai web serve` |
| Gateway route | Single origin, one process, no CDN | `gateway.webClient.enabled` |
| Static host or CDN | You already run object storage or a CDN | Upload `apps/web/dist` plus your own `config.json`; see [Rules the host must follow](#rules-the-host-must-follow) |
| Container | You deploy images | `apps/web/Dockerfile` |

The first two use the packaged bundle by default; the last two host a copy you deploy yourself.
Every shape needs the same two things: the browser origin in
`gateway.webClient.allowedOrigins`, and a `config.json` naming the gateway.

## Standalone server

```bash theme={"dark"}
wednesdayai web serve \
  --port 8787 \
  --gateway-url wss://gateway.example.com
```

This starts **no gateway** and keeps no state, so you can run as many instances behind a load
balancer as you like. Flags win over environment variables, which win over defaults, and the
packaged `dist/web-client` bundle is the default root. Add `--root apps/web/dist` (or any other
directory) to serve a bundle of your own.

| Flag | Environment variable | Default | Meaning |
| - | - | - | - |
| `--root <dir>` | `OPENCLAW_WEB_ROOT` | packaged bundle | Directory holding the built bundle |
| `--gateway-url <url>` | `OPENCLAW_WEB_GATEWAY_URL` | required | Absolute `ws://` or `wss://` gateway URL |
| `--port <port>` | `OPENCLAW_WEB_PORT` | `8787` | TCP port |
| `--host <host>` | `OPENCLAW_WEB_HOST` | `127.0.0.1` | Bind host |
| `--base-path <path>` | `OPENCLAW_WEB_BASE_PATH` | `/` | Public path the bundle is mounted under |
| `--client-id <id>` | `OPENCLAW_WEB_CLIENT_ID` | `openclaw-user-client` | Gateway client id |
| `--assistant-name <name>` | `OPENCLAW_WEB_ASSISTANT_NAME` | unset | Brand name: the sidebar header and pairing screen, and the fallback when an assistant has no resolved name |
| `--image-origin <origin>` | `OPENCLAW_WEB_IMAGE_ORIGINS` | unset | Exact `https://` origin remote markdown images may load from; repeatable on the CLI, comma-separated as an environment variable |

`http://` and `https://` gateway URLs are accepted and upgraded to `ws://` and `wss://`. Anything
else - a relative URL, a query string, an unknown scheme, a missing bundle, a port outside
0-65535 - exits non-zero before the socket binds, with a message naming the flag and its
environment variable. A source checkout with no packaged bundle and no `--root` is refused the same
way, naming `pnpm web:build:packaged`.

`GET /healthz` answers `200 {"status":"ok","service":"openclaw-user-client"}` for load balancer
probes.

### Serving under a subpath

`--base-path /client` (any prefix works; this one is just an example) mounts everything under that
prefix: `/client/`, `/client/config.json`, `/client/assets/...`. A request for the bare `/client`
redirects to `/client/`, and paths outside the prefix are not handled at all. The bundle uses
relative asset URLs, so no rebuild is needed.

## Container

The image builds the bundle and runs the standalone server. Build from the **repository root**, not
from `apps/web`: the build needs the shared workspace packages under `packages/` (`brand-tokens`
for colours and fonts, `gateway-browser-client`, `host-bridge` for the app host bridge,
`talk-client` for browser audio, `ui-contract`) in its context, and
`apps/web/Dockerfile.dockerignore` already limits the context to the files the build uses.

The packaged bundle and this image both include that audio client. Voice playback uses a 40 ms
pre-roll into an echo-cancellation-safe speaker sink. The microphone stops if the gateway socket
drops, including while Voice is still starting, and the control returns to idle rather than staying
on "starting". Interruption is armed only while the spoken reply is playing, not during the short
filler or tool-acknowledgement phrases.

```bash theme={"dark"}
docker build -f apps/web/Dockerfile -t wednesdayai-web-client .

docker run --rm -p 8787:8787 \
  -e OPENCLAW_WEB_GATEWAY_URL=wss://gateway.example.com \
  -e OPENCLAW_WEB_ASSISTANT_NAME=WednesdayAI \
  wednesdayai-web-client
```

The image contains only the static files and a dependency-free Node server. It holds no secrets and
no state, runs as an unprivileged user, exposes `8787`, and declares a `HEALTHCHECK` against
`/healthz`. `OPENCLAW_WEB_GATEWAY_URL` is not baked in; supply it (and any other
`OPENCLAW_WEB_*` variable from the table above) at run time.

## Gateway route

For single-origin deployments the gateway can serve the bundle itself. This is **off by default**.

```json5 theme={"dark"}
{
  gateway: {
    webClient: {
      enabled: true,
      allowedOrigins: ["https://gateway.example.com"],
      // "basePath": "/chat",  // optional override; omit to serve at the default /v2/client/
      // "root": "/srv/wednesdayai-web",  // optional: defaults to the packaged dist/web-client
    },
  },
}
```

With this config the client is at `https://gateway.example.com/v2/client/`, beside the Control UI v2
console at the gateway root. Restart the gateway after changing `gateway.webClient` (Linux:
`systemctl --user restart openclaw-gateway`; macOS: `wednesdayai gateway restart --deep`).

* `config.json` is synthesized per request: `gatewayUrl` is the gateway's own origin, so the client
  connects back to where it was loaded from, and `assistantName` is the configured assistant name
  (`ui.assistant.name`, else the default agent's identity, else `Assistant`).
* `basePath` defaults to `/v2/client` (the default in the sample above). It must be a single-slash path: a `//` prefix, backslashes, whitespace or control characters, `.` or `..` segments, and query or fragment characters are rejected when the config loads. It also may not collide with another active SPA mount: a base path of `/` while the Control UI v2 console is enabled, or base paths that contain one another, are rejected when the config loads, naming both keys. With a distinct base path the other consoles are unaffected.
* `root` is optional. Unset, the gateway serves the packaged `dist/web-client` bundle and logs
  which directory it picked. Set, it always wins - including when it is broken, which answers `503`
  with that reason rather than silently falling back. When neither resolves, the route answers
  `503` naming `pnpm web:build:packaged` and the gateway logs a warning at startup.
* The origin allowlist still applies: add the gateway's own origin to
  `gateway.webClient.allowedOrigins`, or the websocket connect is refused.
* Every response of the route - index, assets, redirects, `config.json` - sends
  `Permissions-Policy` granting `geolocation=(self)` and `Cross-Origin-Opener-Policy: same-origin`.
  This is what makes the client's **Share location** toggle work on the gateway route (ADR 0121):
  browsers only honour geolocation where the policy allows it, and geolocation additionally needs
  a secure context. Every other gateway response keeps the default policy with `geolocation=()`,
  so agent-authored same-origin pages - the canvas host, A2UI and plugin UIs - cannot reach the
  permission the user granted to the web client. The `Cross-Origin-Opener-Policy` isolates the
  client document in its own browsing-context group, so such a page cannot open the client in a
  named window and read its granted permission either. Verify with:
  `curl -sI https://gateway.example.com/v2/client/ | grep -i permissions-policy` (shows
  `geolocation=(self)`) versus the same request to the canvas host (shows `geolocation=()`).

> [!NOTE]
>
> **Upgrading from an earlier build.** The default `basePath` used to be `/client`. On a deployment
> that never set `basePath`, the client now lives at `/v2/client/` and a saved `/client/` bookmark no
> longer reaches it. There is no redirect. With the Control UI at the gateway root (the default),
> `/client/` is now answered by the Control UI; with the Control UI disabled it is a plain `404`.
> Tell your users the new address, or pin the old one explicitly with `"basePath": "/client"`.
> Deployments that already set `basePath` are unaffected, and so is `wednesdayai web serve`, whose
> default stays `/`.

## Origins, HTTPS and secure context

* **`gateway.webClient.allowedOrigins` is mandatory.** The gateway refuses an
  `openclaw-user-client` websocket from any origin not listed there, under every
  `gateway.auth.mode` and even behind a reverse proxy. `gateway.controlUi.allowedOrigins` never
  admits this client. List exact origins (`scheme://host[:port]`), for example
  `https://chat.example.com`. The default is empty, which admits nothing.
* **Use HTTPS and `wss://` outside loopback.** The client stores its device credential in browser
  storage and signs each connect with WebCrypto, which browsers expose only in a
  [secure context](https://developer.mozilla.org/docs/Web/Security/Secure_Contexts): HTTPS, or
  `http://localhost` / `http://127.0.0.1` for development. A plain `http://` page on a LAN address
  cannot mint a device identity.
* **Do not mix schemes.** An HTTPS page cannot open a `ws://` socket. Serve the client over HTTPS
  and point `gatewayUrl` at `wss://`.
* **Location sharing and the screen wake lock need a secure context too.** The client's
  **Share location** toggle and its screen-stays-awake behaviour (ADR 0121) use
  `navigator.geolocation` and `navigator.wakeLock`, which browsers expose only in a secure
  context: on a plain-`http://` page the location button renders dimmed and the wake lock is a
  no-op. HTTPS hosting covers both.
* **Geolocation permission is granted by the serving host, not by the gateway config.** On the
  gateway route the client's documents carry `Permissions-Policy` with `geolocation=(self)`
  (above). `wednesdayai web serve` and a CDN you host yourself send no `Permissions-Policy` at
  all, which browser defaults treat as allow-for-the-page-itself, so the toggle works there too -
  again, only over HTTPS.
* The client sends a browser `Origin` header on connect; a mismatch closes the socket with code
  `1008`. Pair the client with `wednesdayai qr --client openclaw-user-client`, which prints the
  configuration key to fix if the origin is not yet allowed.

## Gateway restarts and client reconnects

A gateway restart closes every client websocket with close code `1012` (`service restart`),
including sockets that finished the HTTP upgrade but not the connect handshake, and terminates any
socket still open 5 seconds later. The web client recovers from this without user action, so a
restart needs no change to the serving layer and no re-pairing:

* **Automatic reconnect.** The client retries with exponential backoff, and immediately when the
  tab becomes visible again, the page is restored from the back/forward cache, or the network comes
  back. A liveness watchdog closes a socket that has carried no frame for two tick intervals
  (`hello-ok` `policy.tickIntervalMs`, default 30 s) with close code `4000` (`tick timeout`) and
  reconnects, so a silently dead socket never pins the client. When the page becomes visible, a
  nominally connected socket that has been silent for more than 5 seconds is not trusted until
  the watchdog: the client probes it with a `health` request and reconnects when the probe times
  out after 5 seconds.
* **Onboarding is not re-triggered.** Transient connect failures - the restart window
  (`RECOVERY_NOT_READY`, `UNAVAILABLE`), auth rate limiting (`AUTH_RATE_LIMITED`), nonce and
  signature refresh codes, or a socket close during the handshake - keep the paired device
  credential; the client only reschedules its reconnect, honouring the server's `retryAfterMs`
  (rate limiting backs off to 15 s). Any other `connect` refusal - a credential the gateway no
  longer accepts (`AUTH_DEVICE_TOKEN_MISMATCH`) is the common example - sends the user back to
  onboarding.
* **Replies survive a drop.** After reconnecting, the client reconciles its own runs against
  `sessions.runs.list`: a reply that finished in the gap is shown once from the transcript
  (deduplicated against what was already streamed, and replayed into the live stream before the
  turn ends), one still running keeps streaming, and one the restart interrupted shows the notice
  **The gateway restarted before this reply finished. Your message was delivered; send it again
  to retry.** A run whose frames stop for 15 seconds while the socket still looks connected is
  re-checked the same way, so a reply never stays frozen. A send, steer or direct-session RPC
  (`sessions.steer`, `sessions.direct`) retries transient connection errors within a 60 s window;
  a send whose retries run out puts the text back in the composer instead of dropping it, and
  `talk.catalog` is retried - Dictate keeps its last known availability instead of latching
  unavailable after one failed read. `agents.list` and `models.list` are fetched again on every
  reconnect, so a restart or a first failed fetch cannot empty the sidebar or the model menu.
* **Thread order survives a drop too.** The thread is append-only: committed rows keep the order
  the gateway saved them in, and live rows are appended at the bottom, so a reconnect or a reload
  cannot move a sent message below later replies. A message sent while a reply streams waits at
  the bottom marked **Queued** until it joins that reply or starts its own turn, and one sent
  while another message of yours is already waiting queues behind it (ADR 1966). A reply to a
  message from an older session - above a **New session** divider - keeps its quote. The
  chat is continuous across the gateway's idle, daily and `/new` resets: a **New session**
  divider marks where a fresh session began, every earlier message stays above it, and
  **Load older** continues into the older sessions. The reads span earlier sessions only when the
  gateway advertises `chat.history.spanTranscripts`; against an older gateway the web client reads
  only the current session - no divider, no older-session paging. One known gap remains: a
  **Queued** badge and the composer's queue mode go stale when a reconnect loses a queued
  follow-up's start frames, clearing only on the next history load or when a later own reply
  finishes and `sessions.runs.list` reports the queued run terminal (#1878).
* **Nothing typed or sent is lost.** Composer drafts are kept per chat in `localStorage`
  (including the composer before a chat is open) and survive a reload, a tab close and a crash;
  they are dropped after 7 days or on logout. Every send is also recorded in a `localStorage`
  outbox before the call, and the entry is removed only once the gateway has acknowledged it
  (entries expire after 24 hours). An unacknowledged send - a failed RPC, a reload or crash
  mid-send, a lost ack - returns to the composer with the notice **Restored a message that was
  not sent.** the next time its chat loads; a send the loaded history proves delivered is
  dropped silently. Both stores are cleared on logout.

User-client disconnects are logged, so drops are measurable in the gateway log:

```text theme={"dark"}
user-client disconnected code=1012 reason=service restart conn=<uuid> durationMs=<ms>
```

The webchat disconnect line is unchanged. See [Logging](https://docs.wednesdayai.dev/next/admin/gateway/logging.md) for where the gateway
file log lives and how to follow it.

## Chat terminal events and transcript durability

The `chat` events that end a run - `final` and `error` - are broadcast only after that run's
transcript writes are durable, so a client that re-reads the chat when the event arrives sees the
finished reply (ADR record: `dev-docs/adr/0089-chat-terminal-events-post-durable.md`). The wait is
bounded at 5 seconds. If a write has not settled within the bound, the event is broadcast anyway
and the gateway logs a warning:

```text theme={"dark"}
chat terminal broadcast before transcript durability (timeout)
```

The line carries the run id, the session key and the bound in milliseconds, under the
`gateway/chat-final` subsystem. An aborted run already behaved this way, with its own 10-second
save-then-announce bound (see [Protocol](https://docs.wednesdayai.dev/next/admin/gateway/protocol.md#operator-helper-methods)).

### If the timeout warning appears

Once in a while, under a burst of writes, it is harmless: the event was still delivered, up to
5 seconds late. If it appears regularly, session-storage writes are slower than the
5-second bound - check the store backend (`session.storage.backend`; on Postgres, connection
saturation, lock contention and slow queries). Clients do not lose messages over it: they keep
what a reply had already streamed and re-read the chat on the next event, so the cost is latency,
not lost replies.

## config.json

Fields, all public by construction - never put a token or any per-user value here:

| Field | Required | Meaning |
| - | - | - |
| `schemaVersion` | yes | Must be `1` |
| `gatewayUrl` | yes | Absolute `ws://` or `wss://` gateway URL, no query or fragment |
| `clientId` | yes | Must be `openclaw-user-client` |
| `basePath` | yes | Public path the bundle is served under, with a trailing slash |
| `assistantName` | no | Brand name; the fallback when an assistant has no resolved name |
| `features` | no | Feature flags; currently `voice` only, **deprecated and ignored** |

`features.voice` is deprecated and has no effect; leave it unset. Dictate's and Voice mode's
availability are both driven by `talk.catalog` — Dictate needs a configured streaming
transcription provider and the operator's `talk.conversation.enabled` gate on; Voice additionally
needs a configured streaming speech provider (cascaded engine) or an active realtime provider
(`realtime` engine) — not by a client feature flag; see ADR 0088 item 12
as amended. Setting `features.voice`/`--voice`/`OPENCLAW_WEB_FEATURE_VOICE` changes nothing users
can see; it is kept as a no-op alias for one release (AGENTS.md's deprecated-alias rule) and will
be removed in a later release.

Example:

```json theme={"dark"}
{
  "schemaVersion": 1,
  "gatewayUrl": "wss://gateway.example.com",
  "clientId": "openclaw-user-client",
  "basePath": "/",
  "assistantName": "WednesdayAI"
}
```

Unknown keys are rejected, not ignored: the client shows a configuration error instead of starting
half-configured.

## What the client needs from the gateway

The client connects with exactly two scopes, `operator.sessions.read` and `operator.sessions.write`,
which its setup code mints and its device token is bound to (see
[Protocol](https://docs.wednesdayai.dev/next/admin/gateway/protocol.md#client-identity)). It never holds `operator.read`, `operator.write` or
`operator.admin`, so the gateway refuses every method outside the two allowlists below with
`missing scope`. The sources of truth are `NARROW_SESSION_READ_METHODS` and
`NARROW_SESSION_WRITE_METHODS` in `src/gateway/method-scopes.ts`; see
[Narrow scope method allowlist](https://docs.wednesdayai.dev/next/admin/gateway/protocol.md#narrow-scope-method-allowlist) for the full lists.

Methods the client calls with `operator.sessions.read`:

| Method | What it powers |
| - | - |
| `status`, `models.authStatus` | Start-up checks: the connection is alive, and the gateway has a model provider credential |
| `agents.list` | The assistant picker, the sidebar's assistants, and the names, avatars and colours the chat surfaces show. Fetched again on every reconnect |
| `models.list` | The model menu, and whether Think is available for the chat's model. Fetched again on every reconnect |
| `sessions.list` | The sessions list, with the assistant filter, search and paging |
| `sessions.describe` | The open session's own row: title, model and Think level |
| `sessions.direct` | The device's direct session for an assistant, computed by the gateway (ADR 0109) so assistant picks land in the dmScope-correct session. Retried on transient connection errors |
| `sessions.subscribe` | Live `sessions.changed` events, so the list refreshes when another device changes a session |
| `chat.history` | Loading a chat and its older messages - spanning earlier sessions when the gateway advertises `chat.history.spanTranscripts` - and learning the chat's latest message so a send can notice the chat changed elsewhere |
| `identity.self` | The **Linked accounts** dialog: who this browser is (`Signed in as …`) and the person's linked accounts, read from the verified device id (see [Identities](https://docs.wednesdayai.dev/next/admin/gateway/identity)) |
| `talk.catalog` | Whether Dictate and Voice mode are available for this connection. Retried up to 3 times on failure; the last known availability is kept instead of latching unavailable |
| `tts.readAloud.status` | Whether the **Read aloud** button and the **Read replies aloud** auto-read toggle are available, and the text limit the client caps both paths' chunks to |
| `chat.surfaces.list`, `chat.surfaces.get` | Assistant UI: the chat's published surfaces and their revisions, and whether the `ui-surfaces` plugin is enabled (see [Assistant UI and Canvas](#assistant-ui-and-canvas)) |

Methods the client calls with `operator.sessions.write`:

| Method | What it powers |
| - | - |
| `chat.send` | Sending a message, optionally quoting an earlier message (`replyToId`, with `replyToTranscriptId` naming the earlier session when the quoted message predates the current one) and guarding against a chat that changed elsewhere (`expectedLeafEntryId`). Attachments ride the send as `uploadId` references to files uploaded over `POST /v2/uploads` (see [Attachment uploads over HTTP](#attachment-uploads-over-http)). When the user turned on location sharing, the send carries an optional `location` object - the device fix for that message, shown to the assistant as untrusted metadata on that turn only and stripped from history. The `uiAction` parameter submits an assistant-composed form: it carries no message body and starts the next turn (see [Assistant UI and Canvas](#assistant-ui-and-canvas)) |
| `chat.surfaces.pin` | Pinning a surface to the top of the Canvas panel |
| `chat.abort` | Stop |
| `sessions.steer` | While a reply streams, Send (or Enter on desktop) adds to the current turn (`inject`, falling back to `queue`). With a file attached, Send queues (`queue`). Send after reply and desktop Ctrl/Cmd+Enter queue. On touch devices Enter inserts a newline and Ctrl/Cmd+Enter does what Send does. A steer can carry the same optional `location` object as `chat.send`. Transient connection errors are retried within a 60 s window, keeping the same idempotency key so the gateway's dedupe still applies. A dictated auto-send finishing while a reply streams takes this same route |
| `sessions.patch` | Rename, model, Think, Send reasoning and archive state. Only `label`, `model`, `thinkingLevel`, `reasoningLevel` and `archived`; any other field is refused |
| `sessions.title.prepare` | Suggest a title |
| `talk.session.create` | Start Dictate (`transcription`) or Voice mode (`stt-tts`, or `realtime` — the operator-chosen speech-to-speech engine). Voice mode carries the optional `readMode` and `speed` when the user picked them (see [Voice and audio settings](#voice-and-audio-settings)). Refused while `talk.conversation.enabled` is false; a `realtime` create is also refused while `talk.conversation.engine` is not `"realtime"` … |
| `talk.session.appendAudio` | Stream microphone audio into that session |
| `talk.session.bargeIn` | Report a local interruption while reply speech is playing |
| `talk.session.mark` | Acknowledge played reply audio, in milliseconds of audio played for that turn. Realtime sessions send a session-monotonic timestamp (the bridge's playback tracker rejects backwards timestamps); cascaded sessions keep the played-audio offset the relay maps through its alignment timeline |
| `talk.session.update` | Push a changed read mode / synthesis speed to the live Voice session, so it applies from the session's next synthesised clause (see [Voice and audio settings](#voice-and-audio-settings)) |
| `talk.session.cancelTurn` | Cancel the current voice turn |
| `talk.session.close` | End Dictate or Voice mode |
| `tts.speak` | The **Read aloud** button on replies, the **Read selection** action, and the **Read replies aloud** auto-read toggle: synthesize reply text into inline audio to play. Read aloud and Read selection carry the optional `readMode` and `speed` when the user picked them (see [Voice and audio settings](#voice-and-audio-settings)). Auto-read speaks a streaming reply sentence by sentence, so one reply can produce several `tts.speak` requests, each under the advertised `maxTextLength` |
| `identity.link.claim` | Redeeming a `/link` code in the **Linked accounts** dialog: links `<channel>:<id>` to this person and approves the pairing code. Rate limited per device and per person (see [Identities](https://docs.wednesdayai.dev/next/admin/gateway/identity#proofs-of-control)) |
| `identity.logout` | **Log out**: removes the paired device server side, unlinks its `device:<deviceId>` value and clears the browser credential and keypair |

Gateway settings that decide what users can do with those methods:

* **Models.** `agents.defaults.models` bounds the model menu and what `sessions.patch` and
  `sessions.create` accept. Set it before you expose the client: left empty, the menu lists the whole
  catalog and any `provider/model` reference that parses is accepted. See
  [Configuration reference](https://docs.wednesdayai.dev/next/admin/gateway/configuration-reference.md#agentslistidentitycolor).
* **Assistants.** The picker lists the agents the gateway's `agents.list` method returns: every
  `agents.list` entry in config plus the default agent, or, with none configured, the default agent
  plus each agent directory under the gateway state directory. `identity.name` and `identity.color`
  set how each one looks; an assistant with no colour gets a stable one derived from its id. A
  configured `agents.list[].name` wins over the identity name, and an `agents.list[].description`,
  if set, appears as a tooltip on the sidebar row and in the assistant picker. An
  agent with `agents.list[].userFacing: false` is internal: the gateway omits it (and its sessions
  and runs) from every user-client answer, so web-client users never see it in the picker, the
  sidebar or their chat lists — only operators do. See
  [`userFacing`](https://docs.wednesdayai.dev/next/admin/gateway/configuration-reference#agentslist-per-agent-overrides).
* **Read aloud.** `messages.tts.readAloud.enabled` (default on) decides whether users see the
  **Read aloud** button; an assistant's own `agents.list[].tts.readAloud.enabled` overrides it for
  that assistant. With the gate on but no TTS provider configured, the button still shows as
  unavailable. While a Voice conversation is active (listening, thinking or speaking), it is
  unavailable, and starting Voice mode stops any playback in progress. The composer's
  **Read replies aloud** toggle rides the same gate: with it on, a streaming reply is spoken
  sentence by sentence while it is written, each chunk capped at the `maxTextLength` the status
  reports. The toggle is a per-browser preference (default off) with no gateway setting yet - an
  operator-side per-assistant default is tracked as finding #1347. See
  [Text-to-speech](https://docs.wednesdayai.dev/next/users/tts.md).
* **Suggest a title.** Each use sends the chat's first message (up to 1000 characters) to the
  assistant's default model - the agent's configured model, not the model picked for the chat. The
  limit is 3 calls per 60 seconds per device and address, and it cannot be changed.
* **Reach.** A paired client can read, send to and change the five `sessions.patch` settings of any
  session on the gateway, including channel and sub-agent sessions; per-session ownership does not
  exist yet (ADR 0077 section 5, ADR 0083). Pair only people who should have that reach.

Adding to the current turn, Send after reply, replies and the notice that a chat changed elsewhere
need no gateway setting.

### Attachment uploads over HTTP

File attachments no longer ride the WebSocket. The browser POSTs each file to `POST /v2/uploads`
on the gateway's HTTP origin with its paired device credential, and the subsequent `chat.send`
references the upload by `uploadId`. The deployment must satisfy:

* **Origin.** The endpoint enforces the same origin allowlist as the websocket connect: the
  browser's origin must be in `gateway.webClient.allowedOrigins`, and the browser must be able to
  reach the gateway's `http://`/`https://` origin, not only its `ws://`/`wss://` one. The
  endpoint sits at the gateway root (`/v2/uploads`); the web client's `basePath` is irrelevant.
* **Body size.** The per-file cap is 50 MiB (`CLIENT_UPLOAD_MAX_BYTES` in
  `src/gateway/client-uploads-http.ts`); there is no total-size limit per message. A reverse proxy
  in front of the gateway may impose a smaller request-body limit (nginx's `client_max_body_size`
  defaults to 1 MiB): raise it to at least 50 MiB, or large attachments are refused with `413`
  before the gateway sees them.
* **CSP.** `wednesdayai web serve` sends a `Content-Security-Policy` whose `connect-src` already
  includes the gateway's http(s) origin alongside its `ws:`/`wss://` one (see
  `src/static-host/static-app.ts`); the gateway route does the same. A self-hosted bundle must
  match (see [Rules the host must follow](#rules-the-host-must-follow)).
* **Lifetime.** An upload that is never sent is deleted by the gateway's sweep after 24 hours;
  there is no DELETE route. Each upload is bound to the paired device that uploaded it: another
  device's `chat.send` cannot consume it, and a consumed `uploadId` cannot be replayed.
* **Staging quota.** A device may hold at most 64 staged files (including in-progress
  uploads) totaling 1 GiB. An upload that would breach either limit is refused with
  `429 UPLOAD_QUOTA_EXCEEDED` before the body is accepted.
* **Errors.** Every refusal answers
  `{ "ok": false, "error": { "code": ..., "message": ... } }`: `403 FORBIDDEN_ORIGIN` (the
  browser's origin is not in `gateway.webClient.allowedOrigins`, or the request carries no
  `Origin` header), `401 UNAUTHORIZED` (a missing, invalid or revoked device token, or a token
  whose scope set lacks `operator.sessions.write`), `400 EMPTY_BODY`, `413 PAYLOAD_TOO_LARGE`,
  `429 UPLOAD_QUOTA_EXCEEDED` (the device's staging quota is full), and `500 UPLOAD_FAILED`
  (the body could not be stored). Repeated failed authentications feed
  the same device-token auth rate limiter as the WebSocket connect: once the bucket empties, the
  endpoint answers `429` (`rate_limited`) with a `Retry-After` header until then.

### Link this device

Each paired browser mints its own device credential, and the gateway identifies that browser's
turns by `device:<deviceId>`. Assistants with workspace lanes keep a private workspace per person,
so a device must be linked to a person; an unlinked device gets a denial message in the chat
naming the `device:<deviceId>` value it needs linked.

List device ids with `openclaw devices list --json` (the `deviceId` field of each entry under
`paired`). Link a device with `wednesdayai devices link <deviceId> --identity <key>`, or pair with
`wednesdayai identity link <key> --qr` so the first connect links it (`devices remove` also
unlinks). After ADR 0104 the person is the sender name: turns from a linked device show
`Alice (device:…)` to the model, with the browser's display name as a separate provenance field.
See [Identities](https://docs.wednesdayai.dev/next/admin/gateway/identity),
[Workspace Lanes](https://docs.wednesdayai.dev/next/developers/concepts/workspace-lanes.md#linking-gateway-devices) and [devices](https://docs.wednesdayai.dev/next/users/cli/devices.md).

## Linked accounts, sign-in and logout

The sidebar **account menu** has a **Linked accounts** entry. It opens a dialog that shows who this
browser belongs to (`Signed in as <person>`) and the person's linked accounts. If the browser is
paired but not linked to a person yet, the dialog instead shows:

```
This browser isn't linked to a person yet. Ask your administrator to run:
wednesdayai devices link <deviceId> --identity <name>
```

**Linking a chat account.** In the dialog's form, a linked person can claim their own chat
account: send `/link` to the bot in a direct message, then enter the one-hour code it replies
with. A successful claim links `<channel>:<id>` to this person and approves the pairing request,
so the chat account can pass `dmPolicy: "pairing"` gates. The gateway refuses the whole flow when
`gateway.webClient.accountLinking` is `false`. See
[Identities](https://docs.wednesdayai.dev/next/admin/gateway/identity#proofs-of-control).

**Signing in.** When the `identity-oidc` plugin is enabled, the pairing screen shows
**Continue with ...** buttons (Google, Microsoft Entra, GitHub) above the setup-code form.
Signing in links the browser to your person and pairs the device in one step; no setup code is
needed. See [Identity OIDC](https://docs.wednesdayai.dev/next/developers/plugins/identity-oidc).

**Enrollment links.** A `#setup=<token>` link (from OIDC sign-in or a setup code) is redeemed
automatically only on an unpaired browser; if an earlier auth failure left a half-signed-in
keypair behind, that redemption rotates it so the old device id is never reused. If the browser is
already paired, the client asks for
confirmation first, because re-pairing logs this device out and moves its link to the new person:
*Pair this browser again* proceeds, *Keep the current session* leaves everything unchanged.
Sign-in failures land back on the client with `#oauthError=<reason>` and a plain-language message.

**Log out.** The account menu's **Log out** asks the gateway to remove the paired device and unlink
its `device:<deviceId>` value (best effort, 3 s), then always clears the stored credential and the
browser keypair; if the gateway was unreachable, an operator removes the device with
`wednesdayai devices remove <deviceId>`. The next
sign-in pairs a fresh device, because a paired browser belongs to exactly one person.

## Assistant UI and Canvas

The assistant can compose interactive UI for the web chat: forms, choice pickers, tables, simple
charts and progress, rendered inline in the reply that produced them, directly after the step
that showed them. Each chat also gets a **Canvas** panel (the top-bar toggle) listing every
surface the assistant published in that chat at its latest revision; pins survive a reload and a
gateway restart. Each tool step appears live
as a tool line inside the reply that ran it (from the `chat.activity` event, which carries the
step's display name and, on start, a redacted, length-capped display verb and detail - what the
step is doing, such as the file being read or the command being run - never its raw arguments or
results), in order with the reply's text, which arrives complete before the next step appears.
When the turn is stored, the same line gains its result in place; the stored line resolves its
label from the same arguments the live verb/detail came from, so the two do not drift (the one
exception is a live label that redaction or the cap shortened), and the
line never moves or disappears, also after a reload. Every assistant row of one run renders as a
single reply block.

This is the bundled `ui-surfaces` plugin, and it is **off by default** (ADR 0034). Enable it
explicitly, then restart the gateway:

```json5 theme={"dark"}
{
  plugins: {
    entries: {
      "ui-surfaces": { enabled: true },
    },
  },
}
```

* **Per-agent opt-out.** An agent never offers the tool while its `tools.deny` list contains
  `"show_ui"`; the usual tool policy precedence applies.
* **What users see.** With the plugin on, a `show_ui` step renders inline and in Canvas, a submit
  shows a "You submitted" chip and starts the next chat turn, and a pinned surface lists first.
  While a submit is in flight the button label switches to "Queued"; once accepted the form locks,
  the button reads "Submitted", and the thread shows the chip `You submitted "<button label>"`.
  A stale revision renders the banner "Updated: open latest in Canvas"; Canvas always shows the
  latest revision. Refusals render as one of: "This action could not be sent.", "This response is
  too large to submit.", "Assistant UI is off.", "This surface is unavailable.", "This form has
  been updated. Open the latest in Canvas to continue.", "This action is no longer available.",
  "Some values were not accepted. Check the fields and try again.", "This form was already
  submitted.", "Could not reach the assistant. Try again." With the plugin off,
  `chat.surfaces.list` answers `enabled: false` and the Canvas toggle reads
  "Assistant UI is off". The tool is also absent from runs whose connection did not advertise the
  `ui-surfaces` client cap - the web client always advertises it. The developer contract, the
  storage placement and the config overrides are in [ui-surfaces plugin](https://docs.wednesdayai.dev/next/developers/plugins/ui-surfaces).
* **Storage.** Surfaces live in the plugin's own tables on the configured session backend
  (sqlite by default, Postgres in the `plugin_ui_surfaces` schema), keyed by session id and never
  deleted, so `/new` and a session reset start an empty Canvas without touching old rows.

### What it never does

* **No agent-authored code reaches the browser.** Everything on screen is declarative JSON
  validated against a fixed component catalog before it is stored: no expressions, no functions,
  no remote catalogs, and the client performs no remote fetch beyond the image origins below.
* **A submit never authorizes anything.** It only starts the next chat turn with the submitted
  values as input. A submitted value of `/new` (or any other slash command) is inert text - it
  does not reset the session.
* **Every budget is a refusal, never a silent prune.** An oversized or malformed surface is
  rejected whole (`show_ui rejected: <rule>: <detail>`), and a submit is accepted once per
  surface revision; a replayed or forged submit is refused with a reason and starts nothing.

### Remote images

Assistant output can include images. Only these render: images served by the gateway itself
(same-origin media), inline `data:image/` attachments, and remote `https://` origins you allow
explicitly. Everything else renders as a plain link - labelled with the image's alt text, or the
URL when there is no alt - and the browser never requests it, so agent output cannot turn a
remote image into a tracking or exfiltration channel.

Each entry must be an exact `https://host[:port]` origin with no path, query or fragment. There
is one source per hosting shape:

| Shape | Where |
| - | - |
| Gateway route | `gateway.webClient.imageOrigins` in the gateway config |
| `web serve` | Repeatable `--image-origin <origin>` flag, or `OPENCLAW_WEB_IMAGE_ORIGINS` (comma-separated) |
| Container | The same `OPENCLAW_WEB_IMAGE_ORIGINS` environment variable |

The client's `Content-Security-Policy` `img-src` is extended by exactly these origins. The
packaged servers send that policy automatically; a self-hosted bundle should match it (see
[Rules the host must follow](#rules-the-host-must-follow)).

## Themes and appearance

The client has four theme modes, chosen by each user from the account menu at the bottom of the
sidebar. You do not configure them; there is no `config.json` or gateway setting for the theme.

| Mode | Behaviour |
| - | - |
| **Auto** | Follows the browser's `prefers-color-scheme` (dark/light), or `prefers-contrast: more` when the operating system requests higher contrast. |
| **Dark** | Always dark, regardless of the operating system setting. |
| **Light** | Always light, regardless of the operating system setting. |
| **High contrast** | Maximum-contrast palette (WCAG AA or better) for low-vision or bright-environment use. |

* The choice is stored per browser (`localStorage`, key `openclaw.web.theme`) and applies
  immediately, with no reload. The default is Auto.
* A browser that stored the retired `black` or `white` mode is migrated on first load: `black`
  becomes `dark`, `white` becomes `light`, and the migrated value is written back.
* The theme also sets the browser's native colours for scroll bars and form controls
  (`color-scheme`), so they follow the chosen theme instead of the operating system. In high
  contrast, text on accent-coloured fills switches to dark for legibility.
* Entrance animation is skipped when the browser's `prefers-reduced-motion` is set.
* Colours and fonts (Inter, Space Grotesk and JetBrains Mono) are bundled with the client and
  served from the same base path, so a deployment needs no font CDN. The host's
  `Content-Security-Policy` still has to allow them: `font-src 'self'` is enough (see
  [Rules the host must follow](#rules-the-host-must-follow)). They come from the same shared token
  package as the [Control UI v2](https://docs.wednesdayai.dev/next/admin/web/control-ui-v2.md) console; developers see [Brand tokens](https://docs.wednesdayai.dev/next/developers/reference/brand-tokens.md).

## Navigation and transcript preferences

Navigation and transcript display settings are client-side, browser-local state. They are not
stored in gateway configuration or `config.json`, and changing them does not require a gateway
restart, page reload, or bundle rebuild.

The browser stores navigation preferences separately for each gateway URL and client ID under
`openclaw.web.navigation:<encodedGatewayUrl>:<clientId>`. Transcript display preferences use the
`openclaw.web.transcript-display.v1` key, which contains a record keyed by
`<gatewayUrl>|<clientId>`. Missing, invalid, or unreadable saved preferences load defaults.
If a storage write fails, the new choice still applies in memory while the page is open, but
a reload can restore the older saved value or a default. Navigation and chat remain usable.

The defaults and available choices are:

| Preference | Default | Options |
| - | - | - |
| Assistant sort | `newest` | `name-asc`, `name-desc`, `newest` (labelled **Recent**) |
| Assistant activity window | `4` hours (`activityWindowHours: 4`) | `1`, `2`, `4`, `8`, `16`, `24`, or `null` for all activity |
| Show internal sessions | `false` (`includeInternal: false`) | `true`, `false` |
| Chat sort field | `updatedAt` (`chatSortBy: "updatedAt"`) | `updatedAt`, `title`, `key` |
| Chat sort order | `desc` (`chatSortOrder: "desc"`) | `asc`, `desc` |
| Show reasoning | `false` (`showReasoning: false`) | `true`, `false` |
| Tool details | `minimum` (`tools: "minimum"`) | `hide`, `minimum`, `collapsed`, `full` |
| Read replies aloud | `false` (`autoRead: false`) | `true`, `false` |

A saved assistant sort of `oldest` (no longer offered) loads as `newest`.

The **Read replies aloud** toggle uses its own storage key,
`openclaw.web.auto-read:<encodedGatewayUrl>:<clientId>`, holding `1` or `0` per gateway URL and
client ID like the other preferences. With it on, the client also sends dictated turns
automatically when the user pauses, and shows the pause chip beside the speaker. That pause is a
browser-local choice too: `openclaw.web.auto-send-delay:<encodedGatewayUrl>:<clientId>` holds one
of `1500`, `2500` or `4000` (default `2500`; anything else loads the default). It only applies
while auto-read is on. The **Share location** toggle stores `1` or `0` under
`openclaw.web.share-location:<encodedGatewayUrl>:<clientId>` (default `0`). There is no
gateway-side default for either; an operator-level per-assistant auto-read default is tracked as
finding #1347. See ADR 0121 for what the location toggle sends.

### Voice and audio settings

The account menu's **Voice & audio** section (and the composer's playback chip) control how
speech sounds. All of it is browser-local: one JSON document under
`openclaw.web.voice-audio:<encodedGatewayUrl>:<clientId>` holds the read mode, volume and speed
per gateway URL and client ID, with clamped defaults (`gain` 1, `speed` 1) when the key is
missing, invalid or unreadable. There is no gateway-side default and nothing is synced to the
account.

* **Read mode** (account menu only): **Literal**, **Human** (default) or **Hybrid**. A chosen
  mode is sent as `readMode` on the next `tts.speak` and Voice session create; when the user has
  not picked one, nothing is sent and the gateway's `messages.tts.naturalize` setting decides -
  the UI shows **Human** selected because that is what the server default resolves to. See
  [Read modes](https://docs.wednesdayai.dev/next/users/tts.md#read-modes) for what each mode does.
* **Volume boost**: a 50 to 300 percent slider applied as client-side playback gain; values clamp
  to 50 to 300 percent, and the playback output chain limits the signal so boosted audio stays
  unclipped. Applied to Read aloud playback and Voice mode playback as soon as it changes.
* **Speed**: a 0.75 to 2 times slider (step 0.25) sent as `speed` on synthesis requests. Speed is
  provider-native with natural pitch - the Kokoro provider honours it, other providers ignore it
  for now. In Read aloud it applies from the next chunk the gateway synthesizes. In Voice mode a
  speed or read-mode change is pushed to the live session as `talk.session.update` and applies
  from the session's next synthesised clause (clauses already synthesised keep their settings);
  with no live voice session the values ride the next `talk.session.create` instead.
* The **playback chip** in the composer (beside the auto-send pause chip, labelled with the
  current speed, for example `1×`) offers the volume and speed sliders without the read mode; the
  account menu owns that choice.

**Read selection**: with text selected inside one assistant reply, the reply's actions row grows
a **Read selection** control that reads only the selected text through the same Read aloud
engine. Reading a section means selecting it; there is no separate per-heading control.

Composer drafts and unsent sends are `localStorage` on the device too, not gateway state: drafts
under `openclaw-user-client:draft:<sessionKey>` (empty-state composer: `...:draft:@new`, 7-day
expiry) and the send outbox under `openclaw-user-client:outbox:v1` (24-hour expiry). A draft or
outbox entry stays on the device until it is sent, it expires, or the user logs out - logging out
clears both. On a shared device, text a user typed but did not send remains readable in browser
storage by whoever uses the same browser profile until it is cleared; treat this like the other
browser-local preferences when advising where the client may be used.

Assistants picked in the **Browse assistants** window stay visible in the sidebar for the current
page session only: the client keeps the picked assistant ids in memory (`pickedAgentIds`, a
session-only list that is never written to storage) so they stay listed past the activity
window until a reload. The selected assistant filter itself still persists as
`selectedAgentId` under the navigation key. When a filtered page of `sessions.list` returns,
the client merges that page's `agentActivity` into its existing map instead of replacing it, so
picking one assistant no longer blanks the activity of the others already on screen.

> [!WARNING]
>
> Navigation filters are not authorization boundaries. Hiding internal sessions or filtering the UI
> by recency or assistant changes only what the browser displays; it does not change RPC
> authorization. Enforce access through gateway authentication and permission policy, not these
> client-side preferences.

For `sessions.list`, the client sends `includeInternal`, `sortBy`, `sortOrder`, and
`includeAgentActivity: true`. When `includeInternal` is `false`, the gateway applies the shared
`isUserFacingSessionKey` rules: session keys whose root segment is `acp`, `cron`, `hook`,
`heartbeat`, or `subagent` are excluded, as are isolated heartbeat keys such as `main:heartbeat` and
`dashboard:*:heartbeat`. A session whose persisted entry records the a2a channel -
assistant-to-assistant traffic (`entry.channel` or `entry.lastChannel` of `a2a`) - is returned as
internal as well, so clients group it with the other background sessions.

Deploy matching web client and gateway versions together. A newer bundle can send
`includeInternal`, `sortBy`, `sortOrder`, and `includeAgentActivity` to `sessions.list`; an older
gateway with strict schema validation could reject fields it does not recognize. Older web client
versions do not send these fields.

### Diagnose missing sessions

Check these display filters before investigating gateway storage:

1. **Time window:** The assistant activity window defaults to 4 hours and narrows the assistant
   list, not the age of sessions. Select **All** to include inactive assistants, or **All
   assistants** to search sessions without an assistant filter.
2. **Internal sessions:** Heartbeats, cron runs, subagents, and other background sessions are hidden
   by default. Enable **Show internal** (`includeInternal: true`) in the sessions menu.
3. **Selected assistant:** The sessions list follows the active assistant. Check whether the session
   was created under a different assistant ID.

### Diagnose missing reasoning or thought transcripts

Reasoning is hidden by default (`showReasoning: false`). The client renders no reasoning element
at all. Enable **Show reasoning** in the **Display** menu or chat display preferences and those
blocks appear as collapsed disclosures. If the model or gateway did not produce reasoning blocks,
enabling the preference shows nothing because the transcript has no reasoning content to display.

## What users see that is not live yet

Some controls are drawn but switched off, with a tooltip naming the tracked finding that enables
them. Selecting one sends nothing to the gateway. They are: the **Feedback** and **Regenerate**
actions on replies; **Settings** and **Keyboard shortcuts** in the account menu. **Add extension**
cites the extension marketplace item (GitHub #1331) instead; **Feedback**, **Regenerate**,
**Settings** and **Keyboard shortcuts** cite their own tracked finding (GitHub #696-#700) instead.
**Memory** and **Calendar** are no longer fixed to this list: they turn on when the operator
allowlists a chat UI plugin that provides those panels - see
[Chat UI plugins](https://docs.wednesdayai.dev/next/developers/plugins/chat-ui). Without such a plugin they stay dimmed, citing the chat
panels item (GitHub #634). The assistant picker, per-assistant colour,
session filter and search, paging past the first page, the model switcher and Think, queue/steer
while a reply streams, rename and Suggest, and replying to a message are live (client-chat-v3
P2). Replies appearing on every open device without a reload, the busy and unread indicators,
the desktop-notification opt-in, Dictate and Voice mode's on/off state, and the automatic
resend into a chat changed elsewhere are also live. The 2026-10-25 client chat-flow slice added
more live behaviour, all client-side: assistants picked in the Browse assistants window stay in
the sidebar for the browser session, the chat area no longer overflows horizontally on narrow
screens, the composer's **Read replies aloud** toggle reads streaming replies sentence by
sentence and sends dictation when the user pauses, user messages render markdown, pasted rich
text (Word, Google Docs, web pages) converts to markdown in the draft, the copy button writes
structured rich text with a plain-text fallback, and large images are downscaled to at most
2048 px on attach. The 2026-11 client everyday slice added more: file attachments upload over the
gateway's authenticated HTTP endpoint with per-file progress and cancel instead of riding the
WebSocket, a very long plain-text paste becomes a `pasted-text.txt` attachment, sessions can be
archived from the top bar and hidden from the sidebar, assistant-to-assistant sessions group as
internal, assistants show their description on hover, and messages relayed from another
assistant's session carry the sending assistant's name; see
[Using the web client](https://docs.wednesdayai.dev/next/admin/web/using-the-web-client.md) for what users see.

One known gap remains: stopping a read-aloud does not cancel a `tts.speak` request already in
flight.

**Canvas** in the top bar is no longer on this list: it is live with the `ui-surfaces` plugin
enabled and explains itself when it is not (see
[Assistant UI and Canvas](#assistant-ui-and-canvas)).

They are not gated by any setting, so there is nothing to enable. If users ask, point them at
[Using the web client](https://docs.wednesdayai.dev/next/admin/web/using-the-web-client.md#controls-that-are-not-available-yet).

**Dictate** and **Voice mode** are not on this list: they render live or disabled per connection,
driven by `talk.catalog` and the operator's `talk.conversation.enabled` gate (see
[config.json](#configjson) above and
[Voice conversation sessions](https://docs.wednesdayai.dev/next/users/talk/realtime-voice-conversation)), not by a fixed release
phase.

**Read aloud** on replies is not on this list either. It is live by default and needs no
`config.json` field; the gateway's `messages.tts.readAloud.enabled` gate (per-agent override
`agents.list[].tts.readAloud.enabled`) turns it off, and it also shows as unavailable when no TTS
provider is configured - see [Text-to-speech](https://docs.wednesdayai.dev/next/users/tts.md) and
[Web client components](https://docs.wednesdayai.dev/next/developers/reference/web-client-components.md#read-aloud), plus the
"Gateway settings" list in
[What the client needs from the gateway](#what-the-client-needs-from-the-gateway). The composer's
**Read replies aloud** auto-read toggle is live under the same gate (see
[Navigation and transcript preferences](#navigation-and-transcript-preferences)); the dictation
auto-send it enables is client-side and needs no gateway method beyond the Dictate session
methods already listed.

## Rules the host must follow

If you serve the bundle yourself (CDN, nginx, object storage), reproduce what
`wednesdayai web serve` does:

| Path | Response |
| - | - |
| `/config.json` | your generated config, `Cache-Control: no-store` |
| `/index.html` and SPA routes | `index.html`, `Cache-Control: no-cache` |
| `/assets/*` (hashed filenames) | the file, `Cache-Control: public, max-age=31536000, immutable` |
| `/assets/*` that does not exist | `404` - never the SPA shell |
| `/manifest.webmanifest`, `/icon-192.png`, `/icon-512.png`, `/apple-touch-icon.png` | the file from the bundle root - the manifest as `application/manifest+json`, the icons as `image/png`; a missing one is `404`, never the SPA shell |
| any other unknown path | `index.html`, so the client router can handle it |

The four root files in that table are the home-screen install: the web manifest and the icons it
names, plus the Apple touch icon. `wednesdayai web serve` and the gateway route serve them from
the bundle automatically; when you host the bundle yourself, copy them up from `apps/web/dist`
with everything else and keep the manifest's `application/manifest+json` media type, the way
`src/static-host/static-app.ts` maps it. They let users install the web client to a phone or
tablet home screen (see
[Using the web client](https://docs.wednesdayai.dev/next/admin/web/using-the-web-client.md#install-the-web-client-on-your-home-screen)).

Send these headers on every response:

* `Content-Security-Policy` with `frame-ancestors 'none'`, `script-src 'self'`, `font-src 'self'`
  (the bundled fonts load from the same origin), and `connect-src` listing `'self'` plus the
  gateway origin with its `ws:`/`wss:` scheme and its `http:`/`https:` one - attachments upload
  over `POST /v2/uploads` (see [Attachment uploads over HTTP](#attachment-uploads-over-http))
* `X-Frame-Options: DENY`
* `X-Content-Type-Options: nosniff`
* `Referrer-Policy: no-referrer`
* If your host also serves agent-authored pages from the same origin (a canvas host, A2UI,
  plugin UIs), mirror the gateway route: `Permissions-Policy` granting `geolocation=(self)` on the
  client's responses with `Cross-Origin-Opener-Policy: same-origin`, and `geolocation=()` on the
  other pages' responses. A host that serves only this client can omit both headers: browser
  defaults let the page itself use geolocation, and there is no same-origin page to isolate from.

Caching `config.json` is the most common deployment mistake: a stale copy silently points the
client at the previous gateway.

## Related

* [Using the web client](https://docs.wednesdayai.dev/next/admin/web/using-the-web-client.md) - what your users see: pairing and chat
* [Control UI v2](https://docs.wednesdayai.dev/next/admin/web/control-ui-v2.md) - the operator console at the gateway root, a separate app with its own route
* [Brand tokens](https://docs.wednesdayai.dev/next/developers/reference/brand-tokens.md) - the shared colour and font package (developers)
* [Web client components](https://docs.wednesdayai.dev/next/developers/reference/web-client-components.md) - how the client UI is built (developers)
* [Gateway protocol](https://docs.wednesdayai.dev/next/admin/gateway/protocol.md) - client identity, scopes and the connect handshake
* [Configuration reference](https://docs.wednesdayai.dev/next/admin/gateway/configuration-reference.md) - every `gateway.webClient` key
* [Pairing QR and setup codes](https://docs.wednesdayai.dev/next/users/cli/qr.md) - onboarding a browser with `--client openclaw-user-client`
* [Identities](https://docs.wednesdayai.dev/next/admin/gateway/identity) - people, linked accounts and the four proofs of control
* [Identity OIDC](https://docs.wednesdayai.dev/next/developers/plugins/identity-oidc) - sign-in with Google, Microsoft Entra or GitHub


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.