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 smallconfig.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:
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:
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
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 fromapps/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.
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.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.jsonis synthesized per request:gatewayUrlis the gateway’s own origin, so the client connects back to where it was loaded from, andassistantNameis the configured assistant name (ui.assistant.name, else the default agent’s identity, elseAssistant).basePathdefaults 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.rootis optional. Unset, the gateway serves the packageddist/web-clientbundle and logs which directory it picked. Set, it always wins - including when it is broken, which answers503with that reason rather than silently falling back. When neither resolves, the route answers503namingpnpm web:build:packagedand 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- sendsPermissions-Policygrantinggeolocation=(self)andCross-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 withgeolocation=(), so agent-authored same-origin pages - the canvas host, A2UI and plugin UIs - cannot reach the permission the user granted to the web client. TheCross-Origin-Opener-Policyisolates 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(showsgeolocation=(self)) versus the same request to the canvas host (showsgeolocation=()).
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.allowedOriginsis mandatory. The gateway refuses anopenclaw-user-clientwebsocket from any origin not listed there, under everygateway.auth.modeand even behind a reverse proxy.gateway.controlUi.allowedOriginsnever admits this client. List exact origins (scheme://host[:port]), for examplehttps://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, orhttp://localhost/http://127.0.0.1for development. A plainhttp://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 pointgatewayUrlatwss://. - 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.geolocationandnavigator.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-Policywithgeolocation=(self)(above).wednesdayai web serveand a CDN you host yourself send noPermissions-Policyat 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
Originheader on connect; a mismatch closes the socket with code1008. Pair the client withwednesdayai 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 code1012 (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-okpolicy.tickIntervalMs, default 30 s) with close code4000(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 ahealthrequest 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’sretryAfterMs(rate limiting backs off to 15 s). Any otherconnectrefusal - 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, andtalk.catalogis retried - Dictate keeps its last known availability instead of latching unavailable after one failed read.agents.listandmodels.listare 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
/newresets: 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 advertiseschat.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 andsessions.runs.listreports 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 alocalStorageoutbox 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.
Chat terminal events and transcript durability
Thechat 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:
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:
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.modelsbounds the model menu and whatsessions.patchandsessions.createaccept. Set it before you expose the client: left empty, the menu lists the whole catalog and anyprovider/modelreference that parses is accepted. See Configuration reference. - Assistants. The picker lists the agents the gateway’s
agents.listmethod returns: everyagents.listentry in config plus the default agent, or, with none configured, the default agent plus each agent directory under the gateway state directory.identity.nameandidentity.colorset how each one looks; an assistant with no colour gets a stable one derived from its id. A configuredagents.list[].namewins over the identity name, and anagents.list[].description, if set, appears as a tooltip on the sidebar row and in the assistant picker. An agent withagents.list[].userFacing: falseis 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. SeeuserFacing. - Read aloud.
messages.tts.readAloud.enabled(default on) decides whether users see the Read aloud button; an assistant’s ownagents.list[].tts.readAloud.enabledoverrides 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 themaxTextLengththe 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.patchsettings 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.
Attachment uploads over HTTP
File attachments no longer ride the WebSocket. The browser POSTs each file toPOST /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’shttp:///https://origin, not only itsws:///wss://one. The endpoint sits at the gateway root (/v2/uploads); the web client’sbasePathis irrelevant. - Body size. The per-file cap is 50 MiB (
CLIENT_UPLOAD_MAX_BYTESinsrc/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’sclient_max_body_sizedefaults to 1 MiB): raise it to at least 50 MiB, or large attachments are refused with413before the gateway sees them. - CSP.
wednesdayai web servesends aContent-Security-Policywhoseconnect-srcalready includes the gateway’s http(s) origin alongside itsws:/wss://one (seesrc/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.sendcannot consume it, and a consumeduploadIdcannot 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_EXCEEDEDbefore the body is accepted. - Errors. Every refusal answers
{ "ok": false, "error": { "code": ..., "message": ... } }:403 FORBIDDEN_ORIGIN(the browser’s origin is not ingateway.webClient.allowedOrigins, or the request carries noOriginheader),401 UNAUTHORIZED(a missing, invalid or revoked device token, or a token whose scope set lacksoperator.sessions.write),400 EMPTY_BODY,413 PAYLOAD_TOO_LARGE,429 UPLOAD_QUOTA_EXCEEDED(the device’s staging quota is full), and500 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 answers429(rate_limited) with aRetry-Afterheader until then.
Link this device
Each paired browser mints its own device credential, and the gateway identifies that browser’s turns bydevice:<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:
/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 thechat.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.denylist contains"show_ui"; the usual tool policy precedence applies. - What users see. With the plugin on, a
show_uistep 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 chipYou 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.listanswersenabled: falseand the Canvas toggle reads “Assistant UI is off”. The tool is also absent from runs whose connection did not advertise theui-surfacesclient 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_surfacesschema), keyed by session id and never deleted, so/newand 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), inlinedata: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 noconfig.json or gateway setting for the theme.
- The choice is stored per browser (
localStorage, keyopenclaw.web.theme) and applies immediately, with no reload. The default is Auto. - A browser that stored the retired
blackorwhitemode is migrated on first load:blackbecomesdark,whitebecomeslight, 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-motionis 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-Policystill 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 preferences
Navigation and transcript display settings are client-side, browser-local state. They are not stored in gateway configuration orconfig.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 underopenclaw.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
readModeon the nexttts.speakand Voice session create; when the user has not picked one, nothing is sent and the gateway’smessages.tts.naturalizesetting 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
speedon 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 astalk.session.updateand applies from the session’s next synthesised clause (clauses already synthesised keep their settings); with no live voice session the values ride the nexttalk.session.createinstead. - 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.
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.
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:- 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.
- Internal sessions: Heartbeats, cron runs, subagents, and other background sessions are hidden
by default. Enable Show internal (
includeInternal: true) in the sessions menu. - 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 apasted-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 whatwednesdayai 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-Policywithframe-ancestors 'none',script-src 'self',font-src 'self'(the bundled fonts load from the same origin), andconnect-srclisting'self'plus the gateway origin with itsws:/wss:scheme and itshttp:/https:one - attachments upload overPOST /v2/uploads(see Attachment uploads over HTTP)X-Frame-Options: DENYX-Content-Type-Options: nosniffReferrer-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-Policygrantinggeolocation=(self)on the client’s responses withCross-Origin-Opener-Policy: same-origin, andgeolocation=()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.
config.json is the most common deployment mistake: a stale copy silently points the
client at the previous gateway.
Related
- Using the web client - what your users see: pairing and chat
- Control UI v2 - the operator console at the gateway root, a separate app with its own route
- Brand tokens - the shared colour and font package (developers)
- Web client components - how the client UI is built (developers)
- Gateway protocol - client identity, scopes and the connect handshake
- Configuration reference - every
gateway.webClientkey - Pairing QR and setup codes - onboarding a browser with
--client openclaw-user-client - Identities - people, linked accounts and the four proofs of control
- Identity OIDC - sign-in with Google, Microsoft Entra or GitHub