Clawline¶

Clawline 是 OpenClaw 生态的自有即时通讯系统，包含全栈组件：Web 前端、Gateway、Channel 插件、小程序客户端。项目从 2026-03-18 启动，历时一周完成核心功能开发和部署。

产品定位¶

Clawline 不是普通的聊天应用，而是专门为 OpenClaw Agent 生态设计的专业 IM/Gateway 前端：

多服务器 Agent 聚合：支持连接和管理多个 OpenClaw 服务器的 Agent
技能与上下文集成：输入框支持 slash 命令调用 Agent 技能，显示 Agent 上下文
跨 Agent 搜索：基于 IndexedDB 的本地消息存储，支持跨 Agent、跨会话搜索
移动端优先：PWA 支持，小程序版本，移动端原生体验
协议适配：与 OpenClaw Gateway/Channel 协议深度集成

技术栈¶

Web 客户端¶

前端框架：React + Vite + TypeScript
UI 库：Tailwind CSS v4 + design tokens
状态管理：React hooks + localStorage + IndexedDB
通信协议：WebSocket + SSE 流式
PWA：Service Worker + manifest.json
部署：pm2 + nginx，开发站点：https://web.dev.dora.restry.cn

Gateway¶

Clawline Gateway 是 WebSocket 连接的入口层，负责客户端连接生命周期管理：

WebSocket 连接管理：支持多客户端并发连接，connect() 幂等化——已连接状态不重复建连，解决了 ChatList/ChatRoom 同时挂载导致的重复连接问题
chatId 分配机制：客户端连接时可不携带 chatId，由服务端在 connection.open 后分配稳定标识；禁止客户端在 token auth 场景下伪造 chatId
连接池管理：修复过 connection pool overflow 问题，改进 agent list pruning 机制
断线重连：重连后使用服务端分配的 currentChatId，toast 提示连接恢复状态，保证幂等不重复同步
历史持久化：clawline-history.json 跟踪更新，避免 Gateway 重启后数据丢失
部署：Owl 节点，通过 openclaw gateway restart 管理，jiti 缓存需手动清理

Channel 插件¶

Clawline Channel 是 OpenClaw 的频道插件，处理消息路由、Agent 隔离和会话绑定：

消息路由：client event → backend、backend event → client 的双向路由；Relay 层保持纯透传，不解析包体、不做业务语义
Agent 隔离：按 connectionId 维度隔离 agentMap/statusMap/loadingMap，streaming 隔离通过 H5 Protocol Tester 验证；解决了不同 Agent/连接之间工具调用、会话状态串台问题
会话绑定：声明 supportsCurrentConversationBinding: true 接入 OpenClaw core 自动绑定链路（dispatchReplyFromConfig → resolveConversationBindingRecord），仅 3 行代码改动即打通 ACP session binding
上下文扩展：通过 channel 插件扩展支持 agent context、skills、thinking metadata，而非在 relay 层做业务逻辑
两级存储架构：connection-level buffer 处理实时切换，chat-level store 处理浏览器关闭后的持久化
部署：独立 Git 仓库，rsync 到 extensions/ 目录，清 jiti 缓存后重启生效

SDK¶

@clawlines/sdk 定位为第三方客户端接入库：

现状：SDK 仓库已建立，但功能尚不完善——目前第三方接入仍需读源码
连接协议封装：封装直连模式（ws://host:port）和 Relay 模式（wss://relay/client?channelId&token）的协议差异
目标：提供标准化的连接、消息收发、Agent 列表查询等 API，降低接入门槛

Relay¶

Relay 是 Clawline 的生产部署中间层，提供安全的 WebSocket 代理：

纯透传设计：不解析包体内容，不做业务语义处理，client event → backend、backend event → client
连接协议：wss://relay.restry.cn/client?channelId=<id>&token=<token>，与直连模式（ws://host:port，端口裸奔无鉴权）形成安全层差异
Git 仓库管理：relay gateway 以 Git repo 形式管理，支持版本化更新
已知问题：直连模式无鉴权已识别为产品设计缺陷，relay 模式作为安全接入层
生产部署：relay.restry.cn

小程序客户端¶

框架：微信小程序原生开发
特性：消息队列、离线缓存、网格/列表视图

关键时刻¶

日期	里程碑	重要性
2026-03-18	项目启动，Web 客户端基础可用性修复	⭐⭐⭐
2026-03-19~20	Onboarding/Profile 重构，性能优化，多连接架构	⭐⭐
2026-03-21	移动端优先改造，拖拽排序，协议修复	⭐⭐⭐
2026-03-21 晚	Clawline v2 规划，IndexedDB 消息存储	⭐⭐⭐
2026-03-23~24	分支治理，品牌统一，Gateway/Channel 联调	⭐⭐
2026-03-24	UI 从气泡改为 flat 风格，ChatRoom 重构	⭐⭐
2026-03-25	PWA 移动端适配，Service Worker 缓存修复	⭐⭐
2026-03-26	合并 `feat/sprint1-ux`，处理 UI 回退	⭐
2026-03-27	左右互搏式 UX 重构，长按/复制问题修复	⭐⭐
2026-03-28~30	小程序客户端开发，多 Agent 协作模式探索	⭐⭐
2026-03-24	全栈知识库统一，单 Bot 维护模式确立	⭐⭐⭐

核心功能¶

多连接 Agent 管理¶

支持添加多个 OpenClaw 服务器
Agent 列表支持按服务器分组或聚合显示
网格/列表视图切换，拖拽排序
自定义 Agent 头像

聊天体验¶

从气泡样式改为 flat/thread 风格（类似 Slack/Discord）
支持 Markdown 渲染、代码高亮、表格
消息操作：复制、引用、emoji 反应
语音录制，媒体消息支持
thinking 状态显示，delivery ticks

技能与上下文集成¶

输入框上方显示技能和上下文入口
slash 命令菜单，支持 /use <skillName> 调用技能
AgentContextViewer 显示 Agent 当前上下文
FileGallery 文件管理器

移动端优化¶

PWA 支持，可添加到主屏幕
移动端长按操作菜单
防止横向滚动，safe-area 适配
触控目标优化（≥44px）
iOS WebKit 兼容性修复

架构决策¶

为什么选择多连接架构？¶

Dad 明确要求 Clawline 不应只显示单个 server 的 agents，而要支持展示所有连接服务器的 agent。这是产品定位决定的：Clawline 是 Agent 聚合中心，不是单一服务器的客户端。

为什么从气泡改为 flat 样式？¶

Dad 指出"不需要气泡，不然信息不好展示"。参考 Slack/Discord，flat 样式更适合展示复杂的 Agent 输出内容（代码、表格、长文本）。

为什么引入 IndexedDB？¶

0 协议改动：客户端直接存储，无需修改 Gateway/Channel
跨 Agent 搜索：支持跨会话、跨 Agent 的消息搜索
可扩展性：比 localStorage 更适合消息量增长

为什么移动端优先？¶

Dad 强调"优先优化手机版"，要求"不需要放大，聊天界面不要横向滚动，尽量接近原生体验"。移动端是主要使用场景。

为什么统一到单 Bot 维护？¶

项目后期 Dad 决定将原本分散的 GatewayBot、ChannelBot 统一为 WebBot 维护，原因： - 避免跨 Bot 沟通的信息损失 - 统一知识库，提高维护效率 - Clawline 是全栈产品，需要整体视角

重要技术突破¶

Service Worker 缓存问题解决¶

PWA 的 cache-first 策略导致用户看不到更新，特别在 iOS 上。解决方案： - 自动 skipWaiting() - 统一 build hash 注入机制 - Profile 页面显示版本信息便于确认

iOS PWA 层级问题修复¶

ActionSheet 在 iOS PWA 中被输入栏遮挡，根因是多个 stacking context + overflow 容器导致的渲染层级错误，不是简单的 z-index 问题。

WebSocket 重连死循环修复¶

多处代码无条件调用 channel.connect() 导致已连接状态下仍重复建连，通过增加连接状态判断解决。

移动端长按与文本选择冲突¶

长按消息弹 ActionSheet 会抢占系统文本选择，通过在消息内容区域阻止 touchStart 冒泡解决。

项目状态¶

开发完成，已部署生产环境。WebBot 负责全栈维护，包含 6 个 repository： - client-web：Web 前端 - channel：Channel 插件 - gateway：Gateway 服务 - client-wechat：小程序客户端 - sdk：连接 SDK - docs：项目文档

开发站点：https://web.dev.dora.restry.cn 生产 Gateway：relay.restry.cn