第 38 章

Control UI 深度：配置编辑、实时日志、审批管理与 Dream Diary

第38章：Control UI 深度：配置编辑、实时日志、审批管理与 Dream Diary

概述

Control UI 是 OpenClaw 的神经中枢可视化界面。它不只是一个聊天窗口——它是整个 Gateway 的控制台、配置中心、监控大屏和记忆内省工具的集合体。本章对 Control UI 的每一个功能模块进行深度解析，帮助你充分发挥这个单页应用的全部潜力。

访问地址：http://127.0.0.1:18789/（本地运行时）

38.1 技术架构：Vite + Lit，轻量框架的选择逻辑

技术栈概述

Control UI 采用以下技术构建：

构建工具: Vite 5.x
UI 框架:  Lit 3.x (Web Components)
通信层:   原生 WebSocket（直连 Gateway）
样式:     CSS Custom Properties（CSS 变量主题化）
PWA:      Workbox + Web App Manifest
本地化:   14 种语言（内置 i18n）

为什么选择 Lit 而非 React/Vue？

这是一个刻意的权衡决策：

体积优势

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

Control UI 需要在低性能设备（树莓派本地运行、内网旧服务器）上流畅运行，7KB 的运行时几乎没有启动开销。

Web Components 天然隔离

Lit 基于原生 Web Components 规范，每个组件是独立的自定义 HTML 元素，天然隔离 CSS 作用域，不存在样式污染问题。这对于一个需要动态插入来自 Agent 的 HTML 内容（Tool 调用卡片、Canvas 渲染）的界面至关重要。

WebSocket 直连架构

Control UI 不通过 REST API 与 Gateway 通信，而是建立一条持久 WebSocket 连接，所有状态更新（日志、工具调用结果、Node 状态变更）都通过这条连接实时推送，无需轮询。这与 Lit 的响应式属性系统天然契合——WebSocket 消息触发属性更新，Lit 高效地仅更新受影响的 DOM 节点。

38.2 聊天界面与基本交互

消息发送与接收

Control UI 的主界面是一个流式聊天界面，支持：

Markdown 渲染：Agent 回复实时流式渲染，支持代码块高亮（Prism.js）、数学公式（KaTeX）
文件附件：拖放图片/文档到聊天框，直接发送给 Agent
@提及 Node：在消息中输入 @node-name 可指定 Agent 优先使用特定节点的能力
快捷命令：输入 / 触发命令补全（/clear、/compact、/status、/model）

消息历史导航

键盘快捷键：
  ↑ / ↓        在输入框中回溯历史消息
  Ctrl+Enter   换行（不发送）
  Enter        发送消息
  Esc          取消当前输入，聚焦到消息列表

Think Mode 深度思维显示

当 Agent 启用思维（Thinking）模式时，Control UI 会以可折叠的 <details> 块显示内部推理过程：

<details class="thinking-block">
  <summary>Agent 正在思考... (1,247 tokens)</summary>
  <!-- 折叠展开可见完整思维链 -->
</details>

38.3 WebRTC 语音 Talk Mode

功能说明

Talk Mode 将 Control UI 变成一个语音交互终端。用户通过麦克风说话，实时转写，Agent 的回复也通过 TTS 语音播报。

启动 Talk Mode

点击聊天界面右下角的麦克风图标，或使用快捷键 Ctrl+Shift+T。

Talk Mode 工作流程：
用户说话 →
  Browser 捕获麦克风音频 (WebRTC getUserMedia) →
  实时 VAD 检测停顿（Voice Activity Detection）→
  音频流通过 WebSocket 发送到 Gateway →
  Gateway 调用 STT（语音转文字）→
  文字发送给 Agent →
  Agent 生成回复 →
  Gateway 调用 TTS →
  音频流返回 Browser →
  浏览器播放语音

Talk Mode 配置

在 openclaw.json 中配置：

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

使用技巧

说"停止"或"结束"：触发 Agent 中断当前生成
说"重复"：重新播报上一条 Agent 回复
背景噪音环境：在设置中调高 silenceThresholdMs（如 1200ms）

38.4 Tool 调用流式输出卡片

当 Agent 调用工具时，Control UI 以实时更新的卡片方式展示工具调用的完整生命周期。

卡片结构解析

┌─────────────────────────────────────────────────────┐
│ ⚙ system.run                           [node-a1b2] │
│ ─────────────────────────────────────────────────── │
│ 输入:                                               │
│   command: "df -h /data"                            │
│ ─────────────────────────────────────────────────── │
│ 输出: (流式实时更新)                                │
│   Filesystem  Size  Used Avail Use% Mounted on      │
│   /dev/sda1   465G  234G  208G  53% /data           │
│ ─────────────────────────────────────────────────── │
│ 状态: ✓ 成功  耗时: 0.34s  Token: +127             │
└─────────────────────────────────────────────────────┘

卡片状态含义

状态图标	含义
`⟳` 旋转	工具调用进行中
`✓` 绿色	执行成功
`✕` 红色	执行失败（含错误详情）
`⏸` 暂停	等待审批（execApprovals）
`⚡` 闪电	Sub-Agent 并行执行

并行工具调用展示

当 Agent 并行调用多个工具时，卡片以网格布局展示：

[system.run @ Pi]    [camera.snap @ iPhone]
    ✓ 完成               ⟳ 进行中
[contacts.search @ Android]
    ✓ 完成

38.5 双模式配置编辑器

Control UI 内置的配置编辑器支持两种工作模式，随时切换。

表单模式（Form Mode）

表单模式将 openclaw.json 的关键字段解构为直观的 UI 控件：

模型配置
  主模型:      [下拉菜单] anthropic/claude-sonnet-4-6
  备用模型:    [下拉菜单] openai/gpt-4.1-mini
  最大Token:   [滑块] 8192  ────────────│────── 200k

思维配置
  思维模式:    [开关] ON
  思维预算:    [数字输入] 10000 tokens

Skills 管理
  [列表] ☑ web-search  ☑ code-exec  ☐ email  ☑ calendar

日志级别:      [下拉] info

表单模式适合日常调整，无需了解 JSON 结构，误操作风险低。

原始 JSON 模式（Raw JSON Mode）

点击右上角的 { } 按钮切换到 JSON 编辑器（Monaco Editor，与 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 模式支持：

语法高亮与实时校验
JSON Schema 自动补全
Diff 视图（对比修改前后）
格式化（Shift+Alt+F）

配置保存与热重载

点击"保存"后，Control UI 将修改后的配置通过 WebSocket 发送给 Gateway。Gateway 在不重启的情况下热重载绝大多数配置项（模型切换、日志级别调整、Skills 增删等），少数底层配置（端口、TLS 证书）需要重启生效。

38.6 Session 覆盖功能

Session 覆盖（Session Override）允许你在不修改全局配置的情况下，对当前会话的模型行为进行临时调整。会话结束后自动恢复到全局配置。

可覆盖的参数

参数	说明	示例
`model`	覆盖当前会话使用的模型	`anthropic/claude-opus-4-6`
`thinkingMode`	思维深度（none/low/medium/high）	`high`
`maxTokens`	单次响应最大 Token 数	`16000`
`verbosity`	响应详细程度（concise/normal/detailed）	`detailed`
`language`	响应语言偏好	`en`

使用方式

在聊天界面右上角点击"会话设置"图标，弹出覆盖面板：

当前会话临时覆盖
  模型:      [anthropic/claude-opus-4-6  ▼]  (仅此会话)
  思维模式:  [high                        ▼]
  最大Token: [16000                          ]
  详细程度:  [detailed                    ▼]

  [应用] [重置为全局默认]

典型使用场景：

在当前会话中临时切换到 opus 模型处理一个复杂任务，任务完成后自动恢复到默认的 sonnet
在调试时临时开启 thinkingMode: high 查看 Agent 推理过程
在需要精简输出时临时设置 verbosity: concise

38.7 Cron 任务可视化管理

Control UI 的 Cron 面板提供完整的定时任务生命周期管理。

创建 Cron 任务

在 Cron 面板点击"+ 新建任务"，填写：

任务名称:    每日系统健康检查
Cron 表达式: 0 9 * * *          (每天上午9点)
执行提示词:  "检查所有 Node 的状态，报告异常，检查磁盘使用率"
超时:        5 分钟
失败重试:    3 次，间隔 5 分钟
通知:        失败时推送 Web Push

支持的 Cron 格式（6位，含秒）：

秒 分 时 日 月 周
0  0  *  *  *  *    每小时整点
0  */30 * * * *     每30分钟
0  9   *  *  1-5 *  工作日上午9点
0  0   0  *  *  *   每天午夜

任务列表与状态监控

任务名称               状态    上次运行          下次运行
每日系统健康检查        ✓ 正常  今天 09:00:05     明天 09:00:00
每小时磁盘检查          ✓ 正常  09:30:02          10:00:00
每周报告生成            ✕ 失败  本周一 08:59:58   下周一 09:00:00
备份 ~/.openclaw        ✓ 正常  昨天 02:00:01     今天 02:00:00

任务历史与执行记录

点击任务名称展开执行历史：

执行历史（最近20次）
  2026-04-26 09:00:05  ✓ 成功  耗时 45s  [查看详情]
  2026-04-25 09:00:03  ✓ 成功  耗时 38s  [查看详情]
  2026-04-24 09:00:01  ✕ 失败  耗时 300s [查看错误]

38.8 Node 能力检查与设备管理

Node 列表面板

在"Nodes"标签页，可以看到所有已连接节点的实时状态：

节点名称                  平台      状态      能力数  延迟
Hexin's iPhone 15 Pro    iOS       ● 在线    5      12ms
Pi Node - Living Room    Headless  ● 在线    2      8ms
Hexin's MacBook Pro      macOS     ○ 离线    6      —

能力检查（Capability Inspector）

点击任意节点展开能力详情：

Pi Node - Living Room (node-a1b2c3d4)
平台: Headless | 已连接: 2h 15m | 延迟: 8ms

已声明能力:
  ✓ system.run      [测试] [撤销]
  ✓ system.which    [测试] [撤销]

点击"测试"对该能力进行实时测试调用。

手动测试能力

点击"测试"按钮后，弹出测试面板：

测试 system.run @ Pi Node - Living Room

输入参数（JSON）:
{
  "command": "uptime"
}

[执行测试]

结果:
  09:15:42 up 2:15,  1 user,  load average: 0.08, 0.05, 0.01
  耗时: 0.21s  状态: ✓ 成功

38.9 执行审批队列管理

当 execApprovals 机制触发时，待审批的命令会出现在"审批"面板中。

审批面板界面

待审批执行（3 项）
───────────────────────────────────────────────────────
[!] rm -rf /tmp/old-cache          @ Pi Node    09:15:33
    来源 Agent: 会话 #4891
    上下文: "清理旧的缓存文件以释放磁盘空间"
    [批准] [拒绝] [查看完整上下文]

[!] sudo apt upgrade -y            @ macOS Node  09:15:41
    来源 Agent: Cron 任务"每周系统更新"
    上下文: "执行计划的系统软件包更新"
    [批准] [拒绝] [查看完整上下文]

[!] curl -o /tmp/script.sh https://example.com/install.sh  @ Pi Node  09:16:02
    来源 Agent: 会话 #4891
    [批准] [拒绝] [查看完整上下文]

批量审批与安全策略

批量批准：勾选多项后点击"全部批准"（谨慎使用）
永久规则：点击"批准并记住"，将命令模式加入自动审批列表
拒绝理由：拒绝时可输入理由，Agent 会收到拒绝消息并调整策略

审批超时处理

默认情况下，待审批命令超过 5 分钟无响应会自动拒绝，防止 Agent 因等待审批而长时间挂起。超时时间可在 openclaw.json 中配置：

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

38.10 日志拖尾与过滤

实时日志面板

日志面板提供 Gateway 日志的实时拖尾（tail -f 效果），所有日志通过 WebSocket 推送到浏览器。

日志过滤器

[级别: ALL ▼] [来源: ALL ▼] [关键词: ___________] [正则 ☐] [清除]

──────────────────────────────────────────────────────────────────
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)

关键日志模式解析

日志模式	含义	建议操作
`Rate limit hit`	API 配额超限	检查 Key Rotation 配置
`Compaction triggered`	上下文压缩启动	正常，可关注频率
`Node disconnected`	节点断线	检查节点网络状态
`ExecApproval timeout`	审批超时被拒绝	调整超时时间或自动审批规则
`Tool error: rate_limit`	工具调用限流	减少并发工具调用
`Memory compaction: full`	全量记忆压缩	正常的长会话行为

日志导出

点击"导出"按钮，可将当前过滤后的日志导出为：

openclaw-gateway.log（纯文本）
openclaw-gateway.json（结构化 JSON）
openclaw-gateway.csv（含时间戳、级别、来源列）

38.11 Dream Diary：记忆内省

什么是 Dream Diary？

Dream Diary 是 OpenClaw 记忆系统的可视化内省工具。OpenClaw 的长期记忆以 Markdown 文件形式存储在 ~/.openclaw/memory/ 目录中。Dream Diary 界面允许你：

浏览所有记忆文件的内容
搜索特定主题或关键词
编辑记忆内容（纠正 Agent 的误解）
删除过时或错误的记忆条目
查看记忆的创建时间和最后更新时间

记忆文件结构

~/.openclaw/memory/
├── user-preferences.md      # 用户偏好（语言/格式/习惯）
├── project-context.md       # 项目背景知识
├── people.md                # 联系人和关系图
├── recurring-tasks.md       # 周期性任务的上下文
├── world-model.md           # Agent 对世界的理解积累
└── episodic/
    ├── 2026-04-25.md        # 按日期的情节记忆
    └── 2026-04-26.md

Dream Diary 使用场景

场景一：纠正错误记忆

Agent 可能在某次对话中记录了一个错误的事实（如你的工作地点）。在 Dream Diary 中找到对应记忆文件，直接编辑修正，Agent 下次对话时会读取更新后的记忆。

场景二：主动注入知识

你可以在 project-context.md 中手动写入项目背景：

## 当前项目：YiteAI 导航站
- 技术栈: Hugo + Tailwind CSS
- 部署: AWS + Cloudflare
- 目标用户: 出海贸易从业者
- 关键优先级: SEO 优化 > 功能丰富度

之后 Agent 在所有相关对话中都会参考这些背景信息。

场景三：审查 Agent 的自我认知

查看 world-model.md 了解 Agent 积累了哪些关于你工作流程和偏好的理解，删除不准确的条目。

记忆文件的 git 版本控制

由于记忆是 Markdown 文件，建议对 ~/.openclaw/ 目录进行 git 版本控制（详见第39章），这样记忆的每次变更都有历史记录，可以随时回滚。

38.12 PWA 安装与 Web Push 通知

安装 Control UI 为 PWA

Control UI 支持 PWA（Progressive Web App），安装后可作为独立应用使用，无需保持浏览器标签页打开。

桌面端安装（Chrome/Edge）：

1. 访问 http://127.0.0.1:18789/
2. 地址栏右侧出现安装图标 (⊕)
3. 点击"安装 OpenClaw Control"
4. 应用出现在桌面/启动台

移动端安装（Safari/iOS）：

1. 访问 Gateway 的局域网地址（如 http://192.168.1.100:18789/）
2. 点击分享按钮 → "添加到主屏幕"
3. 图标出现在主屏幕

Web Push 通知配置

在 openclaw.json 中启用 Push 通知：

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

首次启用时，浏览器会弹出权限请求，点击"允许"后即可接收推送。即使 Control UI 标签页关闭，PWA 安装后仍可接收通知。

14 种语言本地化

Control UI 内置支持以下语言（openclaw.json 中的 ui.language 字段控制）：

zh-CN（简体中文）  zh-TW（繁体中文）  en（英语）
ja（日语）         ko（韩语）          de（德语）
fr（法语）         es（西班牙语）       pt（葡萄牙语）
ru（俄语）         ar（阿拉伯语）       hi（印地语）
vi（越南语）       th（泰语）

38.13 小结

Control UI 以极小的技术负担（7KB Lit 运行时）实现了一个功能完整的 Agent 控制中枢：从日常的聊天交互，到深度的配置管理、实时监控、审批流程和记忆内省。掌握 Control UI 的全部功能，意味着你对 OpenClaw 系统有了完整的可视化掌控能力。

下一章将转向生产部署：如何在 AWS ARM64 实例上搭建一个高可用的 OpenClaw Gateway 生产环境。

下一章：第39章 — 生产部署：AWS ARM64 + systemd + Tailscale 参考架构

本章评分

4.6 / 5 (3 评分)