OpenClaw Control UI setup: pair a browser without weakening Gateway security
OpenClaw Control UI setup has four steps: reach the Gateway over a private path, authenticate the browser, inspect the pending device request, and approve only the role and scopes you intended to grant. If the UI says pairing required or returns WebSocket code 1008, do not disable device auth or expose the port publicly. Repair the connection through the supported dashboard and device-pairing flow instead.
That distinction matters because the Control UI is an operator surface. It can expose sessions, settings, approvals, devices, and Gateway state. A browser that can reach it is not merely reading a chat transcript.
Contents
- What the Control UI connects to
- OpenClaw Control UI setup on the Gateway host
- How browser pairing and scope upgrades work
- Choose a safe remote access path
- Troubleshoot common setup failures
- A short operator checklist
- FAQ
What the Control UI connects to
The Control UI is a browser app served by the OpenClaw Gateway, not a separate hosted dashboard. On a local Gateway, the documented default URL is http://127.0.0.1:18789/. The browser connects to the Gateway WebSocket on that same port, where Gateway authentication happens before device pairing.
Opening the page is not enough: the WebSocket still needs the configured Gateway credential, and a new browser or device can still need pairing approval.
The table below separates the controls that are often conflated during setup.
| Control | What it proves | What to do when it fails |
|---|---|---|
| Gateway authentication | The browser can authenticate to the Gateway | Check the token, password, Tailscale identity, or trusted proxy configuration. |
| Device pairing | This browser or device is approved for its requested role and scopes | Review the pending request and approve the exact request ID. |
| Remote transport | The browser can reach the Gateway without publishing an admin port | Use an SSH tunnel, Tailscale Serve, or a trusted LAN/Tailnet path. |
| Operator scope | The paired browser may perform a particular control-plane action | Treat a broader scope request as a new approval decision. |
For a broader explanation of the Gateway’s role in sessions, tools, and channels, start with how OpenClaw works. If you are already using the UI to supervise parallel work, the Control UI workspace guide covers that operating workflow. This post stays focused on the access path that should exist before either workflow begins.
OpenClaw Control UI setup on the Gateway host
The clean local path is deliberately boring:
- Start the Gateway, then run
openclaw dashboardon the Gateway host. The command opens or prints a short-lived browser handoff instead of placing a shared Gateway token in a launch URL. - If the Gateway runs on the same computer, open the loopback dashboard URL. Do not replace
127.0.0.1with a public address just to make setup convenient. - If the UI asks for authentication, supply the configured Gateway token or password through Control UI settings. The dashboard documentation says a token entered there is retained for the current tab and selected Gateway URL; passwords are not persisted across reloads.
- Complete the one-time pairing request that follows authentication.
A missing configured token is a special failure mode. OpenClaw may generate an ephemeral runtime token that cannot be recovered later. Run openclaw doctor --generate-gateway-token, restart the Gateway, then retrieve the configured value interactively with openclaw gateway auth-token --show. Do not solve an unknown runtime token by relaxing browser-origin or device-auth rules.
OpenClaw v2026.7.1 expanded the UI with session navigation, live Tasks, usage information, and mobile pairing. It remains a control plane, not a shareable web page.
How browser pairing and scope upgrades work
After authentication succeeds, a new browser can receive disconnected (1008): pairing required. That is a pending device approval, not evidence that the Gateway should be made less strict.
On the Gateway host, inspect requests first:
openclaw devices listLook at the device, requested role, and requested scopes. Then approve the specific request ID:
openclaw devices approve <requestId>The exact request ID matters. The Devices CLI documents that openclaw devices approve --latest only previews the most recent request and exits; use it to inspect a request, then rerun the command with the ID you verified.
A second pairing request from a browser you already approved deserves the same care. OpenClaw treats a change from read access to write or admin access as an approval upgrade. The existing approval remains active while the broader request waits. That is the point: a stale browser token or a changed client should not silently obtain more control than it previously had.
This is part of the same boundary described in the OpenClaw security guide: the session identifier helps route work, but it is not an authorization credential. Pairing, Gateway auth, and scope approval each have separate jobs.
Choose a safe remote access path
Keep the Gateway loopback-only when you can. The official remote-access guide names three practical patterns for reaching a Gateway from another machine:
| Remote setup | Best use | Security property |
|---|---|---|
| SSH tunnel | One operator connecting to a host they administer | The Gateway stays bound to loopback; SSH carries the connection. |
| Tailscale Serve | A persistent personal Gateway on a tailnet | The Gateway can stay private while clients use an authenticated private route. |
| Trusted LAN or Tailnet direct connection | A controlled private network | The direct transport should still use Gateway authentication and pairing. |
For the SSH option, the documented forwarding command is:
ssh -N -L 18789:127.0.0.1:18789 user@gateway-hostWith the tunnel running, open the local loopback URL in the browser that started the tunnel. This avoids turning a Gateway port into a public reverse-proxy target just to use the dashboard remotely.
For a public non-loopback origin, OpenClaw requires an explicit gateway.controlUi.allowedOrigins list. Do not use ['*'] outside tightly controlled local testing: it means any browser origin. Use the Gateway security documentation before changing bind mode, proxy settings, or remote exposure.
Troubleshoot common setup failures
The fastest repair is usually to identify the failed boundary rather than rotate every credential.
The page opens, but the UI says unauthorized
Check the Gateway URL and auth mode. Use openclaw dashboard for a fresh browser handoff, or supply the configured credential through the UI. Replace an ephemeral runtime token with a configured token through the documented doctor-and-restart flow.
The UI returns 1008 or says pairing required
Authentication may already be working. Run openclaw devices list, inspect the pending request, and approve the exact ID. If it keeps changing, check whether the browser is reconnecting with different role, scopes, or device identity.
A previously paired browser suddenly requests more access
Treat this as a scope upgrade. Compare the requested access to the existing approval; do not clear all devices or disable pairing as a first response.
Remote setup works on one machine but not another
Check the transport first. An SSH tunnel makes the remote Gateway appear at local loopback. A reachable Gateway does not automatically permit a remote browser origin.
A short operator checklist
Before granting dashboard access from a new browser or phone:
- Keep the Gateway on loopback unless a private remote route is intentionally configured.
- Use
openclaw dashboardfor the initial or repaired browser handoff. - Confirm the browser passes Gateway authentication without copying a shared token into a URL or chat.
- Inspect
openclaw devices listbefore approving a pending request. - Compare requested and approved scopes when an existing device asks for more access.
- Run
openclaw security audit --deepafter changing Gateway exposure, authentication, proxy settings, or permissions.
The payoff is simple: Control UI remains convenient for operating agents while the Gateway remains an operator boundary rather than another browser service on the network.
FAQ
What is the default OpenClaw Control UI URL?
For a local Gateway, OpenClaw documents http://127.0.0.1:18789/ as the default Control UI URL. You can also run openclaw dashboard on the Gateway host to open or print a safe browser handoff.
Why does OpenClaw Control UI say pairing required after I entered the token?
The Gateway token or password authenticates the connection. Device pairing separately approves the browser or device for its requested role and scopes. Inspect the request with openclaw devices list, then approve the specific request ID only after reviewing it.
Can I expose OpenClaw Control UI directly to the internet?
Treat it as an admin surface, not a public application. Prefer a loopback Gateway with SSH tunneling, Tailscale Serve, or another protected private route. If you must use a non-loopback origin, configure explicit allowed origins and follow the Gateway exposure guidance.
Does device pairing replace Gateway authentication?
No. Gateway authentication happens during the WebSocket handshake. Device pairing is a separate approval for a browser or device and its requested role and scopes.