Use this file to discover all available pages before exploring further.

Control UI

The Control UI is a small Vite + Lit single-page app served by the Gateway:

default:
text
http://<host>:18789/
optional prefix: set
text
gateway.controlUi.basePath
(e.g.
text
/openclaw
)

It speaks directly to the Gateway WebSocket on the same port.

Quick open (local)

If the Gateway is running on the same computer, open:

http://127.0.0.1:18789/ (or http://localhost:18789/)

If the page fails to load, start the Gateway first:

text

openclaw gateway

Auth is supplied during the WebSocket handshake via:

text
connect.params.auth.token
text
connect.params.auth.password
Tailscale Serve identity headers when
text
gateway.auth.allowTailscale: true
trusted-proxy identity headers when
text
gateway.auth.mode: "trusted-proxy"

The dashboard settings panel keeps a token for the current browser tab session and selected gateway URL; passwords are not persisted. Onboarding usually generates a gateway token for shared-secret auth on first connect, but password auth works too when

text

gateway.auth.mode

text

"password"

Device pairing (first connection)

When you connect to the Control UI from a new browser or device, the Gateway usually requires a one-time pairing approval. This is a security measure to prevent unauthorized access.

What you'll see: "disconnected (1008): pairing required"

List pending requests

```bash} openclaw devices list ```

Approve by request ID

```bash} openclaw devices approve ```

If the browser retries pairing with changed auth details (role/scopes/public key), the previous pending request is superseded and a new

text

requestId

is created. Re-run

text

openclaw devices list

before approval.

If the browser is already paired and you change it from read access to write/admin access, this is treated as an approval upgrade, not a silent reconnect. OpenClaw keeps the old approval active, blocks the broader reconnect, and asks you to approve the new scope set explicitly.

Once approved, the device is remembered and won't require re-approval unless you revoke it with

text

openclaw devices revoke --device <id> --role <role>

. See Devices CLI for token rotation and revocation.

note

* Direct local loopback browser connections (`127.0.0.1` / `localhost`) are auto-approved. * Tailscale Serve can skip the pairing round trip for Control UI operator sessions when `gateway.auth.allowTailscale: true`, Tailscale identity verifies, and the browser presents its device identity. * Direct Tailnet binds, LAN browser connects, and browser profiles without device identity still require explicit approval. * Each browser profile generates a unique device ID, so switching browsers or clearing browser data will require re-pairing.

Personal identity (browser-local)

The Control UI supports a per-browser personal identity (display name and avatar) attached to outgoing messages for attribution in shared sessions. It lives in browser storage, is scoped to the current browser profile, and is not synced to other devices or persisted server-side beyond the normal transcript authorship metadata on messages you actually send. Clearing site data or switching browsers resets it to empty.

The same browser-local pattern applies to the assistant avatar override. Uploaded assistant avatars overlay the gateway-resolved identity on the local browser only and never round-trip through

text

config.patch

. The shared

text

ui.assistant.avatar

config field is still available for non-UI clients writing the field directly (such as scripted gateways or custom dashboards).

Runtime config endpoint

The Control UI fetches its runtime settings from

text

/__openclaw/control-ui-config.json

. That endpoint is gated by the same gateway auth as the rest of the HTTP surface: unauthenticated browsers cannot fetch it, and a successful fetch requires either an already valid gateway token/password, Tailscale Serve identity, or a trusted-proxy identity.

Language support

The Control UI can localize itself on first load based on your browser locale. To override it later, open Overview -> Gateway Access -> Language. The locale picker lives in the Gateway Access card, not under Appearance.

Supported locales:
text
en
,
text
zh-CN
,
text
zh-TW
,
text
pt-BR
,
text
de
,
text
es
,
text
ja-JP
,
text
ko
,
text
fr
,
text
ar
,
text
it
,
text
tr
,
text
uk
,
text
id
,
text
pl
,
text
th
,
text
vi
,
text
nl
,
text
fa
Non-English translations are lazy-loaded in the browser.
The selected locale is saved in browser storage and reused on future visits.
Missing translation keys fall back to English.

Docs translations are generated for the same non-English locale set, but the docs site's built-in Mintlify language picker is limited to the locale codes Mintlify accepts. Thai (

text

th

) and Persian (

text

fa

) docs are still generated in the publish repo; they may not appear in that picker until Mintlify supports those codes.

Appearance themes

The Appearance panel keeps the built-in Claw, Knot, and Dash themes, plus one browser-local tweakcn import slot. To import a theme, open tweakcn themes, choose or create a theme, click Share, and paste the copied theme link into Appearance. The importer also accepts

text

https://tweakcn.com/r/themes/<id>

registry URLs, editor URLs like

text

https://tweakcn.com/editor/theme?theme=amethyst-haze

, relative

text

/themes/<id>

paths, raw theme IDs, and default theme names such as

text

amethyst-haze

Imported themes are stored only in the current browser profile. They are not written to gateway config and do not sync across devices. Replacing the imported theme updates the one local slot; clearing it switches the active theme back to Claw if the imported theme was selected.

What it can do (today)

Chat behavior

PWA install and web push

The Control UI ships a

text

manifest.webmanifest

and a service worker, so modern browsers can install it as a standalone PWA. Web Push lets the Gateway wake the installed PWA with notifications even when the tab or browser window is not open.

Surface	What it does
text `ui/public/manifest.webmanifest`	PWA manifest. Browsers offer "Install app" once it is reachable.
text `ui/public/sw.js`	Service worker that handles text `push` events and notification clicks.
text `push/vapid-keys.json` (under the OpenClaw state dir)	Auto-generated VAPID keypair used to sign Web Push payloads.
text `push/web-push-subscriptions.json`	Persisted browser subscription endpoints.

Override the VAPID keypair through env vars on the Gateway process when you want to pin keys (for multi-host deployments, secrets rotation, or tests):

text
OPENCLAW_VAPID_PUBLIC_KEY
text
OPENCLAW_VAPID_PRIVATE_KEY
text
OPENCLAW_VAPID_SUBJECT
(defaults to
text
mailto:openclaw@localhost
)

The Control UI uses these scope-gated Gateway methods to register and test browser subscriptions:

text
push.web.vapidPublicKey
— fetches the active VAPID public key.
text
push.web.subscribe
— registers an
text
endpoint
plus
text
keys.p256dh
/
text
keys.auth
.
text
push.web.unsubscribe
— removes a registered endpoint.
text
push.web.test
— sends a test notification to the caller's subscription.

note

Web Push is independent of the iOS APNS relay path (see [Configuration](/gateway/configuration) for relay-backed push) and the existing `push.test` method, which target native mobile pairing.

Hosted embeds

Assistant messages can render hosted web content inline with the

text

[embed ...]

shortcode. The iframe sandbox policy is controlled by

text

gateway.controlUi.embedSandbox

Disables script execution inside hosted embeds. Allows interactive embeds while keeping origin isolation; this is the default and is usually enough for self-contained browser games/widgets. Adds `allow-same-origin` on top of `allow-scripts` for same-site documents that intentionally need stronger privileges.

Example:


json5
{
  gateway: {
    controlUi: {
      embedSandbox: "scripts",
    },
  },
}

warning

Use `trusted` only when the embedded document genuinely needs same-origin behavior. For most agent-generated games and interactive canvases, `scripts` is the safer choice.

Absolute external

text

http(s)

embed URLs stay blocked by default. If you intentionally want

text

[embed url="https://..."]

to load third-party pages, set

text

gateway.controlUi.allowExternalEmbedUrls: true

Tailnet access (recommended)

Keep the Gateway on loopback and let Tailscale Serve proxy it with HTTPS:


text
```bash}
openclaw gateway --tailscale serve
```

Open:

* `https://<magicdns>/` (or your configured `gateway.controlUi.basePath`)

By default, Control UI/WebSocket Serve requests can authenticate via Tailscale identity headers (`tailscale-user-login`) when `gateway.auth.allowTailscale` is `true`. OpenClaw verifies the identity by resolving the `x-forwarded-for` address with `tailscale whois` and matching it to the header, and only accepts these when the request hits loopback with Tailscale's `x-forwarded-*` headers. For Control UI operator sessions with browser device identity, this verified Serve path also skips the device-pairing round trip; device-less browsers and node-role connections still follow the normal device checks. Set `gateway.auth.allowTailscale: false` if you want to require explicit shared-secret credentials even for Serve traffic. Then use `gateway.auth.mode: "token"` or `"password"`.

For that async Serve identity path, failed auth attempts for the same client IP and auth scope are serialized before rate-limit writes. Concurrent bad retries from the same browser can therefore show `retry later` on the second request instead of two plain mismatches racing in parallel.

<Warning>
  Tokenless Serve auth assumes the gateway host is trusted. If untrusted local code may run on that host, require token/password auth.
</Warning>

```bash} openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)" ```


text
Then open:

* `http://<tailscale-ip>:18789/` (or your configured `gateway.controlUi.basePath`)

Paste the matching shared secret into the UI settings (sent as `connect.params.auth.token` or `connect.params.auth.password`).

Insecure HTTP

If you open the dashboard over plain HTTP (

text

http://<lan-ip>

text

http://<tailscale-ip>

), the browser runs in a non-secure context and blocks WebCrypto. By default, OpenClaw blocks Control UI connections without device identity.

Documented exceptions:

localhost-only insecure HTTP compatibility with
text
gateway.controlUi.allowInsecureAuth=true
successful operator Control UI auth through
text
gateway.auth.mode: "trusted-proxy"
break-glass
text
gateway.controlUi.dangerouslyDisableDeviceAuth=true

Recommended fix: use HTTPS (Tailscale Serve) or open the UI locally:

text
https://<magicdns>/
(Serve)
text
http://127.0.0.1:18789/
(on the gateway host)

See Tailscale for HTTPS setup guidance.

Content security policy

The Control UI ships with a tight

text

img-src

policy: only same-origin assets,

text

data:

URLs, and locally generated

text

blob:

URLs are allowed. Remote

text

http(s)

and protocol-relative image URLs are rejected by the browser and do not issue network fetches.

What this means in practice:

Avatars and images served under relative paths (for example
text
/avatars/<id>
) still render, including authenticated avatar routes that the UI fetches and converts into local
text
blob:
URLs.
Inline
text
data:image/...
URLs still render (useful for in-protocol payloads).
Local
text
blob:
URLs created by the Control UI still render.
Remote avatar URLs emitted by channel metadata are stripped at the Control UI's avatar helpers and replaced with the built-in logo/badge, so a compromised or malicious channel cannot force arbitrary remote image fetches from an operator browser.

You do not need to change anything to get this behavior — it is always on and not configurable.

Avatar route auth

When gateway auth is configured, the Control UI avatar endpoint requires the same gateway token as the rest of the API:

text
GET /avatar/<agentId>
returns the avatar image only to authenticated callers.
text
GET /avatar/<agentId>?meta=1
returns the avatar metadata under the same rule.
Unauthenticated requests to either route are rejected (matching the sibling assistant-media route). This prevents the avatar route from leaking agent identity on hosts that are otherwise protected.
The Control UI itself forwards the gateway token as a bearer header when fetching avatars, and uses authenticated blob URLs so the image still renders in dashboards.

If you disable gateway auth (not recommended on shared hosts), the avatar route also becomes unauthenticated, in line with the rest of the gateway.

Building the UI

The Gateway serves static files from

text

dist/control-ui

. Build them with:


bash
pnpm ui:build

Optional absolute base (when you want fixed asset URLs):


bash
OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build

For local development (separate dev server):


bash
pnpm ui:dev

Then point the UI at your Gateway WS URL (e.g.

text

ws://127.0.0.1:18789

Debugging/testing: dev server + remote Gateway

The Control UI is static files; the WebSocket target is configurable and can be different from the HTTP origin. This is handy when you want the Vite dev server locally but the Gateway runs elsewhere.

Start the UI dev server

```bash} pnpm ui:dev ```

Open with gatewayUrl

```text} http://localhost:5173/?gatewayUrl=ws%3A%2F%2F%3A18789 ```


text
Optional one-time auth (if needed):

```text}
http://localhost:5173/?gatewayUrl=wss%3A%2F%2F<gateway-host>%3A18789#token=<gateway-token>
```

Example:


json5
{
  gateway: {
    controlUi: {
      allowedOrigins: ["http://localhost:5173"],
    },
  },
}

Remote access setup details: Remote access.

Dashboard — gateway dashboard
Health Checks — gateway health monitoring
TUI — terminal user interface
WebChat — browser-based chat interface

OpenClaw Docs

Control UI

Quick open (local)

Device pairing (first connection)

List pending requests

Approve by request ID

note

Personal identity (browser-local)

Runtime config endpoint

Language support

Appearance themes

What it can do (today)

Chat behavior

PWA install and web push

note

Hosted embeds

warning

Tailnet access (recommended)

Insecure HTTP

Content security policy

Avatar route auth

Building the UI

Debugging/testing: dev server + remote Gateway

Start the UI dev server

Open with gatewayUrl

Related