Control UI

• default: http://<host>:18789/
• optional prefix: set gateway.controlUi.basePath (e.g. /openclaw)

​

Quick open (local)

• http://127.0.0.1:18789/ (or http://localhost:18789/)

• 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"

​

Device pairing (first connection)

# List pending requests
openclaw devices list

# Approve by request ID
openclaw devices approve <requestId>

• Direct local loopback browser connections (127.0.0.1 / localhost) are auto-approved.
• Tailnet and LAN browser connects still require explicit approval, even when they originate from the same machine.
• Each browser profile generates a unique device ID, so switching browsers or clearing browser data will require re-pairing.

​

Personal identity (browser-local)

​

Runtime config endpoint

​

Language support

• Supported locales: en, zh-CN, zh-TW, pt-BR, de, es, ja-JP, ko, fr, tr, uk, id, pl, th
• Non-English translations are lazy-loaded in the browser.
• The selected locale is saved in browser storage and reused on future visits.
• Missing translation keys fall back to English.

​

What it can do (today)

• Chat with the model via Gateway WS (chat.history, chat.send, chat.abort, chat.inject)
• Talk to OpenAI Realtime directly from the browser via WebRTC. The Gateway mints a short-lived Realtime client secret with talk.realtime.session; the browser sends microphone audio directly to OpenAI and relays openclaw_agent_consult tool calls back through chat.send for the larger configured OpenClaw model.
• Stream tool calls + live tool output cards in Chat (agent events)
• Channels: built-in plus bundled/external plugin channels status, QR login, and per-channel config (channels.status, web.login.*, config.patch)
• Instances: presence list + refresh (system-presence)
• Sessions: list + per-session model/thinking/fast/verbose/trace/reasoning overrides (sessions.list, sessions.patch)
• Dreams: dreaming status, enable/disable toggle, and Dream Diary reader (doctor.memory.status, doctor.memory.dreamDiary, config.patch)
• Cron jobs: list/add/edit/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 writes (config.set/config.apply/config.patch) also preflight active SecretRef resolution for refs in the submitted config payload; unresolved active submitted refs are rejected before write
• Config schema + form rendering (config.schema / config.schema.lookup, including field title / description, matched UI hints, immediate child summaries, docs metadata on nested object/wildcard/array/composition nodes, plus plugin + channel schemas when available); Raw JSON editor is available only when the snapshot has a safe raw round-trip
• If a snapshot cannot safely round-trip raw text, Control UI forces Form mode and disables Raw mode for that snapshot
• Raw JSON editor “Reset to saved” preserves the raw-authored shape (formatting, comments, $include layout) instead of re-rendering a flattened snapshot, so external edits survive a reset when the snapshot can safely round-trip
• Structured SecretRef object values are rendered read-only in form text inputs to prevent accidental object-to-string corruption
• 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

• For isolated jobs, delivery defaults to announce summary. You can switch to none if you want internal-only runs.
• Channel/target fields appear when announce is selected.
• Webhook mode uses delivery.mode = "webhook" with delivery.to set to a valid HTTP(S) webhook URL.
• For main-session jobs, webhook and none delivery modes are available.
• Advanced edit controls include delete-after-run, clear agent override, cron exact/stagger options, agent model/thinking overrides, and best-effort delivery toggles.
• Form validation is inline with field-level errors; invalid values disable the save button until fixed.
• Set cron.webhookToken to send a dedicated bearer token, if omitted the webhook is sent without an auth header.
• Deprecated fallback: stored legacy jobs with notify: true can still use cron.webhook until migrated.

​

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.history responses are size-bounded for UI safety. When transcript entries are too large, Gateway may truncate long text fields, omit heavy metadata blocks, and replace oversized messages with a placeholder ([chat.history omitted: message too large]).
• Assistant/generated images are persisted as managed media references and served back through authenticated Gateway media URLs, so reloads do not depend on raw base64 image payloads staying in the chat history response.
• chat.history also strips display-only inline directive tags from visible assistant text (for example [[reply_to_*]] and [[audio_as_voice]]), plain-text tool-call XML payloads (including <tool_call>...</tool_call>, <function_call>...</function_call>, <tool_calls>...</tool_calls>, <function_calls>...</function_calls>, and truncated tool-call blocks), and leaked ASCII/full-width model control tokens, and omits assistant entries whose whole visible text is only the exact silent token NO_REPLY / no_reply.
• During an active send and the final history refresh, the chat view keeps local optimistic user/assistant messages visible if chat.history briefly returns an older snapshot; the canonical transcript replaces those local messages once the Gateway history catches up.
• 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).
• The chat header model and thinking pickers patch the active session immediately through sessions.patch; they are persistent session overrides, not one-turn-only send options.
• When fresh Gateway session usage reports show high context pressure, the chat composer area shows a context notice and, at recommended compaction levels, a compact button that runs the normal session compaction path. Stale token snapshots are hidden until the Gateway reports fresh usage again.
• Talk mode uses a registered realtime voice provider that supports browser WebRTC sessions. Configure OpenAI with talk.provider: "openai" plus talk.providers.openai.apiKey, or reuse the Voice Call realtime provider config. The browser never receives the standard OpenAI API key; it receives only the ephemeral Realtime client secret. Google Live realtime voice is supported for backend Voice Call and Google Meet bridges, but not this browser WebRTC path yet. The Realtime session prompt is assembled by the Gateway; talk.realtime.session does not accept caller-provided instruction overrides.
• In the Chat composer, the Talk control is the waves button next to the microphone dictation button. When Talk starts, the composer status row shows Connecting Talk..., then Talk live while audio is connected, or Asking OpenClaw... while a realtime tool call is consulting the configured larger model through chat.send.
• Stop:
  • Click Stop (calls chat.abort)
  • While a run is active, normal follow-ups queue. Click Steer on a queued message to inject that follow-up into the running turn.
  • Type /stop (or standalone abort phrases like stop, stop action, stop run, stop openclaw, please stop) to abort out-of-band
  • chat.abort supports { sessionKey } (no runId) to abort all active runs for that session
• Abort partial retention:
  • When a run is aborted, partial assistant text can still be shown in the UI
  • Gateway persists aborted partial assistant text into transcript history when buffered output exists
  • Persisted entries include abort metadata so transcript consumers can tell abort partials from normal completion output

​

PWA install and web push

• OPENCLAW_VAPID_PUBLIC_KEY
• OPENCLAW_VAPID_PRIVATE_KEY
• OPENCLAW_VAPID_SUBJECT (defaults to mailto:openclaw@localhost)

• push.web.vapidPublicKey — fetches the active VAPID public key.
• push.web.subscribe — registers an endpoint plus keys.p256dh/keys.auth.
• push.web.unsubscribe — removes a registered endpoint.
• push.web.test — sends a test notification to the caller’s subscription.

​

Hosted embeds

• strict: disables script execution inside hosted embeds
• scripts: allows interactive embeds while keeping origin isolation; this is the default and is usually enough for self-contained browser games/widgets
• trusted: adds allow-same-origin on top of allow-scripts for same-site documents that intentionally need stronger privileges

{
  gateway: {
    controlUi: {
      embedSandbox: "scripts",
    },
  },
}

​

Tailnet access (recommended)

​

Integrated Tailscale Serve (preferred)

openclaw gateway --tailscale serve

• https://<magicdns>/ (or your configured gateway.controlUi.basePath)

​

Bind to tailnet + token

openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)"

• http://<tailscale-ip>:18789/ (or your configured gateway.controlUi.basePath)

​

Insecure HTTP

• localhost-only insecure HTTP compatibility with gateway.controlUi.allowInsecureAuth=true
• successful operator Control UI auth through gateway.auth.mode: "trusted-proxy"
• break-glass gateway.controlUi.dangerouslyDisableDeviceAuth=true

• https://<magicdns>/ (Serve)
• http://127.0.0.1:18789/ (on the gateway host)

{
  gateway: {
    controlUi: { allowInsecureAuth: true },
    bind: "tailnet",
    auth: { mode: "token", token: "replace-me" },
  },
}

• It allows localhost Control UI sessions to proceed without device identity in non-secure HTTP contexts.
• It does not bypass pairing checks.
• It does not relax remote (non-localhost) device identity requirements.

{
  gateway: {
    controlUi: { dangerouslyDisableDeviceAuth: true },
    bind: "tailnet",
    auth: { mode: "token", token: "replace-me" },
  },
}

• successful trusted-proxy auth can admit operator Control UI sessions without device identity
• this does not extend to node-role Control UI sessions
• same-host loopback reverse proxies still do not satisfy trusted-proxy auth; see Trusted proxy auth

​

Content Security Policy

• Avatars and images served under relative paths (for example /avatars/<id>) still render, including authenticated avatar routes that the UI fetches and converts into local blob: URLs.
• Inline data:image/... URLs still render (useful for in-protocol payloads).
• Local blob: URLs created by the Control UI still render.
• Remote avatar URLs emitted by channel metadata are stripped at the Control UI’s avatar helpers and replaced with the built-in logo/badge, so a compromised or malicious channel cannot force arbitrary remote image fetches from an operator browser.

​

Avatar route auth

• GET /avatar/<agentId> returns the avatar image only to authenticated callers. GET /avatar/<agentId>?meta=1 returns the avatar metadata under the same rule.
• Unauthenticated requests to either route are rejected (matching the sibling assistant-media route). This prevents the avatar route from leaking agent identity on hosts that are otherwise protected.
• The Control UI itself forwards the gateway token as a bearer header when fetching avatars, and uses authenticated blob URLs so the image still renders in dashboards.

​

Building the UI

pnpm ui:build

OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build

pnpm ui:dev

​

Debugging/testing: dev server + remote Gateway

1. Start the UI dev server: pnpm ui:dev
2. Open a URL like:

http://localhost:5173/?gatewayUrl=ws://<gateway-host>:18789

http://localhost:5173/?gatewayUrl=wss://<gateway-host>:18789#token=<gateway-token>

• gatewayUrl is stored in localStorage after load and removed from the URL.
• token should be passed via the URL fragment (#token=...) whenever possible. Fragments are not sent to the server, which avoids request-log and Referer leakage. Legacy ?token= query params are still imported once for compatibility, but only as a fallback, and are stripped immediately after bootstrap.
• password is kept in memory only.
• When gatewayUrl is set, the UI does not fall back to config or environment credentials. Provide token (or password) explicitly. Missing explicit credentials is an error.
• Use wss:// when the Gateway is behind TLS (Tailscale Serve, HTTPS proxy, etc.).
• gatewayUrl is only accepted in a top-level window (not embedded) to prevent clickjacking.
• Non-loopback Control UI deployments must set gateway.controlUi.allowedOrigins explicitly (full origins). This includes remote dev setups.
• Gateway startup may seed local origins such as http://localhost:<port> and http://127.0.0.1:<port> from the effective runtime bind and port, but remote browser origins still need explicit entries.
• Do not use gateway.controlUi.allowedOrigins: ["*"] except for tightly controlled local testing. It means allow any browser origin, not “match whatever host I am using.”
• gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true enables Host-header origin fallback mode, but it is a dangerous security mode.

{
  gateway: {
    controlUi: {
      allowedOrigins: ["http://localhost:5173"],
    },
  },
}

​

Related

• Dashboard — gateway dashboard
• WebChat — browser-based chat interface
• TUI — terminal user interface
• Health Checks — gateway health monitoring