阿里本地通
101.9MB · 2026-02-28
本文档描述 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 / ch@t / 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 子命令） │
└─────────────────────────────────────────────────────────────────────────────┘
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/ch@t:message 等| IPC
IPC -->|webContents.send| Renderer
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() 合并工作区配置
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('ch@t.send', { content, sessionKey, ... })
GatewayStore->>Main: ipcRenderer.invoke('gateway:rpc', 'ch@t.send', params)
Main->>GW: gatewayManager.rpc('ch@t.send', params)
GW->>OC: WebSocket send { type:'req', id, method:'ch@t.send', params }
OC->>OC: 执行 Agent/模型调用
OC-->>GW: 流式/事件: event agent (state/message)
GW->>GW: handleMessage → emit('ch@t:message' / 'notification')
GW->>Main: (已在 IPC 里订阅) status/notification/ch@t:message
Main->>ChatUI: webContents.send('gateway:notification', { method:'agent', params })
ChatUI->>ChatUI: gateway store 中 on('gateway:notification') → ch@t store handleChatEvent
ChatUI->>User: 更新 UI（流式或最终消息）
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 ch@t:message| C
B -->|emit channel:status| C
C -->|gateway:status-changed| D
C -->|gateway:notification| D
C -->|gateway:ch@t-message| D
C -->|gateway:channel-status| D
| 路径 | 职责 |
|---|---|
electron/main/ | 应用入口、窗口、菜单、托盘；注册 IPC；启动/ Gateway |
electron/gateway/manager.ts | Gateway 进程生命周期、WebSocket 连接、重连、RPC 与事件解析 |
electron/gateway/client.ts | 对外的类型化 RPC 封装（channels/skills/ch@t/cron/providers/system） |
electron/gateway/protocol.ts | JSON-RPC 2.0 与 OpenClaw 协议类型、事件类型 |
electron/gateway/clawhub.ts | ClawHub CLI 封装：Skill 搜索/安装/卸载/列表（独立于 Gateway 进程） |
electron/preload/index.ts | contextBridge 暴露安全 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/ch@t.ts | 聊天历史、发送、接收流式/事件（由 gateway notification 驱动） |
vite.config.ts | Vite + electron 主进程/预加载入口，渲染进程用 Vite 开发服务器 |
18789（electron/utils/config.ts 中 PORTS.OPENCLAW_GATEWAY）。5173。ws://localhost:18789/ws。connect.challenge（带 nonce），主进程回 connect（token + 可选 device 签名）。{ type: 'req', id, method, params } → { type: 'res', id, ok, payload }。{ type: 'event', event, payload }，例如 event: 'agent' 表示聊天流式/状态更新。ClawHubService 调用 ClawHub CLI（clawhub search/install/uninstall/list），不经过 Gateway；前端通过 clawhub:* IPC 调用。skills.list、skills.updateConfig）或主进程直接写 ~/.openclaw 下的配置文件（skill:getConfig / skill:updateConfig IPC）。package.json 中 packageManager 指定的 pnpm 版本；建议 corepack enable && corepack prepare。electron-store 和系统钥匙串。以上即为 ClawX 工程的工作原理与架构概览；结合 README 与 AGENTS.md 可快速上手开发与调试。
