OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Web interfaces

Control UI

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

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

gateway.controlUi.enabled hot-applies. Disable it to stop serving dashboard pages and assets while bots and existing Gateway connections keep running. Re-enable it to resume serving; missing assets are prepared in the background. Changing the serving base path or asset root still requires a Gateway restart.

For unmatched HTTP paths, the app-shell fallback respects the request's Accept header. An explicit HTML rejection such as text/html;q=0, */* overrides the broader wildcard, so the request reaches the startup 503 or final 404 response. Headerless and wildcard-only requests retain the browser navigation fallback.

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

While the initial connection or a route loads, shimmer placeholders reserve the chat layout. They respect your theme and reduced-motion preference; Gateway startup progress remains visible when available.

Closed Terminal, Browser, Desktop, and Home/Ask OpenClaw panels initialize when you open them rather than during initial navigation. Panels saved as open still restore after a reload.

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: openclaw gateway.

Auth is supplied during the WebSocket handshake via:

  • the configured shared secret in either connect.params.auth.token or connect.params.auth.password; gateway.auth.mode selects the configured value (gateway.auth.token or gateway.auth.password)
  • Tailscale Serve identity headers when gateway.auth.allowTailscale: true
  • trusted-proxy identity headers when gateway.auth.mode: "trusted-proxy"

Gateway auth runs before device pairing. A direct loopback connection does not bypass token or password auth. The login screen and Settings → Gateway use one Gateway secret field: paste the token or type the password. After a successful connection, the UI keeps the secret in session storage for the current browser tab and Gateway origin only when the Gateway reports token auth. Passwords stay in memory and are never persisted. After pairing, the browser can use its stored per-device token on later connections.

If you paste a setup code from Devices → Pair device → Copy setup code into Gateway secret, the UI shows an inline hint before you connect. Paste that code into Settings → Gateway in the OpenClaw mobile app. For the Control UI, run openclaw gateway auth-token --show in an interactive terminal on the Gateway host and paste the shared token instead. If a connection with a setup code is rejected for a token or password mismatch, the login screen repeats this guidance.

Local onboarding generates a Gateway secret in token mode by default, without a token/password picker, and preserves existing password mode. Use --gateway-auth password or --gateway-password <value> for explicit password setup; Tailscale Funnel requires password mode. If the Gateway starts in token mode without a configured token, it generates an ephemeral runtime token for that process instead. The runtime token is not written to config, so it cannot be recovered and a loopback browser without that token is rejected. Run openclaw doctor --generate-gateway-token, restart the Gateway, then run openclaw gateway auth-token --show in an interactive terminal and paste the output into Gateway secret.

What each page covers

  • Connect and pair — pair a browser or phone, reach the UI over Tailscale, and fix a blank page.
  • Sessions and sidebar — sidebar zones, session menus, and the New session page.
  • Chat — composer controls, the session rail, transcript rendering, and hosted embeds.
  • Panels and docks — Ask OpenClaw, the Home dock, the operator terminal, and the browser panel.
  • Settings — identity, appearance, plugins, updates, MCP, activity, and meetings.
  • Feature and RPC reference — every capability with the Gateway RPC behind it.
  • Offline and reconnect — what survives a dropped connection.
  • Security model — content security policy, media route auth, and approval links.
  • Build and develop — build the UI and run the dev server against a Gateway.

Running the Gateway in Docker? See Using the Control UI browser for the browser-equipped image and setup requirements.

Where each section moved

Every section heading from the previous single-page version keeps its anchor here, so an existing link such as /web/control-ui#chat-behavior still resolves. Each entry points at the page that now holds the content.

Was this useful?
On this page

On this page