Control UI: the console in your browser

OpenClaw Control UI is the browser console that ships with the Gateway: openclaw dashboard one command to open it, with sessions, approvals, files, settings, and terminal all on one page. The previous lesson described three kinds of daily entry points; this lesson focuses on the most commonly used one.

It is not a cloud website. Control UI is a Vite + Solid single-page app served directly by your own Gateway process, with the default local address http://127.0.0.1:18789/ — if the Gateway stops, the page won't load. That is the price of self-hosting, and also the source of "state, memory, and credentials all living on your own hardware."

Control UI was fully rebuilt in v2026.8.1 ("OpenClaw 2.0"): the conversation sits at the center, with files, approvals, settings, and live work docked beside it (for background see OpenClaw 2.0 what's new). This tutorial is based on v2026.10.9.

What you'll be able to do after this lesson

Open OpenClaw Control UI with openclaw dashboard or http://127.0.0.1:18789/, and explain clearly how it differs from the cloud web version
Complete Gateway secret authentication and one-time device pairing; scan a QR code on your phone, and other computers can connect too
Distinguish the sidebar's Pages / Sessions / Users sections, and use the Ctrl+K command palette to jump around quickly
Send messages in the chat box, switch models, and use the Details panel to see workspace, branch, and usage
Manage sessions and settings: Pin, rename, archive, Snooze, generate public read-only share links; on the settings page, change appearance, manage plugins, configure MCP servers, and import Claude Code / Codex memory

Where you are stuck right now

You've been chatting with Claw in the terminal and want to scroll back through old records or see exactly which files it changed, but the terminal won't scroll
When Claw requests approval it only drops a line in a channel, and if you miss it, it sinks to the bottom — you want one place to view and approve everything
You want to switch models, install plugins, and tweak the interface without touching config files — you're missing a handy graphical console

When to use this approach

When you need:

A full-featured console: sessions, files, approvals, settings, and terminal all in the browser
To view and operate your Claw from a phone or another computer
Daily operations without touching the terminal: starting a new session, switching models, and archiving old conversations are all one click

And you don't want to:

SSH into the machine every time to edit openclaw.json
Scroll through long chat histories in a terminal TUI
Dig through log files just to glance at an approval

🎒 Before you start

finished the daily use overview and knows where this lesson sits in the stage
The Gateway runs: in Install: get running in 5 minutes, openclaw gateway status should show it listening on 18789; if installation fails, go to installation troubleshooting first
A reasonably recent browser: Chrome 147+ / Firefox 150+ / Safari 26.2+ (official stance as of 2026-10)
(Optional) the OpenClaw App installed on your phone, if you want to pair by scanning a QR code

Core idea

What is Control UI? Official definition: a Vite + Solid single-page app (SPA) served by the Gateway:

Default address http://<host>:18789/, which is http://127.0.0.1:18789/ on the local machine
Optional prefix gateway.controlUi.basePath (for example, mounting under the /openclaw subpath)
The page talks directly to the Gateway WebSocket on the same port — no intermediary server

How it relates to the other two everyday entry points:

Entry point	How to open	When it fits
Control UI (this lesson)	`openclaw dashboard` or visit in a browser 18789	Full-featured console: sessions, approvals, files, settings, terminal
TUI	Run `openclaw` in a terminal	No browser needed, for quick chats
Chat channels	Feishu / WeCom / Telegram, etc.	Claw comes to you inside the IM you already use (scenario walkthrough)

Remember one sentence about the security model: Gateway authentication (token or password) runs before device pairing, and local loopback connections do not bypass it; by default the Gateway only listens on localhost (loopback), port 18789. The full rules for remote exposure are in Security Hardening (Part One).

Follow along

Step 1: Open the OpenClaw Control UI — local port 18789

Why: The Control UI is served by the Gateway, so the page won't open if the Gateway isn't running. Confirm it's alive first, then open the browser.

bash

openclaw dashboard

You should see: The browser opens the Control UI automatically. You can also visit http://127.0.0.1:18789/ (or http://localhost:18789/) manually.

Page won't open? The official docs say to start the Gateway first:

bash

openclaw gateway

Then refresh the browser. If it still doesn't work, go through the "Pitfalls" section below item by item.

The browser opened http://127.0.0.1:18789/ and you can see the login page or the workspace

Step 2: Enter the Gateway secret — OpenClaw Control UI authentication

Why: Gateway authentication is the first gate, and even local loopback doesn't bypass it. Local onboarding generates a Gateway secret in token mode by default.

The login page has just one Gateway secret input field: paste a token directly, or type a password by hand (gateway.auth.mode decides which one). You can view the shared token in the interactive terminal on the Gateway host:

bash

openclaw gateway auth-token --show

You should see: The terminal prints the shared token. Paste it into the Gateway secret field to connect to the workspace; the connection indicator in the bottom-left corner shows the current connection status.

💡 Where is the secret stored?

After a successful connection, the UI stores the secret in the current browser tab's session storage only in token mode (and only for the current Gateway origin); passwords stay in memory only and are never written to disk. Once pairing is done, the browser uses its own per-device token for subsequent connections, so you don't need to enter the secret again.

Gateway secret authentication passed; you're in the post-login interface

Step 3: Approve device pairing — the first connection from a new browser

Why: After authentication passes, the first connection from a new browser/device usually still needs a one-time pairing approval — recording "I know this browser" in the credential store.

The easiest approach on the Gateway host is the openclaw dashboard from Step 1: it opens a short-lived, one-time pairing link that lets the current browser obtain a persistent admin credential directly, without manual approval.

When you switch to another browser/device, the page shows disconnected (1008): pairing required and waits; at that point, run this on the Gateway host:

bash

openclaw devices list
openclaw devices approve <requestId>

You should see: The page stays open and connects automatically once approved (Check now retries immediately). Approved devices are remembered and skip pairing afterwards; to revoke one, use openclaw devices revoke --device <id> --role <role>.

💡 Local loopback can be auto-approved

Local connections coming directly from 127.0.0.1 / ::1 with no proxy headers are automatically approved for device pairing once Gateway authentication passes (token / password still has to come first — this is not an authentication bypass). To force manual approval for every device, set gateway.nodes.pairing.autoApproveLocal: false.

⚠️ Every incognito window is a "new browser"

Each browser profile generates an independent device ID; clearing browser data, using an incognito window (or Firefox set to "never remember history") discards the paired device identity, so you'll have to pair again next time. Sticking to a fixed browser profile is the easiest for daily use.

The browser completed pairing and entered the Control UI workspace

Step 4: Get to know the three-area navigation — Pages, Sessions, and Users

Why: In 2.0, the conversation is centered and a navigation rail on the left manages everything globally. Once you can tell the three views apart, every later operation has a home.

View	What's in it	What you'll most often do here
Pages	Built-in pages, dashboards, plugin entry points	Open pages like Automations, Templates, Systems
Sessions	All sessions	Find old conversations, start new sessions
Users	People online	See who's online and what others are doing

The navigation rail has a fixed structure: at the top is the current agent's avatar (click it to open the agent menu), below the avatar is a + (New conversation, starts a new session), and at the bottom are Home, Inbox, and your account menu.

Three things to get a feel for right away:

Ctrl+K (⌘K on Mac): the command palette — jump to pages, switch sessions, search commands
Ctrl+B (⌘B on Mac): collapse / expand the sidebar
Ctrl+Shift+O (⌘⇧O on Mac): the New Session shortcut in the browser, focuses the chat box directly

You should see: Click the Sessions view; sessions are laid out in three sections —

Other: regular conversations; Groups: group chats / rooms; Coding: sessions bound to a worktree or exec node, with repo ⎇ branch in the row
Use the My sessions / Involving me / All owners chips in the header row to switch whose sessions you see
Filter & sort lets you filter by status (Active / Snoozed / Archived / All), group, and sort; Show message preview enables message previews
can open the command palette with Ctrl+K and switch between the three views

Step 5: Talk to Claw — composer, models, and the Details panel

Why: Chat is the heart of the Control UI. Beyond sending messages, this step gets you familiar with the widgets that let you "see what it's doing."

Click + in the navigation rail (or New session in Sessions): the New session page lets you pick an agent, a Workspace (saved projects / recent folders / repository URLs), and a model, then send your first message.

You should see:

The reply streams in; a completed turn collapses the process into a single Worked for 2m 3s line — click it to see tool call details
The chat box (composer) has a model selector — switch models without touching config files (notation recap: provider/model, see Connecting Models Overview)
The composer's context ring shows a usage summary, the most recent turn's tokens, and plan limits; View context opens the full report
The Details panel in the chat header: Environment (workspace name, branch, worktree, execution device, model), Changes (PRs, change stats, checks)
When Claw needs approval or asks a question, an attention icon appears on the corresponding session row in the sidebar — click it to see the specific request

A new session's name is taken automatically from the opening task; afterwards it only changes if you or the agent explicitly rename it.

💡 Start a small session in the background without interrupting the current conversation

Open the command palette with Ctrl+K, drag an image or file into the palette (or just paste an image), and the palette switches to New session mode; add a line of instructions, adjust the session settings, and send with Ctrl+Enter — the current conversation stays untouched, and the file won't be sent on its own.

Send a message and receive a reply; open the Details panel once

Step 6: Manage sessions — Pin, rename, archive, and share

Why: Once conversations pile up, you need to organize them. The session menu (right-click a sidebar row, or the action menu in the chat header) gathers the common actions in one place.

Action	Effect
Pin / Unpin	Pins it to the Pinned section at the top of Sessions
Rename	Click the title in the chat header to edit directly; Enter saves, Escape cancels
Archive / Restore	Tucks it away from the Active list (Ctrl+Shift+A archives the current chat); history stays readable and can be undone
Snooze / Wake	Temporarily hides it: 1 hour / 3 hours / tonight 18:00 / tomorrow morning 9:00 / next Monday 9:00
Move to group	Moves it into a custom group; group names and order are stored in the Gateway and follow you across browsers
Icon & color	Assign an emoji / icon and a color bar to the session row (Advanced menu)

Snooze just means "hide it for now": the session itself keeps running — if you send it a message, the agent finishes a turn, or the wake time arrives, it returns to the Active list on its own; to wake it early, use Wake session in the menu.

Share a session publicly: in the chat header, Session sharing → Enable public access… → confirm Make public → Copy public link. Anyone with the link can view the conversation text, eligible images, and collapsed tool summaries in read-only mode; they cannot send messages and do not get your permissions.

⚠️ Read it yourself before making it public

The text on the public page is not redacted — anything like passwords or keys that appeared in the conversation will be visible as-is. Review the conversation before publishing; turning off public access cannot recall copies others have already saved.

You should see: the pinned session stays in the Pinned section at the top of Sessions; the archived session disappears from the Active list, can be undone via Undo on the confirmation bar, and its history remains readable.

Pin a frequently used session to the top and archive an old one

Step 7: Settings page and side panel — appearance, plugins, MCP, and terminal

Why: Everyday graphical configuration lives in Settings; the tools you work with hang in the side panel to the right of the chat.

Settings (account menu at the bottom of the sidebar → Settings):

Appearance: theme and look, even the browser tab icon can be changed (Default / Agent avatar / Lobsterdex)
Plugins: one-click plugin installation and discovery
Updates: an Available badge appears when a new version is available on the stable / beta channel (the account menu also has an Updates entry)
MCP: add / enable / disable MCP servers (three transports: Streamable HTTP, SSE, stdio) — for a deep dive see MCP Integration
Import Memory: import local memories from Claude Code / Codex / Hermes into an agent — details in Memory System
Labs: enables experimental features, such as Templates (an official template discovery page added to Pages) and Speech bubbles (a bubble-style conversation view)
The Search settings at the top searches by page and configuration field name, so you don't have to click through one by one

Side panels (to the right of the chat, opened via the + menu or the Layout menu in the header):

Terminal: the operator terminal, enabled by default (gateway.terminal.enabled), requires the operator.admin permission, and opens a host PTY in the current agent's workspace; the shortcut Ctrl+` (Ctrl plus backtick) toggles it quickly
Browser: view Claw's browser operation results here
Files: browse workspace files; hovering over a file row shows Download file, PDFs up to 16 MiB can be previewed; in the preview toolbar's ⋯ menu, Attach to session attaches the file to your next message
Subagents: see subagents' running status and read-only transcripts (commands like /subagents list also work in the chat)
Processes: status and output of background exec commands in the session; Stop stops exactly that one process

Ask OpenClaw: Settings → Ask OpenClaw (or the Ask OpenClaw tab in the Home dock) — an agent dedicated to system installation and repair; just say configure gateway or import memory in a chat to start the guided wizard.

⚠️ The operator terminal is a host shell

The Gateway local terminal is not sandboxed and inherits the Gateway process environment — any credentials the Gateway can read, it can read too, and writing files directly also bypasses restrictions like OPENCLAW_CONFIG_READONLY. If you don't want this capability: set gateway.terminal.enabled: false, or disable it entirely at deployment time with the environment variable OPENCLAW_DISABLE_GATEWAY_LOCAL_TERMINALS=1.

You should see: a Search settings search box at the top of Settings — typing a word like Typography jumps straight to the matching setting under Appearance; the side panel tabs can be dragged to reorder and closed individually without affecting each other.

Found the MCP and Import Memory pages in Settings; opened the Terminal panel at least once

Step 8 (optional): Remote and mobile access to the Control UI

Why: Claw runs on a home machine or VPS, and you need to be able to connect even when you're not right there.

Option A (recommended): Expose HTTPS with Tailscale Serve

bash

openclaw gateway --tailscale serve

Visit https://<magicdns>/. With gateway.auth.allowTailscale: true, Tailscale identity authentication can be used, and browsers that already carry device identity can even skip the pairing round trip.

Option B: Pair a phone by scanning a QR code

A paired admin, in the Control UI: Devices → Pair device to generate a QR code → in the phone app, Settings → Gateway scan it (or paste the setup code) → when Pending approval appears, review the role and permissions before approving. Generating a setup code requires operator.admin.

Option C: Install as a PWA

The Control UI ships with a manifest and service worker, so modern browsers can "install" it as a standalone app; once installed, Web Push can deliver notifications even with the tab closed — including pending exec / plugin approvals.

⚠️ Don't expose it to the public internet unprotected

The Gateway listens only on localhost by default; switching to a non-loopback listener requires authentication to be configured, otherwise it refuses to start (fail closed). LAN http://<内网IP> can open it but is a downgraded transport — use HTTPS whenever possible. See Security Hardening (Part One) for the full rules.

You should see: with Option A, https://<magicdns>/ opens the same Control UI as on the local machine; with Option B, after scanning the QR code the phone app connects automatically, and pairing succeeds once Pending approval is approved; with Option C, after installation the Control UI runs as a standalone app window without taking up a browser tab.

(Optional) Completed QR-code pairing on a phone, or Tailscale HTTPS can open the Control UI

Checkpoint ✅

openclaw dashboard can open the Control UI, local address http://127.0.0.1:18789/
Gateway secret authentication passed, and the browser completed one-time device pairing
Can explain what Pages / Sessions / Users each contain, and Ctrl+K opens the command palette
Has sent a message, switched models, and opened the Details panel in the Control UI
Has completed at least one session management action (any of Pin / archive / rename)

Pitfall reminders

❌ The page won't open or is completely blank

Three layers of causes — troubleshoot in order:

The Gateway isn't running: the Control UI is a page served by the Gateway, so if the process is stopped it can't open. First run openclaw gateway (in the foreground to watch the logs), or confirm the background service is running
A browser extension is blocking the module-based app: when the page is blank and DevTools shows no errors, the official documentation points to "extensions that inject into all pages (especially those with <all_urls> content scripts)". Disable such extensions, try an incognito window or a clean profile; the page's built-in recovery panel Try again can reload directly
Protocol mismatch shown after an update: an old tab or a cached service worker is still running the pre-update UI bundle. First reopen with openclaw dashboard and force-refresh; if that doesn't work, clear site data for that origin, or verify in an incognito window

There is one more case on Windows: the host 127.0.0.1 works fine, but the LAN address won't open — the firewall or group policy is blocking LAN addresses. Run openclaw gateway status --deep on the Windows host; it will report suspected blocked ports and local firewall rules.

❌ `disconnected (1008): pairing required` keeps spinning

Cause: a new browser's first connection requires a one-time pairing approval, and the request hasn't been approved yet.

The right approach: keep the page open (it connects automatically once approved), and on the Gateway host use openclaw devices list to view requests and openclaw devices approve <requestId> to approve. Distinguish the two failure appearances: an explicit rejection shows Access request declined (you can click Request again to reapply); being ignored shows Access request expired (reopening the page sends another request).

Note: if the browser retries with a changed role or permission, the old request gets superseded by the new requestId — run list again before approving, and don't approve a request that is already stale.

❌ In token mode even the local browser is rejected

Cause: when the Gateway starts in token mode without a token configured, it generates a temporary runtime token — it isn't written to the config and can't be recovered; any browser that doesn't have it is rejected, including the local one.

The right approach (the three-step fix from the official docs):

bash

openclaw doctor --generate-gateway-token   # 生成正式 token 写进配置
# 然后重启 Gateway
openclaw gateway auth-token --show         # 交互式终端里查看，粘贴进登录页

❌ Browser too old, can't get into the UI

Cause: the Control UI requires relatively modern browser capabilities. The official line (as of 2026-10): Chrome 147+, Firefox 150+, and Safari 26.2+ on macOS 26.2 / iOS 26.2 / iPadOS 26.2+ (or a Chrome / Firefox released within the last six months).

The right approach: upgrade your browser. Browsers missing key capabilities first see an update-notice page; ones that don't support module scripts at all show This browser is not supported directly. If you hit this inside a native app, you can tap Open in browser to open it in the system default browser instead.

❌ Incognito / private windows need re-pairing every time

Cause: each browser profile gets one device ID; windows that discard site data (incognito, Firefox "never remember history") are treated as a new browser every time.

The right approach: use a fixed profile for daily Control UI access; when the paired device list grows too long, use openclaw devices remove <deviceId> to clear out old entries you no longer use.

Advanced tips (optional)

Turning off the Control UI doesn't touch the bot. gateway.controlUi.enabled: false takes effect hot — it only stops the page and static assets; the bot and existing Gateway connections keep running; change it back to true to restore service, and missing assets are backfilled in the background. However, changing basePath / the resource root directory still requires a Gateway restart:

json5

{
  gateway: {
    controlUi: {
      enabled: true,
      basePath: "/openclaw",   // 挂到子路径；改这个要重启
    },
  },
}

Read-only config banner. For a Gateway started with OPENCLAW_CONFIG_READONLY=1 (or OPENCLAW_NIX_MODE=1), the top of the Control UI shows Gateway configuration is read-only — the config is view-only. To steer people toward your own process for changing config, set OPENCLAW_CONFIG_READONLY_NOTICE to your notice text (ending with a space + an absolute URL automatically adds a Learn more link).

Don't mix up multiple Gateways. When managing several Gateways at once, configure gateway.controlUi.environment for each one:

json5

{
  gateway: {
    controlUi: {
      environment: { label: "edge", color: "amber" },
    },
  },
}

The browser then shows a 2px top color bar, sidebar tag, title suffix, and a matching favicon, so you can tell at a glance which Gateway you're connected to. Colors can be teal / amber / purple / coral / pink / blue / green / red / gray, and the label is limited to 1–24 characters.

Don't panic on disconnect. When the connection drops, loaded directories, the automation editor, Import Memory selections, activity history, and the approval queue all stay in memory and aren't lost; the bottom-left indicator shows Reconnecting… and reconnects automatically, and only after automatic recovery stops does the Retry button appear. But remember one thing: Gateway actions like saving edits or approving requests require a live connection, and reconnecting does not automatically replay them — after reconnecting, manually redo any unconfirmed operations.

Lesson recap

✅ OpenClaw Control UI is the browser console for the Gateway service: open it with openclaw dashboard, local address http://127.0.0.1:18789/, communicating with the Gateway over WebSocket on the same port — it's not a cloud website.

✅ The three gates of connection went smoothly: Gateway secret (token / password) → one-time device pairing (openclaw dashboard in one step, or devices list / approve) → after that, pairing-free access via the device token.

✅ The UI map is memorized: navigation rail = Pages / Sessions / Users + agent avatar at top + Home / Inbox / account at bottom; Ctrl+K command palette, Ctrl+B collapses the sidebar, Ctrl+Shift+O opens a new session.

✅ Daily actions have fixed entry points: switch models in the chat box, view workspace and usage in Details, Pin / archive / Snooze in the session menu, get a read-only public link via Session sharing, manage appearance / plugins / MCP / memory import in Settings, and dock Terminal / Browser / Files / Subagents in the side panel.

Config key / command	Purpose	Notes
`gateway.controlUi.enabled`	Toggle the Control UI	Takes effect hot; turning it off doesn't affect the bot or existing connections
`gateway.controlUi.basePath`	Sub-path prefix	e.g. `/openclaw`; changing it requires a Gateway restart
`gateway.auth.mode`	token / password	Fill in the corresponding value as the Gateway secret on the login page
`gateway.terminal.enabled`	Operator terminal toggle	On by default; requires `operator.admin`
`openclaw dashboard`	Open / fix pairing	Short-lived one-time pairing link
`openclaw gateway auth-token --show`	View the shared token	Run in an interactive terminal on the Gateway host
`openclaw devices list / approve`	Pairing approval	First connection of a new browser
`openclaw gateway --tailscale serve`	HTTPS remote access	The Tailnet approach is recommended

For a complete quick reference of commands and config, see CLI command and config quick reference.

Next lesson preview

The Control UI chat box isn't just for typing — slash commands like /model, /think, and /new work the same in the web version and in chat channels. The next lesson, Chat commands crash course: /model, /think and slash commands, walks through the most commonly used batch of them.

You will learn:

/model family: /model list to list, /model <name> to switch, /model status to check status
/think <level> to adjust the thinking level, /fast for fast mode
/new, /reset to manage the session lifecycle
/skill <name> the universal entry point — invoke skills as commands

Control UI: the console in your browser ​

What you'll be able to do after this lesson ​

Where you are stuck right now ​

When to use this approach ​

🎒 Before you start ​

Core idea ​

Follow along ​

Step 1: Open the OpenClaw Control UI — local port 18789 ​

Step 2: Enter the Gateway secret — OpenClaw Control UI authentication ​

Step 3: Approve device pairing — the first connection from a new browser ​

Step 4: Get to know the three-area navigation — Pages, Sessions, and Users ​

Step 5: Talk to Claw — composer, models, and the Details panel ​

Step 6: Manage sessions — Pin, rename, archive, and share ​

Step 7: Settings page and side panel — appearance, plugins, MCP, and terminal ​

Step 8 (optional): Remote and mobile access to the Control UI ​

Option A (recommended): Expose HTTPS with Tailscale Serve ​

Option B: Pair a phone by scanning a QR code ​

Option C: Install as a PWA ​

Checkpoint ✅ ​

Pitfall reminders ​

❌ The page won't open or is completely blank ​

❌ disconnected (1008): pairing required keeps spinning ​

❌ In token mode even the local browser is rejected ​

❌ Browser too old, can't get into the UI ​

❌ Incognito / private windows need re-pairing every time ​

Advanced tips (optional) ​

Lesson recap ​

Next lesson preview ​

Related Tutorials ​

Control UI: the console in your browser

What you'll be able to do after this lesson

Where you are stuck right now

When to use this approach

🎒 Before you start

Core idea

Follow along

Step 1: Open the OpenClaw Control UI — local port 18789

Step 2: Enter the Gateway secret — OpenClaw Control UI authentication

Step 3: Approve device pairing — the first connection from a new browser

Step 4: Get to know the three-area navigation — Pages, Sessions, and Users

Step 5: Talk to Claw — composer, models, and the Details panel

Step 6: Manage sessions — Pin, rename, archive, and share

Step 7: Settings page and side panel — appearance, plugins, MCP, and terminal

Step 8 (optional): Remote and mobile access to the Control UI

Option A (recommended): Expose HTTPS with Tailscale Serve

Option B: Pair a phone by scanning a QR code

Option C: Install as a PWA

Checkpoint ✅

Pitfall reminders

❌ The page won't open or is completely blank

❌ `disconnected (1008): pairing required` keeps spinning

❌ In token mode even the local browser is rejected

❌ Browser too old, can't get into the UI

❌ Incognito / private windows need re-pairing every time

Advanced tips (optional)

Lesson recap

Next lesson preview

Related Tutorials