〖OpenClaw系列〗Control UI 与 WebChat 使用指南

上篇回顾

上一篇《[Gateway 网关深度剖析](./第05篇-Gateway 网关深度剖析.md)》，我们把 Gateway 从按下回车到处理请求的完整链路拆了个干净。现在你应该能看懂启动日志的每个阶段，也知道消息是怎么从 Telegram 进来、经过 Agent 处理、再回复回去的。

但 Gateway 跑起来之后，除了看日志，还有什么方式能观察它的运行状态？这篇要讲的 Control UI 就是答案——它是 Gateway 自带的 Web 管理界面，让你用浏览器就能监控、管理、甚至直接和 AI 对话。

本文定位：Control UI 和 WebChat 的完整使用指南。读完这篇，你能熟练使用 Control UI 进行调试监控，明白 WebChat 和 Telegram 聊天的区别，知道在什么场景下用哪个界面更合适。

---

一、Control UI 是什么

Control UI 是 OpenClaw Gateway 内置的 Web 管理界面。当你启动 Gateway 后，除了通过 Telegram、WhatsApp 等渠道与 AI 对话，还可以直接打开浏览器访问 Control UI。

Control UI 能做什么

功能模块	用途
仪表盘	查看 Gateway 运行状态、活跃会话数、已连接渠道
会话管理	查看所有会话列表、搜索特定会话、清理历史记录
Agent 配置	快速查看当前 Agent 配置（只读）
日志查看	实时查看 Gateway 运行日志，支持级别筛选
WebChat	在浏览器里直接和 AI 对话
系统设置	手动触发配置热重载、查看系统信息

Control UI vs 渠道聊天：核心区别

这张图对比了 Control UI 和 Telegram 渠道的核心差异。左边蓝色区域是 Control UI 的特性，右边绿色区域是 Telegram 渠道的特性。

关键区别有三点：

1. 访问方式：Control UI 打开浏览器就能用，不需要安装任何 App；Telegram 需要用户安装客户端
2. 功能范围：Control UI 能看到全局状态（所有会话、系统日志），Telegram 只能看到当前对话
3. 使用场景：Control UI 适合开发者调试和管理，Telegram 适合终端用户日常使用

对应第5篇：Gateway 启动后，主进程会绑定端口（默认 18789），Control UI 就运行在这个端口上。详见第5篇「阶段3：端口绑定与网络初始化」。

---

二、如何访问 Control UI

启动 Gateway 后自动可用

当你执行 openclaw gateway start 看到 Gateway ready 后，Control UI 就已经可访问了：

[INFO] ══════════════════════════════════════
[INFO] Gateway ready on http://localhost:18789
[INFO] Control UI: http://localhost:18789
[INFO] ══════════════════════════════════════

打开浏览器，访问 http://localhost:18789，就能看到 Control UI 界面。

配置了认证怎么办

如果你的 openclaw.json 配置了 gateway.auth，访问 Control UI 时需要登录：

{
  gateway: {
    auth: {
      type: "basic",
      username: "admin",
      password: "${ADMIN_PASSWORD}"
    }
  }
}

浏览器会弹出认证对话框，输入配置的用户名密码即可。

远程访问 Control UI

默认情况下，Control UI 只绑定在 127.0.0.1（本机）。如果你想从其他设备访问：

方式1：修改 bind 配置

{
  gateway: {
    bind: "network",  // 绑定到 0.0.0.0，局域网可访问
    port: 18789
  }
}

方式2：使用 SSH 隧道（推荐，更安全）

# 在本地机器执行，将远程 18789 端口映射到本地
ssh -L 18789:localhost:18789 user@remote-server
# 然后本地访问 http://localhost:18789

安全提示：将 Control UI 暴露到公网时，务必启用 gateway.auth 认证，否则任何人都能访问你的 Gateway。

---

三、Control UI 功能详解

这张图展示了 Control UI 的界面布局。左侧深蓝色导航栏是功能入口，右侧四个彩色区域是主要功能模块。下面逐个介绍。

仪表盘（Dashboard）

仪表盘是 Control UI 的首页，显示 Gateway 的核心运行指标：

指标	说明
System Status	系统状态：Running / Stopped / Error
Active Sessions	当前活跃会话数
Connected Channels	已连接的渠道数量
Uptime	Gateway 运行时长

仪表盘数据每秒自动刷新，一眼就能看出 Gateway 是否健康运行。

会话管理（Sessions）

会话管理是 Control UI 最实用的功能之一。它显示所有活跃会话的列表：

列名	说明
Session ID	会话唯一标识，格式为 channel:peerId
Channel	所属渠道（Telegram/WhatsApp 等）
Messages	该会话的消息数量
Last Active	最后活跃时间

你可以在这里做这些事：

1. 搜索会话：按 Session ID 或渠道筛选
2. 查看详情：点击会话 ID 查看完整对话历史
3. 清理会话：删除特定会话或批量清理旧会话
4. 导出记录：将会话内容导出为 JSON/文本

# 等效命令行操作
openclaw session list              # 列出所有会话
openclaw session stats             # 查看会话统计
openclaw session clear tg:12345    # 清理特定会话

Agent 配置查看

这个页面以只读方式展示当前加载的 Agent 配置：

• 模型信息：当前使用的模型、fallback 配置
• 工具白名单：允许使用的 Skill 列表
• 心跳设置：自动提醒间隔
• 工作区路径：SOUL.md 位置

注意：Control UI 只能查看配置，修改配置需要编辑 openclaw.json 文件（支持热重载）。

日志查看（Logs）

实时日志流是调试 Gateway 问题的利器：

[INFO] Gateway ready on :18789
[INFO] Telegram channel connected
[DEBUG] Session tg:12345 created
[INFO] Message processed in 1.2s

日志级别筛选：

• ERROR：只显示错误
• WARN：显示警告和错误
• INFO：常规信息（默认）
• DEBUG：详细调试信息

实用技巧：

1. 遇到问题时，先把日志级别调到 DEBUG，复现问题后查看详细日志
2. 使用浏览器的查找功能（Ctrl+F）搜索关键词如 error、timeout
3. 日志支持自动滚动，保持开启状态可实时监控

系统设置

系统设置页面提供管理操作：

功能	说明
Reload Config	手动触发配置热重载（等效于 openclaw gateway reload）
System Info	显示 Gateway 版本、Node.js 版本、运行环境
Health Check	手动执行健康检查

---

四、WebChat：浏览器里的 AI 对话

什么是 WebChat

WebChat 是 Control UI 内置的聊天界面。它让你不需要安装 Telegram、不需要配置渠道，直接用浏览器就能和 AI 对话。

这张图展示了 WebChat 的界面。中间白色区域是聊天窗口，包含消息历史、输入框和发送按钮。左侧列出了 WebChat 的核心特性。

如何开启 WebChat

WebChat 默认就是启用的。只要 Gateway 在运行，访问 http://localhost:18789 就能在左侧导航看到 WebChat 入口。

点击后进入独立的聊天界面，特性包括：

特性	说明
Real-time Chat	WebSocket 流式传输，AI 回复实时显示
File Upload	支持拖拽上传文件，AI 可以读取分析
Code Highlight	代码块自动语法高亮
Session Persist	对话上下文自动保存，刷新页面不丢失

WebChat 的消息去哪了

WebChat 创建的会话遵循和其他渠道一样的规则：

• 会话 ID：格式为 webchat:anonymous 或 webchat:{userId}（如果配置了认证）
• 上下文管理：受 session.dmScope 和 session.reset 配置控制
• 持久化：会话数据保存在 ~/.openclaw/sessions/ 目录

这意味着：

1. WebChat 和 Telegram 使用相同 Agent 时，AI 助手的行为和能力完全一致
2. 会话重置策略对 WebChat 同样生效
3. 你可以在 Control UI 的「会话管理」里看到 WebChat 会话

WebChat vs 渠道聊天的区别

对比项	WebChat	Telegram/WhatsApp
使用门槛	打开浏览器即可	需要安装 App、配置 Bot
文件传输	拖拽上传	原生 App 体验更好
通知方式	浏览器推送	系统级推送
移动体验	响应式设计，可用	原生 App，体验更佳
多设备同步	同一浏览器会话共享	多设备登录 Telegram 同步
适用场景	开发调试、临时使用	日常对话、生产使用

一句话总结：WebChat 是「开箱即用」的便捷选择，渠道聊天是「正式部署」的推荐方案。

---

五、使用场景推荐

场景1：开发调试（首选 Control UI）

开发新 Skill 或调试 Agent 行为时，Control UI 是最高效的工具：

1. 开两个标签页：一个放 WebChat 测试对话，一个放 Logs 查看实时日志
2. 快速迭代：修改代码 → 热重载 → WebChat 测试 → 看日志验证
3. 问题定位：出现异常时，Logs 页面搜索错误信息，Sessions 页面查看会话状态

场景2：管理监控（Control UI）

Gateway 长期运行后，用 Control UI 做日常巡检：

1. Dashboard 看状态：确认 Gateway 运行正常、渠道连接稳定
2. Sessions 看增长：观察活跃会话数趋势，判断用户量变化
3. 定期清理：批量清理旧会话，释放磁盘空间

场景3：临时聊天（WebChat）

临时想测试一个配置，不想打开 Telegram：

# 1分钟快速测试
openclaw gateway start
# 浏览器打开 http://localhost:18789
# 点击 WebChat 直接开聊

或者给同事演示 OpenClaw 功能时，WebChat 是最快的方式——对方不需要安装任何东西。

场景4：生产环境用户接入（渠道）

正式给用户使用时，推荐配置 Telegram/WhatsApp 等渠道：

• 用户已有这些 App，无需额外安装
• 系统级通知，不会错过消息
• 移动端体验更好

---

六、踩坑

坑1：Control UI 无法访问

现象：浏览器访问 http://localhost:18789 显示「无法连接」

排查步骤：

# 1. 确认 Gateway 已启动
openclaw gateway status

# 2. 检查端口绑定
lsof -i :18789

# 3. 检查 bind 配置
openclaw config get gateway.bind
# 如果是 "loopback"，只能本机访问
# 如果是 "network"，检查防火墙

# 4. 查看 Gateway 日志找错误
openclaw logs

常见原因：

• Gateway 未启动或启动失败
• 端口被其他程序占用
• 配置了 gateway.bind: "loopback" 但尝试从其他设备访问

坑2：WebChat 消息发送失败

现象：WebChat 界面能打开，但发送消息没反应

排查：

1. 检查 Gateway 状态：Dashboard 显示 Running 才算正常
2. 检查 Agent 配置：Agent 配置错误会导致消息无法处理
3. 查看浏览器控制台：F12 打开 DevTools，看 Console 是否有 WebSocket 错误

常见原因：

• Agent 的模型配置错误（如 API Key 无效）
• WebSocket 连接被代理中断

坑3：会话列表为空

现象：Sessions 页面显示「暂无会话」

排查：

# 确认会话目录存在
ls -la ~/.openclaw/sessions/

# 检查权限
openclaw doctor

常见原因：

• Gateway 刚启动，确实没有会话
• 会话目录权限问题
• session.dmScope 配置导致会话 ID 格式不一致

坑4：热重载按钮点了没反应

现象：点击「Reload Config」后，配置没有更新

排查：

# 1. 检查配置文件语法
openclaw doctor

# 2. 查看日志确认重载是否触发
openclaw logs | grep "Hot reload"

# 3. 手动命令行重载测试
openclaw gateway reload

常见原因：

• 配置文件语法错误（JSON5 格式问题）
• gateway.reload.mode 设为 off
• 修改的是 $include 子文件但路径错误

---

七、常见问题（FAQ）

Q：Control UI 支持多用户同时访问吗？

A：支持。Control UI 是只读界面（除了手动重载配置），多个用户同时查看不会冲突。但如果多人同时点击「Reload Config」，最后一次点击生效。

Q：WebChat 的对话记录会保存吗？

A：会。WebChat 的对话和其他渠道一样持久化到磁盘，重启 Gateway 后对话历史还在。除非你手动清理会话或触发了 session.reset。

Q：Control UI 可以修改配置吗？

A：目前 Control UI 是只读的，不能直接修改配置。修改配置需要编辑 ~/.openclaw/openclaw.json 文件，然后手动触发热重载。

Q：WebChat 支持语音输入吗？

A：浏览器原生的语音输入（如 macOS 的听写功能）可以工作，但 OpenClaw 暂时没有内置语音转文字功能。需要语音对话可以用 Talk Mode（第39篇会介绍）。

Q：如何在 WebChat 切换 Agent？

A：WebChat 使用默认 Agent（agents.defaults）。如果想测试其他 Agent，需要修改配置将目标 Agent 设为默认，或使用渠道特定的路由规则。

---

总结

Control UI 和 WebChat 是 Gateway 的重要组成部分：

功能	核心用途	推荐场景
Dashboard	查看运行状态	日常巡检、快速健康检查
Sessions	管理用户会话	问题排查、数据清理
Logs	实时日志查看	调试排错、问题定位
WebChat	浏览器内聊天	开发测试、临时使用

再看一遍三张图：

• Control UI 架构图（第三章）：六大功能模块的位置和关系
• WebChat 界面图（第四章）：浏览器聊天的交互方式
• 对比图（第一章）：Control UI 和 Telegram 的适用场景差异

一句话记住：Control UI 是开发者的调试利器，渠道聊天是用户的日常工具。两者共享同一个 Gateway、同一个 Agent 配置、同一个会话系统——只是交互方式不同。

---

下一篇预告

〖OpenClaw系列〗openclaw doctor 诊断工具详解

Gateway 出问题时，除了看日志，还有一个专门的诊断工具——openclaw doctor。下一篇详细介绍这个工具的每个检查项、常见问题的自动修复能力，以及如何用它快速定位配置错误。

本文是系列第6篇，前序文章：[第5篇：Gateway 网关深度剖析](./第05篇-Gateway 网关深度剖析.md) | [第3篇：配置文件详解](./第03篇-配置文件 openclaw.json 详解.md)

---

📌 觉得有用？点个「在看」 👇
👨‍💻 关注「敏叔侃技术」，每周更新 OpenClaw 实战干货
⭐ 收藏这篇文章，遇到 Control UI 访问问题随时翻出来排查