openclaw桌面端体验--ClawX

Jahzo
0 阅读3分钟

ClawX 工程工作原理详解

本文档描述 ClawX 桌面应用的架构、进程划分、数据流与关键组件，便于理解与二次开发。

一、整体架构概览

ClawX 采用 双进程 + 独立网关 的三层架构：Electron 主进程、React 渲染进程、OpenClaw Gateway 进程。UI 与 AI 运行时隔离，保证界面流畅。

┌─────────────────────────────────────────────────────────────────────────────┐
│                          ClawX 桌面应用 (Electron)                            │
│                                                                              │
│  ┌──────────────────────────────────────────────────────────────────────┐   │
│  │                    Electron 主进程 (Node.js)                          │   │
│  │  • 窗口/应用生命周期 (main/index.ts, window.ts)                        │   │
│  │  • Gateway 进程管理 (gateway/manager.ts) — 启动/停止/重连              │   │
│  │  • IPC 处理 (main/ipc-handlers.ts) — 转发渲染进程请求                  │   │
│  │  • 系统集成：托盘、通知、钥匙串、自动更新                               │   │
│  │  • ClawHub 服务 (gateway/clawhub.ts) — Skill 搜索/安装/卸载 (CLI)      │   │
│  └───────────────────────────────────┬──────────────────────────────────┘   │
│                                       │                                        │
│                                       │ IPC (invoke / on)                      │
│                                       │ 安全通道：preload 白名单 channel       │
│                                       ▼                                        │
│  ┌──────────────────────────────────────────────────────────────────────┐   │
│  │                    React 渲染进程 (BrowserWindow)                     │   │
│  │  • 技术栈：React 19 + Vite + TypeScript + Zustand + Tailwind/shadcn    │   │
│  │  • 页面：Setup / Dashboard / Chat / Channels / Skills / Cron / Settings │   │
│  │  • 通过 window.electron.ipcRenderer.invoke/on 与主进程通信            │   │
│  │  • 状态：gateway / chat / channels / cron / providers / settings 等   │   │
│  └──────────────────────────────────────────────────────────────────────┘   │
└───────────────────────────────────────┬───────────────────────────────────────┘
                                        │
                                        │ WebSocket (ws://localhost:18789/ws)
                                        │ 协议：OpenClaw (req/res/event + connect 握手)
                                        ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                        OpenClaw Gateway 进程 (独立)                           │
│  • 端口：18789 (PORTS.OPENCLAW_GATEWAY)                                       │
│  • 职责：AI 编排、频道管理、Skill 执行、Provider 抽象、Cron 调度                │
│  • 由主进程 spawn（node/Electron 跑 entry + gateway 子命令）                   │
└─────────────────────────────────────────────────────────────────────────────┘

二、详细架构图 (Mermaid)

2.1 进程与通信关系

flowchart TB
  subgraph Renderer["React 渲染进程"]
    UI[React 页面/组件]
    Stores[Zustand Stores]
    UI --> Stores
  end

  subgraph Main["Electron 主进程"]
    IPC[IPC Handlers]
    GW[GatewayManager]
    ClawHub[ClawHubService]
    IPC --> GW
    IPC --> ClawHub
  end

  subgraph Preload["Preload 脚本"]
    Bridge[contextBridge API]
  end

  subgraph Gateway["OpenClaw Gateway 进程"]
    WS[WebSocket Server :18789]
    Agent[Agent 运行时]
    Channels[频道管理]
    Skills[Skill 执行]
    WS --> Agent
    WS --> Channels
    WS --> Skills
  end

  Renderer -->|invoke/on 白名单| Preload
  Preload -->|ipcRenderer| Main
  GW -->|WebSocket JSON-RPC| WS
  GW -->|status/notification/chat:message 等| IPC
  IPC -->|webContents.send| Renderer

2.2 应用启动与 Gateway 启动流程

sequenceDiagram
  participant User
  participant App as Electron App
  participant Main as 主进程
  participant GW as GatewayManager
  participant OC as OpenClaw Gateway 进程
  participant WS as WebSocket

  User->>App: 启动 ClawX
  App->>Main: app.whenReady()
  Main->>Main: createWindow, createTray, registerIpcHandlers
  Main->>GW: gatewayManager.start()

  alt 已有 Gateway 在运行
    GW->>WS: findExistingGateway() 探测 18789
    WS-->>GW: 连接成功
    GW->>GW: connect(port) 握手
  else 无现有进程
    GW->>OC: startProcess() spawn node/electron + gateway --port 18789 --token ...
    OC->>OC: 启动 HTTP+WS 服务
    GW->>GW: waitForReady() 轮询 ws 可连
    GW->>WS: connect(18789) WebSocket
  end

  WS-->>GW: connect.challenge (nonce)
  GW->>WS: connect (auth token + device 签名)
  WS-->>GW: connect 成功 (res)
  GW->>Main: emit('status', running)
  Main->>Renderer: gateway:status-changed
  Main->>Main: ensureClawXContext() 合并工作区配置

2.3 用户发消息（聊天）数据流

sequenceDiagram
  participant User
  participant ChatUI as Chat 页面
  participant GatewayStore as gateway store
  participant Main as 主进程
  participant GW as GatewayManager
  participant OC as OpenClaw Gateway

  User->>ChatUI: 输入并发送消息
  ChatUI->>GatewayStore: rpc('chat.send', { content, sessionKey, ... })
  GatewayStore->>Main: ipcRenderer.invoke('gateway:rpc', 'chat.send', params)
  Main->>GW: gatewayManager.rpc('chat.send', params)
  GW->>OC: WebSocket send { type:'req', id, method:'chat.send', params }
  OC->>OC: 执行 Agent/模型调用
  OC-->>GW: 流式/事件: event agent (state/message)
  GW->>GW: handleMessage → emit('chat:message' / 'notification')
  GW->>Main: (已在 IPC 里订阅) status/notification/chat:message
  Main->>ChatUI: webContents.send('gateway:notification', { method:'agent', params })
  ChatUI->>ChatUI: gateway store 中 on('gateway:notification') → chat store handleChatEvent
  ChatUI->>User: 更新 UI（流式或最终消息）

2.4 Gateway 与主进程事件转发

flowchart LR
  subgraph Gateway进程
    A[OpenClaw Gateway]
  end
  subgraph 主进程
    B[GatewayManager]
    C[IPC Handlers]
  end
  subgraph 渲染进程
    D[Gateway Store / Chat Store]
  end

  A -->|WebSocket message| B
  B -->|emit status| C
  B -->|emit notification| C
  B -->|emit chat:message| C
  B -->|emit channel:status| C
  C -->|gateway:status-changed| D
  C -->|gateway:notification| D
  C -->|gateway:chat-message| D
  C -->|gateway:channel-status| D

三、目录与职责速览

路径职责
electron/main/应用入口、窗口、菜单、托盘；注册 IPC；启动/监听 Gateway
electron/gateway/manager.tsGateway 进程生命周期、WebSocket 连接、重连、RPC 与事件解析
electron/gateway/client.ts对外的类型化 RPC 封装（channels/skills/chat/cron/providers/system）
electron/gateway/protocol.tsJSON-RPC 2.0 与 OpenClaw 协议类型、事件类型
electron/gateway/clawhub.tsClawHub CLI 封装：Skill 搜索/安装/卸载/列表（独立于 Gateway 进程）
electron/preload/index.tscontextBridge 暴露安全 API，IPC channel 白名单
electron/main/ipc-handlers.ts所有 IPC handle/on，包括 gateway:*、provider、cron、channel、clawhub 等
electron/utils/存储(store)、安全存储(secure-storage)、路径(paths)、OpenClaw 配置与认证等
src/stores/gateway.ts前端 Gateway 状态、init、rpc、订阅 status/error/notification
src/stores/chat.ts聊天历史、发送、接收流式/事件（由 gateway notification 驱动）
vite.config.tsVite + electron 主进程/预加载入口，渲染进程用 Vite 开发服务器

四、关键协议与端口

  • Gateway 端口：18789（electron/utils/config.ts 中 PORTS.OPENCLAW_GATEWAY）。
  • 开发时 Vite：渲染进程通常 5173。
  • 与 Gateway 通信：
    • 连接：ws://localhost:18789/ws。
    • 握手：Gateway 先发 connect.challenge（带 nonce），主进程回 connect（token + 可选 device 签名）。
    • 请求/响应：{ type: 'req', id, method, params } → { type: 'res', id, ok, payload }。
    • 服务端推送：{ type: 'event', event, payload }，例如 event: 'agent' 表示聊天流式/状态更新。

五、两条“技能”相关路径

  • ClawHub（Skill 市场/安装）：主进程通过 ClawHubService 调用 ClawHub CLI（clawhub search/install/uninstall/list），不经过 Gateway；前端通过 clawhub:* IPC 调用。
  • Gateway 内 Skill：安装后的 Skill 由 OpenClaw Gateway 加载与执行；配置可通过 Gateway RPC（如 skills.list、skills.updateConfig）或主进程直接写 ~/.openclaw 下的配置文件（skill:getConfig / skill:updateConfig IPC）。

六、开发与构建要点

  • pnpm：使用 package.json 中 packageManager 指定的 pnpm 版本；建议 corepack enable && corepack prepare。
  • pnpm dev：同时启动 Vite 与 Electron；主进程会自动启动 Gateway（约 10–30 秒就绪）。
  • 热重载：仅影响渲染进程；主进程或 Gateway 改动需重启应用。
  • 无数据库：配置与状态依赖 electron-store 和系统钥匙串。

以上即为 ClawX 工程的工作原理与架构概览；结合 README 与 AGENTS.md 可快速上手开发与调试。

avatar
文章
阅读
粉丝