ClawX 工程工作原理详解
本文档描述 ClawX 桌面应用的架构、进程划分、数据流与关键组件，便于理解与二次开发。
一、整体架构概览
ClawX 采用 双进程 + 独立网关 的三层架构：Electron 主进程 、React 渲染进程 、OpenClaw Gateway 进程。UI 与 AI 运行时隔离，保证界面流畅。
scss
┌─────────────────────────────────────────────────────────────────────────────┐
│ 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.ts |
Gateway 进程生命周期、WebSocket 连接、重连、RPC 与事件解析 |
electron/gateway/client.ts |
对外的类型化 RPC 封装（channels/skills/chat/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/chat.ts |
聊天历史、发送、接收流式/事件（由 gateway notification 驱动） |
vite.config.ts |
Vite + 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:updateConfigIPC）。
六、开发与构建要点
- pnpm ：使用
package.json中packageManager指定的 pnpm 版本；建议corepack enable && corepack prepare。 - pnpm dev：同时启动 Vite 与 Electron；主进程会自动启动 Gateway（约 10--30 秒就绪）。
- 热重载：仅影响渲染进程；主进程或 Gateway 改动需重启应用。
- 无数据库 ：配置与状态依赖
electron-store和系统钥匙串。
以上即为 ClawX 工程的工作原理与架构概览；结合 README 与 AGENTS.md 可快速上手开发与调试。