| --- |
| summary: "Browser-based control UI for the Gateway (chat, nodes, config)" |
| read_when: |
| - You want to operate the Gateway from a browser |
| - You want Tailnet access without SSH tunnels |
| --- |
| |
| # Control UI (browser) |
|
|
| The Control UI is a small **Vite + Lit** single-page app served by the Gateway: |
|
|
| - default: `http://<host>:7860/` |
| - optional prefix: set `gateway.controlUi.basePath` (e.g. `/openclaw`) |
|
|
| It speaks **directly to the Gateway WebSocket** on the same port. |
|
|
| ## Quick open (local) |
|
|
| If the Gateway is running on the same computer, open: |
|
|
| - http://127.0.0.1:7860/ (or http://localhost:7860/) |
|
|
| If the page fails to load, start the Gateway first: `openclaw gateway`. |
|
|
| Auth is supplied during the WebSocket handshake via: |
|
|
| - `connect.params.auth.token` |
| - `connect.params.auth.password` |
| The dashboard settings panel lets you store a token; passwords are not persisted. |
| The onboarding wizard generates a gateway token by default, so paste it here on first connect. |
|
|
| ## What it can do (today) |
|
|
| - Chat with the model via Gateway WS (`chat.history`, `chat.send`, `chat.abort`, `chat.inject`) |
| - Stream tool calls + live tool output cards in Chat (agent events) |
| - Channels: WhatsApp/Telegram/Discord/Slack + plugin channels (Mattermost, etc.) status + QR login + per-channel config (`channels.status`, `web.login.*`, `config.patch`) |
| - Instances: presence list + refresh (`system-presence`) |
| - Sessions: list + per-session thinking/verbose overrides (`sessions.list`, `sessions.patch`) |
| - Cron jobs: list/add/run/enable/disable + run history (`cron.*`) |
| - Skills: status, enable/disable, install, API key updates (`skills.*`) |
| - Nodes: list + caps (`node.list`) |
| - Exec approvals: edit gateway or node allowlists + ask policy for `exec host=gateway/node` (`exec.approvals.*`) |
| - Config: view/edit `~/.openclaw/openclaw.json` (`config.get`, `config.set`) |
| - Config: apply + restart with validation (`config.apply`) and wake the last active session |
| - Config writes include a base-hash guard to prevent clobbering concurrent edits |
| - Config schema + form rendering (`config.schema`, including plugin + channel schemas); Raw JSON editor remains available |
| - Debug: status/health/models snapshots + event log + manual RPC calls (`status`, `health`, `models.list`) |
| - Logs: live tail of gateway file logs with filter/export (`logs.tail`) |
| - Update: run a package/git update + restart (`update.run`) with a restart report |
|
|
| ## Chat behavior |
|
|
| - `chat.send` is **non-blocking**: it acks immediately with `{ runId, status: "started" }` and the response streams via `chat` events. |
| - Re-sending with the same `idempotencyKey` returns `{ status: "in_flight" }` while running, and `{ status: "ok" }` after completion. |
| - `chat.inject` appends an assistant note to the session transcript and broadcasts a `chat` event for UI-only updates (no agent run, no channel delivery). |
| - Stop: |
| - Click **Stop** (calls `chat.abort`) |
| - Type `/stop` (or `stop|esc|abort|wait|exit|interrupt`) to abort out-of-band |
| - `chat.abort` supports `{ sessionKey }` (no `runId`) to abort all active runs for that session |
|
|
| ## Tailnet access (recommended) |
|
|
| ### Integrated Tailscale Serve (preferred) |
|
|
| Keep the Gateway on loopback and let Tailscale Serve proxy it with HTTPS: |
|
|
| ```bash |
| openclaw gateway --tailscale serve |
| ``` |
|
|
| Open: |
|
|
| - `https://<magicdns>/` (or your configured `gateway.controlUi.basePath`) |
|
|
| By default, Serve requests can authenticate via Tailscale identity headers |
| (`tailscale-user-login`) when `gateway.auth.allowTailscale` is `true`. OpenClaw |
| verifies the identity by resolving the `x-forwarded-for` address with |
| `tailscale whois` and matching it to the header, and only accepts these when the |
| request hits loopback with Tailscale’s `x-forwarded-*` headers. Set |
| `gateway.auth.allowTailscale: false` (or force `gateway.auth.mode: "password"`) |
| if you want to require a token/password even for Serve traffic. |
|
|
| ### Bind to tailnet + token |
|
|
| ```bash |
| openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)" |
| ``` |
|
|
| Then open: |
|
|
| - `http://<tailscale-ip>:7860/` (or your configured `gateway.controlUi.basePath`) |
|
|
| Paste the token into the UI settings (sent as `connect.params.auth.token`). |
|
|
| ## Insecure HTTP |
|
|
| If you open the dashboard over plain HTTP (`http://<lan-ip>` or `http://<tailscale-ip>`), |
| the browser runs in a **non-secure context** and blocks WebCrypto. By default, |
| OpenClaw **blocks** Control UI connections without device identity. |
|
|
| **Recommended fix:** use HTTPS (Tailscale Serve) or open the UI locally: |
|
|
| - `https://<magicdns>/` (Serve) |
| - `http://127.0.0.1:7860/` (on the gateway host) |
|
|
| **Downgrade example (token-only over HTTP):** |
|
|
| ```json5 |
| { |
| gateway: { |
| controlUi: { allowInsecureAuth: true }, |
| bind: "tailnet", |
| auth: { mode: "token", token: "replace-me" }, |
| }, |
| } |
| ``` |
|
|
| This disables device identity + pairing for the Control UI (even on HTTPS). Use |
| only if you trust the network. |
|
|
| See [Tailscale](/gateway/tailscale) for HTTPS setup guidance. |
|
|
| ## Building the UI |
|
|
| The Gateway serves static files from `dist/control-ui`. Build them with: |
|
|
| ```bash |
| pnpm ui:build # auto-installs UI deps on first run |
| ``` |
|
|
| Optional absolute base (when you want fixed asset URLs): |
|
|
| ```bash |
| OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build |
| ``` |
|
|
| For local development (separate dev server): |
|
|
| ```bash |
| pnpm ui:dev # auto-installs UI deps on first run |
| ``` |
|
|
| Then point the UI at your Gateway WS URL (e.g. `ws://127.0.0.1:7860`). |
|
|
| ## Debugging/testing: dev server + remote Gateway |
|
|
| The Control UI is static files; the WebSocket target is configurable and can be |
| different from the HTTP origin. This is handy when you want the Vite dev server |
| locally but the Gateway runs elsewhere. |
|
|
| 1. Start the UI dev server: `pnpm ui:dev` |
| 2. Open a URL like: |
|
|
| ```text |
| http://localhost:5173/?gatewayUrl=ws://<gateway-host>:7860 |
| ``` |
|
|
| Optional one-time auth (if needed): |
|
|
| ```text |
| http://localhost:5173/?gatewayUrl=wss://<gateway-host>:7860&token=<gateway-token> |
| ``` |
|
|
| Notes: |
|
|
| - `gatewayUrl` is stored in localStorage after load and removed from the URL. |
| - `token` is stored in localStorage; `password` is kept in memory only. |
| - Use `wss://` when the Gateway is behind TLS (Tailscale Serve, HTTPS proxy, etc.). |
|
|
| Remote access setup details: [Remote access](/gateway/remote). |
|
|
