Control UI v2
Control UI v2 is the WednesdayAI operator console and the default console: the gateway serves it at the root (/). It covers the full operator surface, grouped in the sidebar as Monitor,
Configure, Fleet and Learning (see What the pages show), plus
a command palette (⌘K or Ctrl+K) and light and dark themes. When an allowlisted plugin
contributes console UI, a Plugins group appears with its pages (see
Plugin pages and panels).
Like the web client, the console is a static bundle. It contains no gateway
address and no credentials: everything environment-specific arrives at runtime from a small
config.json served next to index.html. One build serves every deployment.
Choose a deployment
A published install ships the built console at
<install>/dist/control-ui-v2; the gateway route
and web serve-control use it by default. From a source checkout, build it first:
Gateway route
The gateway serves the console itself, on by default: the v2 console owns the gateway root (/). To pin it to a sub-path instead, set basePath.
http://127.0.0.1:18789/ (or your gateway’s own address); with an
explicit basePath, open that path instead.
config.jsonis generated per request: the console connects back to the origin it was loaded from, and links to the web client this gateway serves.basePathmust be a single-slash path: it must start with/, and a//prefix, backslashes, whitespace or control characters,.or..segments, and query or fragment characters are all rejected when the config loads. It also may not equal, contain, or be contained by another active console mount (gateway.webClient.basePath); a collision is rejected when the config loads, naming both keys.- With no
root, a missing packaged bundle answers503namingpnpm control:build:packaged, and the gateway logs a warning at startup. A broken explicitrootanswers503with that reason. - The classic console is removed:
gateway.controlUino longer carriesenabled,basePathorroot. A config that still sets them is rewritten when it loads (the keys are dropped, and the gateway persists the rewrite;openclaw doctor --fixapplies it too). Behaviour change from the classic-console release: a config that pinned the old classic console to the root (its removedbasePathset to"/") now gets the v2 console at the root instead of v2 standing down to/v2/control. - Otherwise v2 takes the root unless an enabled
gateway.webClientexplicitly claims/, in which case v2 mounts at/v2/control. gateway.controlUiV2.enabled: falseturns the v2 console off; the gateway then serves no operator console (gateway.controlUiremains only the admission policy).- Bookmarks to
/v2/control/...are not redirected: with v2 at the root, the request falls through to the root console, which opens Overview. Update saved links.
Standalone server
Links must be absolute
http(s) URLs or paths starting with a single /. Anything unusable - a
missing gateway URL, a bad link, a bundle with no index.html, a port that is not an integer from
0 to 65535 - exits non-zero before the socket binds, naming the flag and its environment variable.
GET /healthz answers
200 {"status":"ok","service":"openclaw-control-ui-v2"}.
Container
Build from the repository root;apps/control/Dockerfile.dockerignore limits the context.
8788, and a HEALTHCHECK against /healthz. The gateway URL is not baked
in; supply it (and any other variable from the table above) at run time.
Sign in
Paste the gateway token (or switch to Password) and select Connect. The browser creates a device identity and the gateway mints a device token for it; later visits reconnect with that device token and never show the sign-in screen. Select Sign out to forget the device token. The token or password is held in memory only for the connection attempt - it is never written to browser storage. Only the device identity, the device token and the theme are stored, under theopenclaw.control-v2. prefix.
wednesdayai dashboard opens the console with the gateway token in the URL fragment
(…/#token=<token>; the macOS app passes ?token=). The console takes the token from either spot,
signs in with it only when it has no connected device token, and immediately strips token and
password from the address bar - the credential is never written to browser storage, and a
password in a URL is never used. A stored device token wins: the console reconnects with it and
discards the URL token.
Origins
The console connects as theopenclaw-control-ui client, whose admission and auth policy is
gateway.controlUi. Opened from a loopback address (127.0.0.1,
localhost) it needs no configuration. Any other origin - including the gateway’s own address
when the console is opened by host name - must be listed in gateway.controlUi.allowedOrigins:
https://control.example.com) is not
allowed. Add it to gateway.controlUi.allowedOrigins on the gateway.”
The gateway also enforces the allowlist at startup. On a non-loopback bind with the console
enabled, a config that leaves gateway.controlUi.allowedOrigins empty is refused.
Onboarding and gateway startup seed http://localhost:<port> and http://127.0.0.1:<port> (plus
the custom bind host for bind: "custom") when nothing is configured, so a startup refusal usually
means the list was emptied or the bind changed outside onboarding. Setting
gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback: true skips the requirement at the
documented security cost.
HTTPS
Device identity uses WebCrypto, which browsers allow only in a secure context: HTTPS, orhttp://localhost / http://127.0.0.1. On a plain http:// LAN address the console shows “Open the
console over HTTPS or on localhost; browser device identity needs a secure context.” and does not
connect. Serve it over HTTPS and point the gateway URL at wss://.
Device approval
If the gateway requires approval for a new device, sign-in says so. Approve it on the gateway host, then select Connect again:- Local connections (
127.0.0.1) are auto-approved. - Remote connections (LAN, Tailnet, etc.) require explicit approval.
- Each browser profile generates a unique device ID, so switching browsers or clearing browser data requires re-pairing.
- Turns sent from the console are identified by that device as
device:<deviceId>. Assistants with workspace lanes keep a private workspace per person, so the device must be linked to a person withwednesdayai devices link <deviceId> --identity <key>; an unlinked device gets a denial message naming thedevice:<deviceId>value. The console’s Nodes & devices page can also link or unlink a paired device. See Identities. - Revoke a device with
wednesdayai devices revoke --device <id> --role <role>; see Devices CLI for token rotation and revocation.
Insecure HTTP
The console signs in only from a secure context (see HTTPS). On plainhttp:// to a LAN
or Tailnet IP it shows the secure-context message and never offers the credential form, whatever
the gateway config says. To reach a remote gateway, use HTTPS (Tailscale Serve
or a TLS reverse proxy), or tunnel to loopback so the browser sees http://localhost:
http://localhost:18789/.
Two gateway-side flags relax admission for clients that connect as openclaw-control-ui. Neither
makes the console usable over plain HTTP:
gateway.controlUi.allowInsecureAuth: trueaccepts token or password auth from a non-secure origin. It does not bypass device identity or pairing checks.gateway.controlUi.dangerouslyDisableDeviceAuth: true(break-glass only) disables device identity checks and is a severe security downgrade; revert quickly after emergency use. Connections under this flag are treated as device-less (any presented device block is ignored), so assistants with workspace lanes deny them.
Tailscale access
Keep the gateway on loopback and let Tailscale Serve proxy it with HTTPS:https://<magicdns>/(or your configuredgateway.controlUiV2.basePath)
tailscale-user-login) when gateway.auth.allowTailscale is true. The gateway
verifies the identity by resolving the x-forwarded-for address with tailscale whois and
matching it to the header, and only accepts these when the request hits loopback with Tailscale’s
x-forwarded-* headers. Set gateway.auth.allowTailscale: false (or force
gateway.auth.mode: "password") if you want to require a token/password even for Serve traffic.
Tokenless Serve auth assumes the gateway host is trusted. If untrusted local code may run on that
host, require token/password auth.
For other remote setups, see Tailscale and
Remote access.
config.json
All fields are public; never put a token here. Unknown keys are rejected: the console shows a configuration error instead of connecting anywhere.What the pages show
The sidebar groups the screens into five sections: Monitor, Configure, Fleet, Learning and Plugins. Screens whose gateway RPC is missing - Storage, Recovery, Learning and Dreams - stay out of the sidebar and the command palette, and a direct URL shows “This feature is not enabled on this gateway” instead.Monitor
- Overview: gateway connection and version, channel accounts connected, active runs, spend for today, 7 days or 30 days, upcoming automations, nodes, pending approvals and restart-recovery items that need a decision. The stat captions link to Channels, Sessions, the running runs, Usage and Recovery.
- Sessions: every session with its channel, model, context use (flagged at 80%) and last
activity. The list refreshes itself when a session is created, changed or finishes a run; once
you have loaded more than 200 rows it stops refreshing itself so it keeps your place (use
Refresh). Filter by agent with
?agent=<id>(the Agents page links here). Select a session to open the Session inspector next to the list, with three tabs:- Overview: channel, model, tokens, last activity, links to the owning agent and the parent session, a View runs link, and plugin panels contributed by allowlisted plugins.
- Transcript: the session’s messages, newest last, with collapsed thinking, tool calls and
tool results. Load older pages back. On a gateway that supports it, Load older carries on
into the chat’s earlier sessions (before a
/new,/resetor an idle or daily reset), and a New session divider marks where each one starts. A link to one message or one run highlights it; the console looks back at most 1,000 messages. Each message from a run links to that run. - Usage: spend, tokens, messages, tool calls, errors and p95 latency for the session, with per-model and per-tool tables. Messages without a price are counted, because spend is then a lower bound.
- Runs: agent turns and task runs, filtered by Queued, Running, Needs attention, Failed or
Done. Select a run for its details and timeline, abort a running turn, decide an interrupted
run, or answer an approval that belongs to it. The run inspector links to the agent, the session
and the run’s messages in the transcript. Filtered to one session or agent (
?session=,?agent=), the list shows that scope’s 100 most recent runs. Queued and task runs, and finished runs in the session or agent filter, need SQLite or Postgres session storage (session.storage.backend); without it the filter lists only runs still in progress. When the last gateway restart left items that need a decision, a notice above the table links to Recovery.- Context: for an agent turn that finished, the inspector shows the model that answered and any fallbacks tried before it, token counts, the stop reason and the error kind. It breaks the prompt down into system prompt, workspace files, skills, tools, each plugin’s injected context and messages, with each part’s share of the total. It also lists the injected workspace files (flagged Truncated or Missing) and the tool and skill names. File names are basenames, and a tool or skill name that is not identifier-shaped is shown as a hash, because names may come from skill frontmatter or bootstrap hooks.
- The gateway stores sizes, counts and names only, never prompt text, file contents or file paths. The context needs SQLite or Postgres session storage. Runs recorded before this feature, ACP and subagent runs, and heartbeat, nudge and announce turns show “No context was recorded for this run.”.
- Recovery: work the last gateway restart left behind, filtered by Needs action (blocked
items) or All this boot. Each row names the work (for example “Chat run · agent main”), its
agent, what triggered it and why it is blocked. Select an item for its session, run, cron job
and a short preview, links to the session, its runs, the automation and the agent, and the
item’s action history with who acted. The inspector offers only the actions the gateway will
accept for that item: Continue, Reattach, Mark complete, Discard (marks the work
abandoned; nothing is re-run or re-sent, and it does not come back after a restart) and, for
cron jobs and nudges, Run again (Discard, then start the same work again). Every action asks
for confirmation first. Discard all N like this discards every blocked item that shares the
selected item’s reason. Needs the
doctor.recovery.inspectmethod; plan and apply need admin scope. - Usage: spend and tokens for the range, a daily token chart, the ten sessions that spent the most (USD; a row opens the session’s Usage tab), and spend by agent, model and channel with the most-used tools. Rankings cover only the 1,000 most recent sessions in the range, so an older session with higher spend can be missing. Refreshes every 60 seconds.
- Logs: the gateway file log, following new lines every 2 seconds while the tab is visible, with a minimum-level filter, a text filter and Pause.
- Debug: JSON snapshots of gateway status, health, the last heartbeat and available models, the security-audit summary with the read-only event log, and a manual RPC box (calls run with this console’s operator scopes).
Configure
- Agents: per-agent identity header, config editing, workspace files, the tool catalog with
profile and per-tool overrides, per-agent skills, channel and cron panels, and a nudge dialog.
The identity header shows the agent’s avatar image when the identity carries one: the gateway
pre-resolves workspace-relative avatar paths and serves them unauthenticated at
/__openclaw__/avatar/<agentId>(GET/HEAD only, at most 2 MiB), andagent.identity.getreturns that resolved URL. The header links to the agent’s sessions and runs, and the open tab is kept in the URL (?tab=). Agents configured in anagents.teamsentry are grouped under their team’s name with a lead badge on the lead and an internal badge onuserFacing: falseagents; the selected agent shows its team and role and links to its teammates, and its detail subtitle shows itsdescription. - Automations: cron jobs - schedule, payload (system event, agent turn or wake-gate check), delivery and failure alerting; create, edit, clone, run now, enable or disable; run history with a link to each run’s session. The job inspector shows Created by: … for the connection that created the job (no line on older jobs).
- Channels: one card per gateway channel with probe, per-account rows and logout; WhatsApp QR
login, the Telegram fleet panel, the Nostr profile editor and the Microsoft 365 inbox sign-in
panel (starts the device-code sign-in; shown when the gateway offers
inbox.ms365.signin.status); per-channel config through the schema form. - Skills: workspace, built-in and installed skills with eligibility at a glance; enable or disable a skill, set its API key, or install one.
- Settings: the gateway config as a schema-driven form or a raw JSON5 editor, with a base-hash guard against concurrent edits, save or save-and-restart (a drain confirmation when runs are active), and a package or git update.
Fleet
- Nodes & devices: fleet nodes and pending node or device pairing approvals, device tokens
(rotate, revoke, remove), linking a paired device to an identity (person) or unlinking it, and
exec-approval allowlists for the gateway or a node. Create identities with
wednesdayai identity add <name>. - Instances: live presence of the running WednesdayAI instances.
- Storage (needs
sessions.storage.status): session storage status, legacy JSONL import progress, storage validation, backups on SQLite, and retrying failed imports.
Learning
- Learning (needs
learning.overview): lesson proposals with inspect, approve, reject or quarantine (single or bulk), and the lesson index with search. Click a lesson to open its detail: the judge’s rationale, the model and prompt version that wrote it, the quoted messages with their sender and a link that opens the session’s transcript at the quoted message, the revision history, and the skill proposals built from it. Active lessons can be edited, endorsed or retired (approvals scope). - Dreams (needs
dream.status): dream state, weights and lesson candidates, health, and dream and learning run budgets.
/v2/client/ by default; the sidebar’s Client link opens the
one this gateway serves). Talk existed only in the removed classic console and was deleted with
it; the web client’s Dictate and Voice mode buttons are a separate feature (see
Using the web client).
Approvals requested before the console connected are not listed; the bell counts the ones that
arrived since.
Plugin pages and panels
Trusted plugins can extend the console with their own browser code (ADR 0113). The operator opts in per plugin withgateway.controlUiV2.pluginUi.allow (default none); an allowlisted plugin
whose manifest declares controlUi.entry can then add:
- Pages in a Plugins sidebar group and the command palette. Each page is its own route
(
?plugin=<id>&page=<pageId>), titled with the page label the plugin registered. - Session panels in the Session inspector, receiving the inspected session key.
- Run panels at the end of the Run inspector, receiving the session and run ids.
wednesdayai/plugin-sdk/control-ui; see
Control UI plugins. After updating a plugin, reload the tab: loaded plugin
modules stay cached for the life of the page.
Troubleshooting
“Configuration error” screen before sign-in. Theconfig.json served next to the bundle is
missing or invalid; nothing connected. The detail line names the problem and shows the expected
shape. Fix the file (see config.json): unknown keys, a schemaVersion other than
1, a gatewayUrl that is not an absolute ws:///wss:// URL, a clientId other than
openclaw-control-ui, or a bad basePath or links value all produce this screen. Reload after
fixing it.
Sign-in says the origin is not allowed. The browser origin is missing from
gateway.controlUi.allowedOrigins on the gateway. Add the exact origin shown in the message and
restart the gateway; see Origins.
The gateway refuses to start, naming gateway.controlUiV2.basePath (or web serve-control
exits naming --base-path). The base path is not a single-slash path - a missing leading /, a
// prefix, backslashes, whitespace or control characters, . or .. segments, or a query or
fragment - or it collides with another active SPA mount. Choose a distinct single-slash path; the
gateway validates it when the config loads, and the standalone server before it binds.
Sign-in asks for pairing approval. The gateway requires approval for this new browser device.
The console shows “This device needs pairing approval from the gateway host. Approve it there, then
click Connect again.” Approve it on the gateway host and select Connect again; see
Device approval.
Sign-in says “Open the console over HTTPS or on localhost; browser device identity needs a secure
context.” The page is not in a secure context, so the browser blocks device identity. See
HTTPS.
The route answers 503 naming a build command or a bundle directory. The console bundle is
missing or broken: for the gateway route, run pnpm control:build:packaged or set
gateway.controlUiV2.root to a built apps/control/dist; for the standalone server, point --root
at a directory containing index.html.