OpenClaw WebUI Chat 工作流程与核心组件解析

整体架构

OpenClaw WebUI 是一个基于 Web Components 的现代前端应用，提供了直观的聊天界面来与 OpenClaw Agent 进行交互。

主要程序名称

前端程序

1. control-ui/index.html - WebUI 主页面
2. control-ui/assets/index-BeKTXH1m.js - 打包后的前端核心代码
3. control-ui/assets/index-DWhx-9JL.css - 前端样式文件

后端服务

1. Gateway 服务 - 运行在端口 18789，提供 API 端点
2. Agent 服务 - 处理代理逻辑
3. Session 服务 - 管理会话状态

Chat 工作流程

1. 初始化阶段

• 页面加载：用户访问 WebUI 地址（通常是 http://localhost:18789）
• WebSocket 连接：前端与 Gateway 建立 WebSocket 连接，用于实时通信
• 会话加载：前端加载默认会话或上次活动的会话
• 历史记录获取：调用 chat.history API 端点获取历史消息

2. 消息发送流程

1. 用户输入：用户在聊天输入框中输入消息
2. 消息处理：
   • 前端验证输入内容
   • 显示'正在发送'状态
   • 生成唯一的 runId 标识本次对话
3. API 调用：
   • 前端调用 chat.send API 端点
   • 发送数据包括：会话密钥、消息内容、幂等性密钥
   • 支持附件（如图片）上传
4. 后端处理：
   • Gateway 接收请求并路由到相应的 Agent
   • Agent 分析消息内容
   • 可能调用工具（如 web_search）获取信息
   • 生成回复内容
5. 消息接收：
   • 后端通过 WebSocket 流式返回回复
   • 前端实时显示回复内容
   • 支持工具调用结果的展示

3. 会话管理

• 会话选择：用户可以在下拉菜单中选择不同的会话
• 会话切换：切换会话时会加载对应会话的历史记录
• 会话刷新：用户可以手动刷新聊天数据

4. 工具调用流程

1. 工具检测：Agent 分析用户请求，确定是否需要调用工具
2. 工具调用：
   • 前端显示工具调用状态
   • 后端执行工具操作（如搜索）
3. 结果处理：
   • 工具执行结果返回给 Agent
   • Agent 分析结果并生成回复
   • 前端显示工具调用结果和 Agent 回复

5. 界面交互

• 主题切换：支持系统、浅色、深色三种主题
• 思考模式：可切换显示/隐藏 Agent 的思考过程
• 专注模式：可切换显示/隐藏侧边栏和页面标题
• 消息滚动：新消息自动滚动到底部
• 加载状态：显示各种操作的加载状态

核心 API 端点

1. chat.send - 发送聊天消息
   • 参数：sessionKey, message, idempotencyKey, attachments
   • 返回：Agent 回复
2. chat.history - 获取聊天历史
   • 参数：sessionKey, limit
   • 返回：历史消息列表
3. status - 获取系统状态
   • 返回：系统运行状态
4. health - 获取系统健康状态
   • 返回：系统健康信息

技术特点

1. 流式响应：支持模型回复的流式展示，提升用户体验
2. 实时通信：使用 WebSocket 实现实时消息传递
3. 模块化设计：前端代码采用模块化结构，易于维护
4. 响应式布局：适配不同屏幕尺寸
5. 丰富的交互：支持表情、图片、工具调用等多种交互方式

工作流程图

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐  
│   用户界面  │     │  前端处理   │     │ Gateway 服务│     │  Agent 服务  │  
└─────┬───────┘     └─────┬───────┘     └─────┬───────┘     └─────┬───────┘  
      │                  │                  │                  │  
      │ 输入消息         │                  │                  │  
      ├─────────────────>│                  │                  │  
      │                  │ 验证输入         │                  │  
      │                  │ 生成 runId       │                  │  
      │                  │                  │                  │  
      │                  │ 调用 chat.send API│                  │  
      │                  ├─────────────────>│                  │  
      │                  │                  │ 路由请求         │  
      │                  │                  ├─────────────────>│  
      │                  │                  │                  │  
      │                  │                  │                  │  处理消息  
      │                  │                  │                  ├─────────┐  
      │                  │                  │                  │         │  
      │                  │                  │                  │ 调用工具  
      │                  │                  │                  │         │  
      │                  │                  │                  │         │  
      │                  │                  │                  │<────────┘  
      │                  │                  │                  │  
      │                  │                  │                  │ 生成回复  
      │                  │                  │                  │  
      │                  │                  │<─────────────────┘  
      │                  │<─────────────────┘  
      │                  │  
      │                  │ 流式返回回复  
      │                  │  
      │<─────────────────┘  
      │  
      │ 显示回复  
      │  
┌─────┴───────┐  
│   用户界面  │  
└─────────────┘