整体架构
OpenClaw WebUI 是一个基于 Web Components 构建的现代前端应用,提供了直观的聊天界面来与 OpenClaw Agent 进行交互。整个系统采用前后端分离的架构设计,通过 WebSocket 实现实时通信。
主要程序名称
前端程序
- control-ui/index.html:WebUI 主页面入口
- control-ui/assets/index-BeKTXH1m.js:打包后的前端核心逻辑
- control-ui/assets/index-DWhx-9JL.css:样式文件
后端服务
- Gateway 服务:运行在端口 18789,负责 API 路由与请求分发
- Agent 服务:处理代理核心逻辑与业务决策
- Session 服务:管理会话状态与上下文
Chat 工作流程
1. 初始化阶段
当用户访问 WebUI 地址(通常是 http://localhost:18789)时,流程开始启动。首先建立 WebSocket 连接,确保前端与 Gateway 之间能进行实时通信。随后前端会加载默认会话或恢复上次活动的会话,并调用 chat.history API 端点获取历史消息记录,为对话做好准备。
2. 消息发送流程
用户在输入框中输入内容后,前端会先验证输入的有效性,并显示'正在发送'的状态提示。系统会为本次对话生成唯一的 runId 标识。接着调用 chat.send API 端点,数据载荷包含会话密钥、消息内容以及幂等性密钥,同时支持图片等附件上传。
后端收到请求后,Gateway 将其路由到相应的 Agent 实例。Agent 分析消息内容,必要时调用外部工具(如 web_search)获取信息,最终生成回复。回复内容会通过 WebSocket 流式返回给前端,用户可实时看到打字效果,同时支持展示工具调用的中间结果。
3. 会话管理
用户可以通过下拉菜单切换不同的会话,切换时会触发对应历史记录的重载。如果需要更新当前聊天数据,也可以手动执行刷新操作。
4. 工具调用流程
当 Agent 分析认为需要借助外部能力时,会进入工具调用流程。前端会同步显示工具调用状态,后端则执行具体操作(例如搜索)。执行结果返回给 Agent 进行分析,最终生成包含工具结果的完整回复并推送到前端展示。
5. 界面交互特性
- 主题切换:支持系统、浅色、深色三种模式
- 思考模式:可控制是否显示 Agent 的思考过程
- 专注模式:隐藏侧边栏和页面标题以聚焦内容
- 消息滚动:新消息自动滚动到底部
- 加载状态:各类操作均有明确的加载反馈
核心 API 端点
-
chat.send - 发送聊天消息
- 参数:sessionKey, message, idempotencyKey, attachments
- 返回:Agent 回复内容
-
chat.history - 获取聊天历史
- 参数:sessionKey, limit
- 返回:历史消息列表
-
status - 获取系统状态
- 返回:系统运行状态信息
-
health - 获取系统健康状态
- 返回:系统健康检查信息
技术特点
- :支持模型回复的流式展示,显著提升用户体验

