Books / OpenClaw Complete Guide: From Internals to Production
Chapter 38

Control UI Deep Dive: Config Editor, Live Logs, Approval Management and Dream Diary

Chapter 38: Control UI Deep Dive — Configuration Editing, Live Logs, Approval Management, and Dream Diary

Overview

The Control UI is the nerve center visualization interface of OpenClaw. It is far more than a chat window — it is the Gateway console, configuration hub, monitoring dashboard, and memory introspection tool all in one. This chapter provides a deep-dive into every functional module of the Control UI, helping you unlock the full potential of this single-page application.

Access URL: http://127.0.0.1:18789/ (when running locally)

38.1 Technical Architecture: Vite + Lit and the Case for Lightweight Frameworks

Technology Stack Overview

The Control UI is built with:

Build tool:  Vite 5.x
UI framework: Lit 3.x (Web Components)
Transport:   Native WebSocket (direct Gateway connection)
Styling:     CSS Custom Properties (CSS variable theming)
PWA:         Workbox + Web App Manifest
Localization: 14 languages (built-in i18n)

Why Lit Instead of React/Vue?

This was a deliberate trade-off decision:

Bundle Size Advantage

React (production build):  ~42KB gzipped
Vue 3 (production build):  ~22KB gzipped
Lit 3:                      ~7KB gzipped

The Control UI needs to run smoothly on low-performance devices (Raspberry Pi running locally, older intranet servers). A 7KB runtime has virtually zero startup overhead.

Web Components Natural Isolation

Lit is built on the native Web Components specification. Each component is an independent custom HTML element with naturally isolated CSS scope, eliminating style bleeding. This is critical for an interface that needs to dynamically inject HTML content from the Agent (tool call cards, Canvas rendering).

WebSocket Direct-Connect Architecture

The Control UI does not communicate with the Gateway via REST API. Instead, it maintains a persistent WebSocket connection, with all state updates (logs, tool call results, Node status changes) pushed in real time through this connection — no polling required. This aligns naturally with Lit's reactive property system: WebSocket messages trigger property updates, and Lit efficiently updates only the affected DOM nodes.

38.2 Chat Interface and Basic Interaction

Sending and Receiving Messages

The main interface of the Control UI is a streaming chat window that supports:

Message History Navigation

Keyboard shortcuts:
  ↑ / ↓        Scroll through previous messages in the input box
  Ctrl+Enter   New line (without sending)
  Enter        Send message
  Esc          Cancel current input, focus the message list

Thinking Mode Display

When the Agent has Thinking mode enabled, the Control UI displays the internal reasoning process in collapsible <details> blocks:

<details class="thinking-block">
  <summary>Agent is thinking... (1,247 tokens)</summary>
  <!-- Full reasoning chain visible when expanded -->
</details>

38.3 WebRTC Voice Talk Mode

Feature Description

Talk Mode turns the Control UI into a voice interaction terminal. The user speaks through a microphone, speech is transcribed in real time, and the Agent's reply is read back via TTS.

Activating Talk Mode

Click the microphone icon in the bottom-right corner of the chat interface, or use the shortcut Ctrl+Shift+T.

Talk Mode workflow:
User speaks →
  Browser captures microphone audio (WebRTC getUserMedia) →
  Real-time VAD detects pauses (Voice Activity Detection) →
  Audio stream sent to Gateway via WebSocket →
  Gateway calls STT (speech-to-text) →
  Text sent to Agent →
  Agent generates reply →
  Gateway calls TTS →
  Audio stream returned to Browser →
  Browser plays speech

Talk Mode Configuration

Configure in openclaw.json:

{
  "talkMode": {
    "stt": {
      "provider": "openai",
      "model": "whisper-1",
      "language": "en"
    },
    "tts": {
      "provider": "openai",
      "model": "tts-1",
      "voice": "nova",
      "speed": 1.0
    },
    "vad": {
      "silenceThresholdMs": 800,
      "minSpeechDurationMs": 200
    }
  }
}

Usage Tips

38.4 Streaming Tool Call Cards

When the Agent invokes a tool, the Control UI displays the complete tool call lifecycle as a real-time updating card.

Card Structure Breakdown

┌─────────────────────────────────────────────────────┐
│ ⚙ system.run                           [node-a1b2] │
│ ─────────────────────────────────────────────────── │
│ Input:                                              │
│   command: "df -h /data"                            │
│ ─────────────────────────────────────────────────── │
│ Output: (streaming, updates in real time)           │
│   Filesystem  Size  Used Avail Use% Mounted on      │
│   /dev/sda1   465G  234G  208G  53% /data           │
│ ─────────────────────────────────────────────────── │
│ Status: ✓ Success  Duration: 0.34s  Tokens: +127   │
└─────────────────────────────────────────────────────┘

Card Status Meanings

Status Icon Meaning
⟳ Spinning Tool call in progress
✓ Green Execution succeeded
✕ Red Execution failed (with error details)
⏸ Paused Awaiting approval (execApprovals)
⚡ Lightning Sub-Agent parallel execution

Parallel Tool Call Display

When the Agent calls multiple tools in parallel, cards are displayed in a grid layout:

[system.run @ Pi]    [camera.snap @ iPhone]
    ✓ Done               ⟳ In Progress
[contacts.search @ Android]
    ✓ Done

38.5 Dual-Mode Configuration Editor

The Control UI's built-in configuration editor supports two working modes, switchable at any time.

Form Mode

Form mode deconstructs the key fields of openclaw.json into intuitive UI controls:

Model Configuration
  Primary model:   [Dropdown] anthropic/claude-sonnet-4-6
  Fallback model:  [Dropdown] openai/gpt-4.1-mini
  Max tokens:      [Slider] 8192  ────────────│────── 200k

Thinking Configuration
  Thinking mode:   [Toggle] ON
  Thinking budget: [Number input] 10000 tokens

Skills Management
  [List] ☑ web-search  ☑ code-exec  ☐ email  ☑ calendar

Log level:         [Dropdown] info

Form mode is ideal for everyday adjustments — no need to understand the JSON structure, with low risk of accidental errors.

Raw JSON Mode

Click the { } button in the top-right corner to switch to the JSON editor (Monaco Editor — the same editor engine as VS Code):

{
  "model": "anthropic/claude-sonnet-4-6",
  "fallbackModel": "openai/gpt-4.1-mini",
  "thinking": {
    "enabled": true,
    "budget": 10000
  },
  "skills": {
    "lazy": true,
    "enabled": ["web-search", "code-exec", "calendar"]
  },
  "logging": {
    "level": "info",
    "output": "file"
  }
}

JSON mode supports:

Save and Hot-Reload

After clicking "Save," the Control UI sends the updated configuration to the Gateway via WebSocket. The Gateway hot-reloads most configuration items without restarting (model switching, log level changes, Skills additions/removals, etc.). A small number of low-level settings (port, TLS certificate) require a restart.

38.6 Session Override

Session Override allows you to temporarily adjust model behavior for the current session without modifying the global configuration. Settings automatically revert to the global configuration when the session ends.

Overridable Parameters

Parameter Description Example
model Override the model used for the current session anthropic/claude-opus-4-6
thinkingMode Thinking depth (none/low/medium/high) high
maxTokens Maximum tokens per response 16000
verbosity Response verbosity (concise/normal/detailed) detailed
language Response language preference en

How to Use

Click the "Session Settings" icon in the top-right corner of the chat interface to open the override panel:

Current Session Temporary Overrides
  Model:          [anthropic/claude-opus-4-6  ▼]  (this session only)
  Thinking mode:  [high                        ▼]
  Max tokens:     [16000                          ]
  Verbosity:      [detailed                    ▼]

  [Apply] [Reset to Global Defaults]

Typical use cases:

38.7 Cron Task Visual Management

The Cron panel in the Control UI provides complete lifecycle management for scheduled tasks.

Creating a Cron Task

Click "+ New Task" in the Cron panel and fill in:

Task name:       Daily System Health Check
Cron expression: 0 9 * * *          (every day at 9 AM)
Prompt:          "Check the status of all Nodes, report anomalies, check disk usage"
Timeout:         5 minutes
Retry on failure: 3 times, every 5 minutes
Notification:    Web Push on failure

Supported Cron format (6 fields, including seconds):

Sec Min Hour Day Month Weekday
0   0   *    *   *     *       Every hour on the hour
0   */30 *   *   *     *       Every 30 minutes
0   9    *   *   1-5   *       Weekdays at 9 AM
0   0    0   *   *     *       Every day at midnight

Task List and Status Monitoring

Task Name                   Status   Last Run           Next Run
Daily System Health Check   ✓ OK     Today 09:00:05     Tomorrow 09:00:00
Hourly Disk Check           ✓ OK     09:30:02           10:00:00
Weekly Report Generation    ✕ Failed This Mon 08:59:58  Next Mon 09:00:00
Backup ~/.openclaw          ✓ OK     Yesterday 02:00:01 Today 02:00:00

Task History and Execution Records

Click a task name to expand its execution history:

Execution History (last 20 runs)
  2026-04-26 09:00:05  ✓ Success  45s   [View Details]
  2026-04-25 09:00:03  ✓ Success  38s   [View Details]
  2026-04-24 09:00:01  ✕ Failed   300s  [View Error]

38.8 Node Capability Inspection and Device Management

Node List Panel

In the "Nodes" tab, you can see the real-time status of all connected nodes:

Node Name                  Platform  Status    Capabilities  Latency
Hexin's iPhone 15 Pro      iOS       ● Online  5             12ms
Pi Node - Living Room      Headless  ● Online  2             8ms
Hexin's MacBook Pro        macOS     ○ Offline 6             —

Capability Inspector

Click any node to expand its capability details:

Pi Node - Living Room (node-a1b2c3d4)
Platform: Headless | Connected: 2h 15m | Latency: 8ms

Declared Capabilities:
  ✓ system.run      [Test] [Revoke]
  ✓ system.which    [Test] [Revoke]

Click "Test" to perform a live test invocation of that capability.

Manually Testing a Capability

After clicking "Test," a test panel appears:

Test system.run @ Pi Node - Living Room

Input parameters (JSON):
{
  "command": "uptime"
}

[Run Test]

Result:
   09:15:42 up 2:15,  1 user,  load average: 0.08, 0.05, 0.01
  Duration: 0.21s  Status: ✓ Success

38.9 Execution Approval Queue Management

When the execApprovals mechanism is triggered, commands awaiting approval appear in the "Approvals" panel.

Approval Panel Interface

Pending Approvals (3 items)
───────────────────────────────────────────────────────
[!] rm -rf /tmp/old-cache          @ Pi Node    09:15:33
    Source Agent: Session #4891
    Context: "Cleaning up old cache files to free disk space"
    [Approve] [Reject] [View Full Context]

[!] sudo apt upgrade -y            @ macOS Node  09:15:41
    Source Agent: Cron task "Weekly System Update"
    Context: "Executing scheduled system package updates"
    [Approve] [Reject] [View Full Context]

[!] curl -o /tmp/script.sh https://example.com/install.sh  @ Pi Node  09:16:02
    Source Agent: Session #4891
    [Approve] [Reject] [View Full Context]

Batch Approval and Security Policies

Approval Timeout Handling

By default, pending approval commands that receive no response within 5 minutes are automatically rejected, preventing the Agent from hanging indefinitely while waiting for approval. The timeout is configurable in openclaw.json:

{
  "execApprovals": {
    "timeoutMinutes": 10,
    "onTimeout": "reject"
  }
}

38.10 Log Tail and Filtering

Real-Time Log Panel

The log panel provides real-time tailing of Gateway logs (equivalent to tail -f), with all logs pushed to the browser via WebSocket.

Log Filters

[Level: ALL ▼] [Source: ALL ▼] [Keyword: ___________] [Regex ☐] [Clear]

──────────────────────────────────────────────────────────────────
09:15:33 INFO  [Gateway]   WebSocket client connected: Control UI
09:15:34 INFO  [Agent]     Session started: #4891
09:15:35 DEBUG [Router]    Routing tool call: system.run → node-a1b2
09:15:35 INFO  [Node]      Executing: system.run on node-a1b2c3d4
09:15:35 WARN  [ExecApproval] Command requires approval: rm -rf /tmp/old-cache
09:15:36 INFO  [Node]      Result received: system.run (234 bytes)
09:15:37 ERROR [Provider]  Rate limit hit: anthropic (retry in 5s)

Key Log Pattern Reference

Log Pattern Meaning Recommended Action
Rate limit hit API quota exceeded Check Key Rotation configuration
Compaction triggered Context compaction started Normal; monitor frequency
Node disconnected A node has gone offline Check node network status
ExecApproval timeout Approval timed out, auto-rejected Adjust timeout or auto-approve rules
Tool error: rate_limit Tool call throttled Reduce concurrent tool calls
Memory compaction: full Full memory compaction Normal behavior in long sessions

Log Export

Click the "Export" button to export the currently filtered log as:

38.11 Dream Diary: Memory Introspection

What Is Dream Diary?

Dream Diary is the visual introspection tool for OpenClaw's memory system. OpenClaw's long-term memory is stored as Markdown files in the ~/.openclaw/memory/ directory. The Dream Diary interface lets you:

  1. Browse the contents of all memory files
  2. Search for specific topics or keywords
  3. Edit memory content (to correct the Agent's misconceptions)
  4. Delete outdated or incorrect memory entries
  5. View the creation time and last-updated time of any memory

Memory File Structure

~/.openclaw/memory/
├── user-preferences.md      # User preferences (language/format/habits)
├── project-context.md       # Project background knowledge
├── people.md                # Contacts and relationship graph
├── recurring-tasks.md       # Context for recurring tasks
├── world-model.md           # Agent's accumulated understanding of the world
└── episodic/
    ├── 2026-04-25.md        # Episodic memories by date
    └── 2026-04-26.md

Dream Diary Use Cases

Scenario 1: Correcting Incorrect Memories

The Agent may have recorded an incorrect fact during a conversation (e.g., your work location). Find the corresponding memory file in Dream Diary, edit it directly to correct the error, and the Agent will use the updated memory in the next conversation.

Scenario 2: Proactively Injecting Knowledge

You can manually write project background into project-context.md:

## Current Project: YiteAI Navigation Site
- Tech stack: Hugo + Tailwind CSS
- Deployment: AWS + Cloudflare
- Target users: Cross-border trade practitioners
- Key priority: SEO optimization > Feature richness

After this, the Agent will reference this background information in all related conversations.

Scenario 3: Reviewing the Agent's Self-Knowledge

View world-model.md to see what understanding the Agent has accumulated about your workflow and preferences, and delete any inaccurate entries.

Git Version Control for Memory Files

Since memories are Markdown files, it is recommended to put the ~/.openclaw/ directory under git version control (see Chapter 39 for details). This way, every change to memory has a history record and can be rolled back at any time.

38.12 PWA Installation and Web Push Notifications

Installing Control UI as a PWA

The Control UI supports PWA (Progressive Web App). Once installed, it functions as a standalone application — no need to keep a browser tab open.

Desktop installation (Chrome/Edge):

1. Visit http://127.0.0.1:18789/
2. An install icon (⊕) appears on the right side of the address bar
3. Click "Install OpenClaw Control"
4. The app appears on your desktop / Launchpad

Mobile installation (Safari/iOS):

1. Visit the Gateway's LAN address (e.g., http://192.168.1.100:18789/)
2. Tap the Share button → "Add to Home Screen"
3. The icon appears on your home screen

Web Push Notification Configuration

Enable push notifications in openclaw.json:

{
  "webPush": {
    "enabled": true,
    "triggers": {
      "cronFailure": true,
      "approvalRequired": true,
      "agentError": true,
      "nodeDisconnect": true,
      "sessionComplete": false
    }
  }
}

On first activation, the browser will show a permission request. Clicking "Allow" enables push notifications. Even when the Control UI tab is closed, push notifications can still be received after PWA installation.

14-Language Localization

The Control UI has built-in support for the following languages (controlled by the ui.language field in openclaw.json):

zh-CN (Simplified Chinese)   zh-TW (Traditional Chinese)  en (English)
ja (Japanese)                ko (Korean)                   de (German)
fr (French)                  es (Spanish)                  pt (Portuguese)
ru (Russian)                 ar (Arabic)                   hi (Hindi)
vi (Vietnamese)              th (Thai)

38.13 Summary

The Control UI delivers a fully-featured Agent control center with minimal technical overhead (7KB Lit runtime): from everyday chat interactions to deep configuration management, real-time monitoring, approval workflows, and memory introspection. Mastering all the features of the Control UI means you have complete visual control over the entire OpenClaw system.

The next chapter shifts to production deployment: how to build a highly available OpenClaw Gateway production environment on an AWS ARM64 instance.

Next Chapter: Chapter 39 — Production Deployment: AWS ARM64 + systemd + Tailscale Reference Architecture

Rate this chapter
4.6  / 5  (3 ratings)

💬 Comments