14.5 WebChat

WebChat 是 OpenClaw macOS 菜单栏应用中嵌入的原生 SwiftUI 聊天界面。它连接到网关,默认使用所选代理的主会话(带会话切换器可切换到其他会话)。

连接模式

• 本地模式:直接连接到本地网关 WebSocket
• 远程模式:通过 SSH 转发网关控制端口,并使用该隧道作为数据平面

启动和调试

启动方式

• 手动:Lobster 菜单 → "打开聊天"
• 自动打开(用于测试):

  dist/OpenClaw.app/Contents/MacOS/OpenClaw --webchat

查看日志

./scripts/clawlog.sh

子系统:bot.molt,类别:WebChatSwiftUI

工作原理

数据平面

WebChat 使用网关 WebSocket 方法和事件:

• 方法:
  • chat.history - 获取聊天历史
  • chat.send - 发送消息
  • chat.abort - 中止当前请求
  • chat.inject - 注入消息
• 事件:
  • chat - 聊天消息更新
  • agent - 代理状态变化
  • presence - 在线状态
  • tick - 心跳
  • health - 健康检查

会话管理

默认使用主会话(main,或当作用域为全局时使用 global)。UI 可以在会话之间切换。入门向导使用专用会话以保持首次运行设置的独立性。

安全边界

远程模式仅通过 SSH 转发网关 WebSocket 控制端口。

已知限制

UI 针对聊天会话优化(不是完整的浏览器沙箱)。

功能特性

• 实时消息:通过 WebSocket 实时接收和发送消息
• 会话切换:在不同聊天会话之间切换
• 消息历史:查看完整的聊天历史记录
• 富文本支持:支持 Markdown 格式和代码块
• 媒体支持:显示图片和其他媒体内容
• 状态指示:显示代理在线状态和输入指示器

使用技巧

• 快捷键:使用键盘快捷键快速访问 WebChat
• 多会话:同时管理多个对话上下文
• 历史搜索:在聊天历史中搜索特定内容
• 消息操作:复制、删除或重新发送消息

故障排除

• 连接失败:
  • 本地模式:检查网关是否运行(openclaw status)
  • 远程模式:验证 SSH 连接和端口转发
• 消息未发送:检查网关健康状态和 WebSocket 连接
• 会话加载失败:确认会话 ID 有效且代理已配置
• 界面卡顿:检查日志中的错误信息

WebSocket 连接

WebChat 要求与网关建立健康的 WebSocket 连接:

• 本地模式:默认端口 18789
• 远程模式:通过 SSH 隧道转发的端口
• 直连模式:配置的网关 URL(ws:// 或 wss://)

入门向导集成

首次运行时,WebChat 会自动使用专用会话进行入门设置:

• 引导用户完成初始配置
• 设置代理和提供商
• 配置权限和偏好设置
• 与主聊天会话分离,保持设置流程清晰