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.

If the Gateway's request queue is full, the Control UI shows "The server is busy. Please try again in a moment." Wait briefly, then retry the action.

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.

The selected chat loads before automatic sidebar task lists refresh. Live events remain subscribed during startup, and explicit sidebar actions remain available. Background lists resume after the transcript loads or reports an error.

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.

Hidden retained chats defer command and model metadata refreshes until you return to them. Repeated background changes share the current metadata read and refresh once more after it finishes, instead of issuing overlapping requests.

Choose New agent in the sidebar or Agents home to open the custodian chat. It recommends a chief of staff, researcher, writer, reviewer, or a small team with all four. Reply with a choice, or describe custom work and a name. Role choices use the same role templates as the CLI; creation waits for operator approval. Created agents appear in Agents home and the agent switcher. If team creation stops partway through, the custodian reports the retained agents so you can inspect them before creating the missing members.

Watch a desktop in Picture-in-Picture

Connect the Desktop viewer, then choose Open desktop in Picture-in-Picture in its toolbar. The browser opens a view-only, always-on-top window so you can watch the remote computer while using other tabs or apps. The same action is available in the docked panel, chat side panel, and focused desktop window.

This requires a secure context (HTTPS or localhost) and a desktop browser that exposes the Document Picture-in-Picture API, including supported Chrome and Firefox versions. The control is disabled when the API is unavailable or the desktop is not connected. Browser permissions can still deny the request; check those permissions and click the control again to retry. OpenClaw does not replace unsupported PiP with an ordinary popup.

PiP mirrors the existing live connection without taking control or opening a second desktop connection. Closing PiP leaves the original viewer and remote task running. Disconnecting, changing the viewer's source or session, or closing the originating viewer closes PiP; it does not stop the remote task. Keep the opener tab open. A sleeping computer or a browser that suspends the entire page cannot continue streaming.

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.

Agents home

Open Agents in the sidebar, choose All agents in the agent switcher, or visit /agents to see your configured agents as a roster. Each card shows the agent's identity, model, current work status, last activity, and a preview from its main chat. Open chat opens that agent's main session. Working agents appear first, followed by the most recently active.

Manage agents opens /settings/agents. New agent opens the existing agent creation flow when available, or agent settings otherwise. /agents now opens the roster; agent configuration remains at /settings/agents.

To browse sessions across agents, choose Show all agents in the agent switcher. This enables team mode, a browser preference that is off by default. The top row becomes a workspace header with the configured Gateway display name, or OpenClaw, and the OpenClaw mark. Its menu contains Show one agent, Agent settings, and the existing documentation, help, community, and changelog links. Sessions appear under collapsible agent headers in configured roster order, which stays stable as activity changes. Home disappears from Pages: click an agent header's avatar or name to open that agent's main chat. The separate collapse control only folds its sessions. The top +, labeled New conversation, opens an agent menu with avatars and names in the same order as the groups; choosing an agent opens New session for that agent. Each group's + does this directly, appearing on hover or keyboard focus and remaining visible on touch devices. Selecting a session switches the active agent for chat. Choose Show one agent in the workspace menu to restore the agent chip, Home row, and direct New session button.

Enabling team mode also defaults the shared page scope to All agents, while remembering the previous scope to restore when you turn it off. That scope, including an explicit All agents selection, is saved in this browser for each gateway. It survives reloads and switching to another gateway and back, even if you open a different agent's chat in team mode. Turning team mode off clears the remembered value after restoring it. You can still choose a narrower scope; navigating between pages does not reset that choice. Automations, Dashboards, Sessions, Tasks, and Usage support all-agent views, with agent identity shown on mixed-agent rows. Memory, Model providers, and Skill Workshop stay scoped to one agent. Open an agent's main chat from its group header to select that agent before visiting those pages; chat actions always belong to the conversation's agent.

Choose All sessions from an agent group’s options menu to open the Sessions page filtered to that agent. Open Agents in the sidebar to return to the roster page. See Sidebar navigation for group controls and filtering.

Agent names and avatars follow agent and identity updates. While a configured avatar image loads, the avatar keeps its tinted background with no face or text. The image appears when ready; an emoji or generated face appears only when no image is configured or the image fails to load. This behavior is shared by the roster, agent switcher, identity chips, settings, and chat.

Activity and previews on the page and sidebar roster refresh on session events and Gateway reconnects. When both are visible, they share one activity window and one refresh, so opening Agents while team mode is visible does not duplicate requests. Activity loading stops when neither roster is visible. Each refresh reads at most 300 sessions across agents, loading pinned sessions first and then the most recent sessions. Pinned sessions count toward that limit; sessions outside the window do not appear in the grouped sidebar or contribute to activity summaries, except that the open conversation remains visible so direct links keep a selected row. When a main session is absent from the window, its agent's most recent session supplies the preview.

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