mirror of
https://github.com/openclaw/openclaw.git
synced 2026-04-06 23:01:08 +00:00
94 lines
4.9 KiB
Markdown
94 lines
4.9 KiB
Markdown
---
|
|
summary: "Gateway dashboard (Control UI) access and auth"
|
|
read_when:
|
|
- Changing dashboard authentication or exposure modes
|
|
title: "Dashboard"
|
|
---
|
|
|
|
# Dashboard (Control UI)
|
|
|
|
The Gateway dashboard is the browser Control UI served at `/` by default
|
|
(override with `gateway.controlUi.basePath`).
|
|
|
|
Quick open (local Gateway):
|
|
|
|
- [http://127.0.0.1:18789/](http://127.0.0.1:18789/) (or [http://localhost:18789/](http://localhost:18789/))
|
|
|
|
Key references:
|
|
|
|
- [Control UI](/web/control-ui) for usage and UI capabilities.
|
|
- [Tailscale](/gateway/tailscale) for Serve/Funnel automation.
|
|
- [Web surfaces](/web) for bind modes and security notes.
|
|
|
|
Authentication is enforced at the WebSocket handshake via the configured gateway
|
|
auth path:
|
|
|
|
- `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"`
|
|
|
|
See `gateway.auth` in [Gateway configuration](/gateway/configuration).
|
|
|
|
Security note: the Control UI is an **admin surface** (chat, config, exec approvals).
|
|
Do not expose it publicly. The UI keeps dashboard URL tokens in sessionStorage
|
|
for the current browser tab session and selected gateway URL, and strips them from the URL after load.
|
|
Prefer localhost, Tailscale Serve, or an SSH tunnel.
|
|
|
|
## Fast path (recommended)
|
|
|
|
- After onboarding, the CLI auto-opens the dashboard and prints a clean (non-tokenized) link.
|
|
- Re-open anytime: `openclaw dashboard` (copies link, opens browser if possible, shows SSH hint if headless).
|
|
- If the UI prompts for shared-secret auth, paste the configured token or
|
|
password into Control UI settings.
|
|
|
|
## Auth basics (local vs remote)
|
|
|
|
- **Localhost**: open `http://127.0.0.1:18789/`.
|
|
- **Shared-secret token source**: `gateway.auth.token` (or
|
|
`OPENCLAW_GATEWAY_TOKEN`); `openclaw dashboard` can pass it via URL fragment
|
|
for one-time bootstrap, and the Control UI keeps it in sessionStorage for the
|
|
current browser tab session and selected gateway URL instead of localStorage.
|
|
- If `gateway.auth.token` is SecretRef-managed, `openclaw dashboard`
|
|
prints/copies/opens a non-tokenized URL by design. This avoids exposing
|
|
externally managed tokens in shell logs, clipboard history, or browser-launch
|
|
arguments.
|
|
- If `gateway.auth.token` is configured as a SecretRef and is unresolved in your
|
|
current shell, `openclaw dashboard` still prints a non-tokenized URL plus
|
|
actionable auth setup guidance.
|
|
- **Shared-secret password**: use the configured `gateway.auth.password` (or
|
|
`OPENCLAW_GATEWAY_PASSWORD`). The dashboard does not persist passwords across
|
|
reloads.
|
|
- **Identity-bearing modes**: Tailscale Serve can satisfy Control UI/WebSocket
|
|
auth via identity headers when `gateway.auth.allowTailscale: true`, and a
|
|
non-loopback identity-aware reverse proxy can satisfy
|
|
`gateway.auth.mode: "trusted-proxy"`. In those modes the dashboard does not
|
|
need a pasted shared secret for the WebSocket.
|
|
- **Not localhost**: use Tailscale Serve, a non-loopback shared-secret bind, a
|
|
non-loopback identity-aware reverse proxy with
|
|
`gateway.auth.mode: "trusted-proxy"`, or an SSH tunnel. HTTP APIs still use
|
|
shared-secret auth unless you intentionally run private-ingress
|
|
`gateway.auth.mode: "none"` or trusted-proxy HTTP auth. See
|
|
[Web surfaces](/web).
|
|
|
|
<a id="if-you-see-unauthorized-1008"></a>
|
|
|
|
## If you see "unauthorized" / 1008
|
|
|
|
- Ensure the gateway is reachable (local: `openclaw status`; remote: SSH tunnel `ssh -N -L 18789:127.0.0.1:18789 user@host` then open `http://127.0.0.1:18789/`).
|
|
- For `AUTH_TOKEN_MISMATCH`, clients may do one trusted retry with a cached device token when the gateway returns retry hints. That cached-token retry reuses the token's cached approved scopes; explicit `deviceToken` / explicit `scopes` callers keep their requested scope set. If auth still fails after that retry, resolve token drift manually.
|
|
- Outside that retry path, connect auth precedence is explicit shared token/password first, then explicit `deviceToken`, then stored device token, then bootstrap token.
|
|
- On the async Tailscale Serve Control UI path, failed attempts for the same
|
|
`{scope, ip}` are serialized before the failed-auth limiter records them, so
|
|
the second concurrent bad retry can already show `retry later`.
|
|
- For token drift repair steps, follow [Token drift recovery checklist](/cli/devices#token-drift-recovery-checklist).
|
|
- Retrieve or supply the shared secret from the gateway host:
|
|
- Token: `openclaw config get gateway.auth.token`
|
|
- Password: resolve the configured `gateway.auth.password` or
|
|
`OPENCLAW_GATEWAY_PASSWORD`
|
|
- SecretRef-managed token: resolve the external secret provider or export
|
|
`OPENCLAW_GATEWAY_TOKEN` in this shell, then rerun `openclaw dashboard`
|
|
- No shared secret configured: `openclaw doctor --generate-gateway-token`
|
|
- In the dashboard settings, paste the token or password into the auth field,
|
|
then connect.
|