Control UI - OpenClaw OpenClawDocs Search...K 🇺🇸English🇺🇸 English🇨🇳 简体中文🇨🇳 繁體中文🇯🇵 日本語🇪🇸 Español🇧🇷 Português (BR)🇰🇷 한국어🇩🇪 Deutsch🇫🇷 Français🇮🇳 हिन्दी🇸🇦 العربية🇮🇹 Italiano🇻🇳 Tiếng Việt🇳🇱 Nederlands🇹🇷 Türkçe🇺🇦 Українська🇮🇩 Bahasa Indonesia🇵🇱 Polski🇷🇺 Русский🇮🇷 فارسی🇹🇭 ไทย🇺🇸English✓🇨🇳简体中文✓🇨🇳繁體中文✓🇯🇵日本語✓🇪🇸Español✓🇧🇷Português (BR)✓🇰🇷한국어✓🇩🇪Deutsch✓🇫🇷Français✓🇮🇳हिन्दी✓🇸🇦العربية✓🇮🇹Italiano✓🇻🇳Tiếng Việt✓🇳🇱Nederlands✓🇹🇷Türkçe✓🇺🇦Українська✓🇮🇩Bahasa Indonesia✓🇵🇱Polski✓🇷🇺Русский✓🇮🇷فارسی✓🇹🇭ไทย✓ Get startedInstallChannelsAgentsCapabilitiesClawHubModelsPlatformsGateway & OpsReferenceRelease & CIHelp Browse docs SectionGateway & OpsGet startedInstallChannelsAgentsCapabilitiesClawHubModelsPlatformsGateway & OpsReferenceRelease & CIHelp In this section Gateway Gateway runbookConfiguration ConfigurationConfiguration referenceConfiguration — agentsConfiguration — channelsConfiguration — tools and custom providersConfiguration examples Authentication and secrets AuthenticationAuth credential semanticsSecrets management1PasswordSecrets apply plan contractTrusted proxy auth Health and diagnostics Health checksHeartbeatDoctorAudit historyUsage telemetry and update checksLoggingOpenTelemetry exportPrometheus metricsGateway loggingDiagnostics exportTroubleshooting Scaling and operations Gateway lockBackground exec and process toolRestart recoveryCloud SessionsCloud WorkersMultiple gatewaysMulti-tenant hosting Security and sandboxing SecurityGateway exposure runbookSecure file operationsDependency lockingSecurity audit checksRate limitingOperator scopesSandboxingOpenShellSandbox vs tool policy vs elevatedSession permission modes Protocols and APIs Gateway protocolBuilding a Gateway clientEmbedding OpenClawOpenAI chat completionsOpenResponses APITools invoke APICLI backendsLocal modelsLocal model services Networking and discovery NetworkNode pairingDiscovery and transportsPortalsBonjour discovery Remote access Remote accessGive your Gateway a stable HTTPS URLTailscaleCloudflare Tunnel and Access Security Network proxyFormal verification (security models)Threat model (MITRE ATLAS)Contributing to the threat model Nodes and media NodesActive computer presenceNode troubleshootingMedia capabilities Media understandingMedia playbackImage and media supportAudio and voice notesCamera captureText-to-speech Node features Computer useTalk modeVoice wakeLocation command Web interfaces WebControl UINotificationsControl UI URLsDashboardSession DashboardsDashboard ArchitectureWebChatTUIThe Lobster Gateway & Ops/Web interfaces/Control UICopy pageCopy pageCopy page as Markdown for LLMsView as MarkdownView this page as plain text↗Open in ChatGPTAsk questions about this page↗Open in ClaudeAsk questions about this page↗ Web interfaces Control UI Gateway & OpsWeb interfaces 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) It speaks directly to the Gateway WebSocket on the same port. While you watch a running session, the Gateway shows the model's latest safe preamble immediately as the session headline. When a utility model is available, it can replace that headline with a richer compact status digest after enough activity accumulates. Chat carries the result in a session rail: its compact pill shows the live digest, while the expanded rail shows the assessment, plan progress, pull requests, elapsed time, and a read-only Side chat thread. The rail can expand once when a run becomes stuck or needs input, and done or failed runs keep a frozen “finished” time based on the final digest. On wide chat panes the expanded rail docks as a 400 px right column; on narrower and mobile layouts it remains an overlay. Side chat answers questions about the selected session and its project without entering or interrupting the main agent run. On the first question, the Gateway lazily loads a bounded visible snapshot of the selected session before starting the utility model. If history is temporarily unavailable, the question stays visible with Retry instead of being treated as an empty session. Side chat uses read-only access to the target session's history/search and agent workspace. Its bounded thread is held in Gateway memory, is restored when you switch sessions in the Control UI, and is cleared by the rail's trash button, a session reset, Gateway restart, or idle expiry. It never enters chat.history, and private reference context is not stored as operator dialogue. Type /btw <question> or /side <question> in the main Control UI composer to open the rail and ask there; other clients keep their existing BTW behavior. Highlighting text in a chat message offers Ask in side chat, which opens the rail with a quoted draft ready to edit. The headline owns that run's sidebar subtitle instead of heuristic live activity. It is shared with the official iOS and Android session lists. A final done or failed digest remains visible while the session is unread, then the row returns to its normal work subtitle. Session observation is enabled by default. Safe preamble headlines do not require a utility model; the utility model only owns richer assessments and terminal summaries. In Settings > Appearance > Sidebar, you can turn observation off gateway-wide, inspect the resolved small model and its provenance, or choose automatic routing, disable utility tasks, or select an explicit agents.defaults.utilityModel. The equivalent config controls are gateway.controlUi.sessionObserver: false and agents.defaults.utilityModel: "". Environment identity When you run several Gateways, set gateway.controlUi.environment to distinguish their browser tabs and windows: json5Copy code { gateway: { controlUi: { environment: { label: "edge", color: "amber" }, }, },} The environment adds a 2 px top stripe, an agent-avatar ring, label pills in the sidebar and narrow topbar, a browser-title suffix, and a matching favicon. The label is trimmed and must contain 1–24 characters. Available colors are teal, amber, purple, coral, pink, blue, green, red, and gray. The label and color are intentionally visible before sign-in; leave environment unset to keep the standard appearance unchanged. 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. Note On native Windows LAN binds, Windows Firewall or organization-managed Group Policy can still block the advertised LAN URL even when 127.0.0.1 works on the Gateway host. Run openclaw gateway status --deep on the Windows host; it reports likely-blocked ports, profile mismatches, and local firewall rules that policy may ignore. Auth is supplied during the WebSocket handshake via: connect.params.auth.token connect.params.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 dashboard settings panel keeps a token for the current browser tab session and selected gateway URL; passwords are not persisted. After pairing, the browser can use its stored per-device token on later connections. Onboarding usually configures a gateway token for shared-secret auth. 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 Control UI settings. Password auth works instead when gateway.auth.mode is "password". Device pairing (first connection) After gateway auth succeeds, connecting from a new browser or device usually requires a one-time pairing approval, shown as disconnected (1008): pairing required. On the Gateway host, openclaw dashboard is the preferred owner path: it opens a short-lived, single-use pairing link and leaves that exact signed browser with a durable administrator credential. Opening a fresh link in the same browser also repairs a previously limited credential; another browser profile cannot inherit or replay the grant. List pending requests bashCopy code openclaw devices list Approve by request ID bashCopy code openclaw devices approve <requestId> If the browser retries pairing with changed auth details (role/scopes/public key), the previous pending request is superseded and a new requestId is created; re-run openclaw devices list before approving. Switching an already-paired browser from read access to write/admin access through ordinary stored or shared credentials 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. The narrow exception is a fresh owner handoff issued on the Gateway host by openclaw dashboard or graphical onboarding; it can upgrade only the same signed browser that redeems that one-time handoff. When the connected Control UI reports limited access, open Inbox > System > Limited access, then click Request admin. On mobile, open the sidebar to reach Inbox. The browser files the pending device scope-upgrade request over its existing connection; approve it with openclaw devices on the Gateway host or from Devices in another admin-capable browser that also has operator.pairing. Keep the requesting tab connected while approval completes so it can receive and store the freshly rotated device token before reconnecting. Retry reattaches to the pending request. Cancel stops the local wait but does not reject the device request; if you cancel or disconnect before approval, use the normal pairing repair path on the next connection. Once approved, the device is remembered and won't require re-approval unless you revoke it with openclaw devices revoke --device <id> --role <role>. See Devices CLI for token rotation, revocation, and the Paperclip / openclaw_gateway first-run approval flow. If the Gateway denies the upgrade because it exceeds your assigned operator role, the access details show the administrator-change guidance without Retry. An administrator must change the role before the request can succeed; device approval cannot override that ceiling. Retry remains available for pending, rejected, or expired approval requests and retryable failures. Cancel clears the local request state so you can make a new request after the underlying problem is resolved. Note Direct local Control UI connections from a loopback TCP peer (127.0.0.1 or ::1, typically reached as localhost) with no forwarded/proxy headers can auto-approve device pairing only after gateway auth succeeds and the browser presents device identity. In token/password mode, the first connection still needs the configured shared secret; this auto-approval is not a token bypass. Direct loopback needs no shared secret only when gateway.auth.mode: "none" is explicitly configured. That disables gateway auth and is not the recommended Control UI setup. Tailscale Serve and trusted-proxy modes can avoid a pasted shared secret only when their respective identity checks succeed. Tailscale Serve can skip the pairing round trip for Control UI operator s…