<!-- source: https://deepwiki.com/openclaw/openclaw/2.7-control-ui-and-webchat -->

# Control UI & WebChat

- extensions/whatsapp/src/auto-reply.web-auto-reply.last-route.test.ts
- scripts/check-docker-e2e-boundaries.mjs
- scripts/ensure-playwright-chromium.mjs
- src/gateway/server-methods/chat.directive-tags.test.ts
- src/gateway/server-methods/chat.ts
- src/gateway/server.chat.gateway-server-chat-b.test.ts
- src/routing/session-key.test.ts
- src/routing/session-key.ts
- src/sessions/user-turn-transcript.test.ts
- src/sessions/user-turn-transcript.ts
- test/scripts/ensure-playwright-chromium.test.ts
- ui/src/styles.css
- ui/src/styles/base.css
- ui/src/styles/chat/layout.css
- ui/src/styles/chat/sidebar.css
- ui/src/styles/chat/text.css
- ui/src/styles/chat/tool-cards.css
- ui/src/styles/config-quick.css
- ui/src/styles/layout.css
- ui/src/styles/layout.mobile.css
- ui/src/styles/skill-workshop.css
- ui/src/test-helpers/control-ui-e2e.ts
- ui/src/types/highlight-js-subpaths.d.ts
- ui/src/ui/app-chat.test.ts
- ui/src/ui/app-chat.ts
- ui/src/ui/app-gateway-chat-load.node.test.ts
- ui/src/ui/app-gateway.node.test.ts
- ui/src/ui/app-gateway.sessions.node.test.ts
- ui/src/ui/app-gateway.ts
- ui/src/ui/app-lifecycle-connect.node.test.ts
- ui/src/ui/app-lifecycle.node.test.ts
- ui/src/ui/app-lifecycle.ts
- ui/src/ui/app-render.assistant-avatar.test.ts
- ui/src/ui/app-render.helpers.node.test.ts
- ui/src/ui/app-render.helpers.ts
- ui/src/ui/app-render.ts
- ui/src/ui/app-scroll.test.ts
- ui/src/ui/app-scroll.ts
- ui/src/ui/app-settings.test.ts
- ui/src/ui/app-view-state.ts
- ui/src/ui/app.ts
- ui/src/ui/chat/build-chat-items.test.ts
- ui/src/ui/chat/build-chat-items.ts
- ui/src/ui/chat/chat-queue.ts
- ui/src/ui/chat/chat-responsive.browser.test.ts
- ui/src/ui/chat/composer-persistence.test.ts
- ui/src/ui/chat/composer-persistence.ts
- ui/src/ui/chat/grouped-render.test.ts
- ui/src/ui/chat/grouped-render.ts
- ui/src/ui/chat/run-lifecycle.test.ts
- ui/src/ui/chat/run-lifecycle.ts
- ui/src/ui/chat/session-controls.ts
- ui/src/ui/chat/tool-cards.node.test.ts
- ui/src/ui/chat/tool-cards.test.ts
- ui/src/ui/chat/tool-cards.ts
- ui/src/ui/chat/user-message-content.ts
- ui/src/ui/components/file-preview-modal.test.ts
- ui/src/ui/components/file-preview-modal.ts
- ui/src/ui/control-ui-performance.test.ts
- ui/src/ui/control-ui-performance.ts
- ui/src/ui/controllers/chat.test.ts
- ui/src/ui/controllers/chat.ts
- ui/src/ui/controllers/sessions.test.ts
- ui/src/ui/controllers/sessions.ts
- ui/src/ui/controllers/skill-workshop.ts
- ui/src/ui/e2e/chat-flow.e2e.test.ts
- ui/src/ui/e2e/chat-picker-pagination.e2e.test.ts
- ui/src/ui/e2e/cron-filters.e2e.test.ts
- ui/src/ui/gateway.node.test.ts
- ui/src/ui/gateway.ts
- ui/src/ui/markdown.test.ts
- ui/src/ui/markdown.ts
- ui/src/ui/navigation.browser.test.ts
- ui/src/ui/session-key.ts
- ui/src/ui/storage.node.test.ts
- ui/src/ui/storage.ts
- ui/src/ui/types/chat-types.ts
- ui/src/ui/ui-types.ts
- ui/src/ui/views/chat.test.ts
- ui/src/ui/views/chat.ts
- ui/src/ui/views/logs.ts
- ui/src/ui/views/skill-workshop.ts

The OpenClaw Gateway serves a browser-based Control UI that acts as the primary administrative and interaction interface for the system. It includes a comprehensive chat interface, settings management, session views, and real-time monitoring.

## Overview

The Control UI is a Single Page Application (SPA) built with **Vite + Lit** and served directly by the Gateway's internal HTTP server. By default, it is accessible at `http://<host>:18789/`, though an optional prefix can be configured via `gateway.controlUi.basePath`. It communicates with the Gateway via the WebSocket Protocol (v3) to perform actions like sending messages, updating configurations, and managing agent lifecycles.

### Implementation Architecture

The UI is organized into a controller-view pattern. Views represent the visual layout using Lit templates, while controllers handle data fetching and state mutations through RPC calls over the WebSocket [ui/src/ui/app-render.ts34-135](https://github.com/openclaw/openclaw/blob/fbdf5937/ui/src/ui/app-render.ts#L34-L135)

**Sources:** [ui/src/ui/app-render.ts1-189](https://github.com/openclaw/openclaw/blob/fbdf5937/ui/src/ui/app-render.ts#L1-L189) [ui/src/ui/views/chat.ts23-26](https://github.com/openclaw/openclaw/blob/fbdf5937/ui/src/ui/views/chat.ts#L23-L26)

## Chat Interface

The Chat interface is the primary interaction point for AI agents. It supports real-time streaming, tool execution visualization, and session management.

### Message Processing Flow

When a user sends a message through the UI, it follows a specific pipeline managed by `app-chat.ts`:

1. Input Handling : handleSendChat triggers the message dispatch, managing attachments and local history ui/src/ui/app-chat.ts 57
2. RPC Request : The client calls the chat.send method via WebSocket ui/src/ui/app-chat.ts 102-108
3. Gateway Routing : The Gateway resolves the sessionKey (e.g., agent:main or agent:ops:main ) and routes the message src/gateway/server-methods/chat.ts 148-150
4. Event Feedback : The Gateway broadcasts events back to the UI, which are processed by refreshChat to update the local AppViewState ui/src/ui/app-chat.ts 212-217

### Data Flow: WebChat to Agent Runtime

The following diagram illustrates the path of a message from the browser UI to the Agent Runtime, utilizing the RPC methods defined in the Gateway.

Title: "Message Delivery Path from Control UI"

```

```

**Sources:** [ui/src/ui/app-chat.ts57-217](https://github.com/openclaw/openclaw/blob/fbdf5937/ui/src/ui/app-chat.ts#L57-L217) [src/gateway/server-methods/chat.ts42-44](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server-methods/chat.ts#L42-L44) [ui/src/ui/views/chat.ts23-33](https://github.com/openclaw/openclaw/blob/fbdf5937/ui/src/ui/views/chat.ts#L23-L33) [src/sessions/transcript-events.ts10](https://github.com/openclaw/openclaw/blob/fbdf5937/src/sessions/transcript-events.ts#L10-L10)

### Chat UI Components

The chat interface is rendered by `renderChat` [ui/src/ui/views/chat.ts24](https://github.com/openclaw/openclaw/blob/fbdf5937/ui/src/ui/views/chat.ts#L24-L24) and includes several interactive elements:

- Session Selector : Allows switching between direct, group, and cron sessions, rendered by renderChatSessionSelect ui/src/ui/chat/session-controls.ts 30
- Message Grouping : Messages are processed through buildChatItems ui/src/ui/chat/build-chat-items.ts 17 and rendered via renderMessageGroup ui/src/ui/chat/grouped-render.ts 8 to handle role-based styling and text avatars.
- Markdown Rendering : The UI uses toSanitizedMarkdownHtml to safely render agent responses, stripping unsafe scripts and links ui/src/ui/markdown.ts 6
- Attachment Store : Manages image and file payloads locally via registerChatAttachmentPayload ui/src/ui/chat/attachment-payload-store.ts 8 and getChatAttachmentDataUrl ui/src/ui/chat/attachment-payload-store.ts 14
- Skill Workshop : An integrated view for triaging agent-proposed skills and modifications, supporting a two-pane layout with a queue and detail view ui/src/ui/views/skill-workshop.ts 122

Title: "Chat View Component Hierarchy"

```

```

**Sources:** [ui/src/ui/views/chat.ts24](https://github.com/openclaw/openclaw/blob/fbdf5937/ui/src/ui/views/chat.ts#L24-L24) [ui/src/ui/chat/session-controls.ts30](https://github.com/openclaw/openclaw/blob/fbdf5937/ui/src/ui/chat/session-controls.ts#L30-L30) [ui/src/ui/chat/grouped-render.ts8](https://github.com/openclaw/openclaw/blob/fbdf5937/ui/src/ui/chat/grouped-render.ts#L8-L8) [ui/src/ui/chat/attachment-payload-store.ts8-14](https://github.com/openclaw/openclaw/blob/fbdf5937/ui/src/ui/chat/attachment-payload-store.ts#L8-L14) [ui/src/ui/markdown.ts6](https://github.com/openclaw/openclaw/blob/fbdf5937/ui/src/ui/markdown.ts#L6-L6) [ui/src/ui/views/skill-workshop.ts122](https://github.com/openclaw/openclaw/blob/fbdf5937/ui/src/ui/views/skill-workshop.ts#L122-L122)

## Configuration & Settings

The Control UI provides a dynamic form-based interface for managing the Gateway's configuration (`openclaw.json`).

### Configuration Form Rendering

The `renderConfig` view [ui/src/ui/views/config.ts188](https://github.com/openclaw/openclaw/blob/fbdf5937/ui/src/ui/views/config.ts#L188-L188) generates UI elements based on the JSON Schema provided by the Gateway.

- Form vs Raw : The UI provides a Form mode and a Raw JSON editor.
- Secret Management : Structured SecretRef values are rendered to prevent accidental object-to-string corruption.
- Validation : Config writes include a base-hash guard to prevent clobbering concurrent edits.

### Quick Settings

The `renderQuickSettings` view [ui/src/ui/views/config-quick.ts187](https://github.com/openclaw/openclaw/blob/fbdf5937/ui/src/ui/views/config-quick.ts#L187-L187) provides a compact dashboard for frequently accessed settings.

- Model & Thinking : Allows changing the current model and thinking level.
- Security : Displays gateway authentication status, execution policy, and browser enablement.
- Assistant Identity : Allows overriding the assistant's avatar and name locally via setAssistantAvatarOverride ui/src/ui/app-render.ts 52

**Sources:** [ui/src/ui/app-render.ts52-188](https://github.com/openclaw/openclaw/blob/fbdf5937/ui/src/ui/app-render.ts#L52-L188)

## Session & Memory Management

The UI provides dedicated views for managing sessions and the "Dreaming" memory system.

### Session Management

The `loadSessions` controller [ui/src/ui/controllers/sessions.ts123](https://github.com/openclaw/openclaw/blob/fbdf5937/ui/src/ui/controllers/sessions.ts#L123-L123) allows users to interact with session data.

- Lifecycle : Users can list, patch, and delete sessions via the sessions.* RPC family.
- Restoration : Sessions can be restored or branched from specific checkpoints ui/src/ui/controllers/sessions.ts 121-126
- Key Parsing : Session keys are parsed into displayable names via resolveSessionDisplayName ui/src/ui/app-render.ts 161

### Dreaming (Memory)

The `renderDreaming` view [ui/src/ui/app-render.ts195](https://github.com/openclaw/openclaw/blob/fbdf5937/ui/src/ui/app-render.ts#L195-L195) provides a "Dream Diary" reader and status monitoring.

- Status Monitoring : Displays status for dreaming phases (light, deep, rem) via loadDreamingStatus ui/src/ui/app-render.ts 102
- Diary Management : Provides actions like loadDreamDiary , backfillDreamDiary , and dedupeDreamDiary ui/src/ui/app-render.ts 91-107
- Wiki Integration : Displays synthesized insights and memory palace items via loadWikiImportInsights and loadWikiMemoryPalace ui/src/ui/app-render.ts 103-104

### Cron & Automations

The `renderCron` controller [ui/src/ui/controllers/cron.ts72-88](https://github.com/openclaw/openclaw/blob/fbdf5937/ui/src/ui/controllers/cron.ts#L72-L88) manages scheduled jobs.

- Job Control : Allows creating, editing, cloning, and running cron jobs via addCronJob , toggleCronJob , and runCronJob ui/src/ui/app-render.ts 75-78
- History : Displays run history with status and delivery filtering via loadCronRuns ui/src/ui/app-render.ts 73

**Sources:** [ui/src/ui/controllers/sessions.ts121-126](https://github.com/openclaw/openclaw/blob/fbdf5937/ui/src/ui/controllers/sessions.ts#L121-L126) [ui/src/ui/app-render.ts73-195](https://github.com/openclaw/openclaw/blob/fbdf5937/ui/src/ui/app-render.ts#L73-L195) [ui/src/ui/controllers/cron.ts72-88](https://github.com/openclaw/openclaw/blob/fbdf5937/ui/src/ui/controllers/cron.ts#L72-L88)

## WebChat & Embedding

The Gateway serves a simplified WebChat interface designed for embedding or lightweight use.

### Authentication & Handshake

- Pairing : New browser profiles require one-time pairing approval via approveDevicePairing ui/src/ui/app-render.ts 91
- Handshake : Auth is supplied during the WebSocket handshake via tokens, passwords, or device tokens.
- Device Management : Users can revoke or rotate device tokens via the devices controller ui/src/ui/controllers/devices.ts 91-95

### Localization

The UI supports multiple locales managed via the `i18n` subsystem [ui/src/ui/app-render.ts4](https://github.com/openclaw/openclaw/blob/fbdf5937/ui/src/ui/app-render.ts#L4-L4) Translations are handled through the `t` function [ui/src/ui/views/chat.ts6](https://github.com/openclaw/openclaw/blob/fbdf5937/ui/src/ui/views/chat.ts#L6-L6) and `i18n.setLocale` [ui/src/ui/views/chat.test.ts5](https://github.com/openclaw/openclaw/blob/fbdf5937/ui/src/ui/views/chat.test.ts#L5-L5)

**Sources:** [ui/src/ui/app-render.ts4-91](https://github.com/openclaw/openclaw/blob/fbdf5937/ui/src/ui/app-render.ts#L4-L91) [ui/src/ui/controllers/devices.ts91-95](https://github.com/openclaw/openclaw/blob/fbdf5937/ui/src/ui/controllers/devices.ts#L91-L95) [ui/src/ui/views/chat.test.ts5](https://github.com/openclaw/openclaw/blob/fbdf5937/ui/src/ui/views/chat.test.ts#L5-L5) [ui/src/ui/views/chat.ts6](https://github.com/openclaw/openclaw/blob/fbdf5937/ui/src/ui/views/chat.ts#L6-L6)
