Skip to main content

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 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:
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:
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

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

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. 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.
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.
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=()).
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, 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:
The webchat disconnect line is unchanged. See Logging 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:
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).

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: 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:
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). 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 for the full lists. Methods the client calls with operator.sessions.read: Methods the client calls with operator.sessions.write: 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.
  • 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.
  • 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.
  • 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).
  • 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.
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, Workspace Lanes and devices.

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:
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. 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. 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:
  • 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.
  • 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: 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).

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.
  • 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). They come from the same shared token package as the Control UI v2 console; developers see Brand tokens.
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: 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 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.
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. 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 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). They are not gated by any setting, so there is nothing to enable. If users ask, point them at Using the web client. 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 above and Voice conversation sessions), 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 and Web client components, plus the “Gateway settings” list in 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); 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: 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). 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)
  • 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.