ClawApp 技术解析：H5 移动端 AI 智能体聊天客户端实战

痛点：移动场景下的 AI 交互困境

通勤途中或外出办公时，突然需要和团队部署的 AI 智能体确认某个问题，却发现 OpenClaw 平台只能通过桌面端访问——这种体验相当割裂。

ClawApp 正是为解决这一痛点而生。它是一个专为移动端优化的 H5 聊天客户端，让用户可以随时随地通过手机与 AI 智能体进行对话。

技术架构：H5 如何撑起实时聊天

ClawApp 采用典型的 Web 单页应用（SPA）架构，技术栈如下：

├── 前端框架：Vue 3 + Composition API（或 React）
├── 状态管理：Pinia（Vue 系）/ Redux Toolkit（React 系）
├── 通信层：WebSocket + HTTP Long Polling Fallback
├── UI 层：Tailwind CSS + 自定义组件库
└── 构建工具：Vite

离线能力的关键实现

Service Worker 是 H5 离线能力的核心，ClawApp 通过它实现：

消息缓存与离线续传

// 注册 Service Worker
if ('serviceWorker' in navigator) {
  navigator.serviceWorker.register('/sw.js');
}

// sw.js 中缓存策略
const CACHE_NAME = 'clawapp-v1';
const urlsToCache = ['/index.html', '/static/js/main.js'];

// 消息缓存逻辑
self.addEventListener('fetch', (event) => {
  if (event.request.url.includes('/api/messages')) {
    event.respondWith(
      caches.open(CACHE_NAME).then((cache) => {
        return cache.match(event.request).then((response) => {
          return response || fetch(event.request).then((networkResponse) => {
            cache.put(event.request, networkResponse.clone());
            return networkResponse;
          });
        });
      })
    );
  }
});

后台同步机制

// 离线时将消息加入队列
async function sendMessage(message) {
  if (!navigator.onLine) {
    // 存入 IndexedDB，等待网络恢复后发送
    await db.messages.add({ ...message, pending: true });
    await navigator.serviceWorker.ready.then((registration) => {
      registration.sync.register('sync-messages');
    });
    return { status: 'queued' };
  }
  // 在线则直接发送
  return await fetch('/api/send', { method: 'POST', body: JSON.stringify(message) });
}

这套机制让用户在地铁等弱网环境中也能流畅对话，消息不会因网络波动丢失。

与 OpenClaw 平台的集成

ClawApp 通过 OpenClaw 提供的 RESTful API 与后端服务通信，核心连接方式如下：

WebSocket 实时通信

class OpenClawSocket {
  constructor(apiBase) {
    this.apiBase = apiBase;
    this.socket = null;
    this.reconnectDelay = 1000;
  }

  connect(token, callbacks) {
    this.socket = new WebSocket(`${this.apiBase}/ws/chat?token=${token}`);

    this.socket.onopen = () => {
      console.log('WebSocket 连接已建立');
      callbacks.onOpen?.();
    };

    this.socket.onmessage = (event) => {
      const data = JSON.parse(event.data);
      // 根据 type 分发消息
      if (data.type === 'message') {
        callbacks.onMessage?.(data.content);
      } else if (data.type === 'typing') {
        callbacks.onTyping?.(data.agent_id);
      }
    };

    this.socket.onclose = () => {
      // 自动重连机制
      setTimeout(() => this.reconnect(token, callbacks), this.reconnectDelay);
      this.reconnectDelay = Math.min(this.reconnectDelay * 2, 30000);
    };
  }

  send(content, agentId, sessionId) {
    this.socket.send(JSON.stringify({
      type: 'message',
      agent_id: agentId,
      content: content,
      session_id: sessionId
    }));
  }
}

消息格式示例

{
  "type": "message",
  "agent_id": "agent_xxx",
  "content": "用户输入内容",
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": 1699520000000
}

平台认证采用 JWT Token 机制，移动端每次请求需携带有效 Token，Token 有效期通常设为 24 小时，刷新机制由服务端控制。

快速部署：5 分钟启动你的聊天客户端

环境准备

# 克隆项目
git clone https://github.com/your-repo/ClawApp.git

# 安装依赖
cd ClawApp && npm install

# 配置环境变量
cp .env.example .env

.env 配置示例

# OpenClaw 后端地址
OPENCLAW_API_URL=https://your-openclaw-instance.com

# WebSocket 连接地址
OPENCLAW_WS_URL=wss://your-openclaw-instance.com

# JWT Token（建议使用环境变量注入，不要硬编码）
OPENCLAW_TOKEN=${OPENCLAW_TOKEN}

# 应用名称
VITE_APP_NAME=ClawApp

启动服务

# 开发环境
npm run dev

# 生产环境构建
npm run build

# Docker 部署
docker build -t clawapp .
docker run -d -p 3000:80 --env-file .env clawapp

部署时只需确保 H5 页面能访问到 OpenClaw 后端即可，OpenClaw 需开启 CORS 配置以允许移动端域名访问。

H5 与原生 App 的对比

对于 AI 聊天类应用，H5 方案的优势在于快速触达和低成本迭代。ClawApp 选择 H5，意味着用户只需扫描二维码或点击链接即可使用，无需经历下载、注册、安装的繁琐流程。

适用场景

ClawApp 适合以下场景：

移动办公人员：外出时随时与团队 AI 智能体确认进展，获取实时数据支持

团队管理者：会议间隙快速查询 AI Agent 处理结果，无需打开电脑

客户服务场景：客服人员移动端接收 AI 预筛选结果，提升响应效率

GitHub 上该项目已获得 400+ Stars，社区反馈表明其在移动端 AI 对话场景中有较高的实用价值。

延伸使用

如果需要更便捷地管理 OpenClaw 平台，建议使用 ClawPanel 进行 AI 智能体的配置与监控，它提供了可视化的管理界面和实时状态追踪。

对于有定制需求的开发者，ClawApp 采用模块化设计，核心通信层与 UI 层解耦，可以很方便地替换为自己的组件库或接入其他 AI 平台。

---END---