# ZCLAW v2 架构设计 — 基于 OpenClaw 定制化

**日期**: 2026-03-11  
**定位**: 像 AutoClaw 一样，对 OpenClaw 进行定制化封装，打造 Tauri 桌面版

---

## 一、架构总览

```
┌─────────────────────────────────────────────────────────┐
│                    ZCLAW (Tauri App)                     │
│  ┌──────────────────────────────────────────────────┐   │
│  │              React 19 + TailwindCSS               │   │
│  │  ┌────────┐ ┌────────┐ ┌────────┐ ┌──────────┐  │   │
│  │  │ 分身Tab │ │IM频道  │ │定时任务│ │ 设置页面 │  │   │
│  │  └────────┘ └────────┘ └────────┘ └──────────┘  │   │
│  │  ┌──────────────────────────────────────────┐    │   │
│  │  │            聊天区域 + 工具调用展示          │    │   │
│  │  └──────────────────────────────────────────┘    │   │
│  └──────────────────────────────────────────────────┘   │
│                         │ Tauri Commands                 │
│  ┌──────────────────────────────────────────────────┐   │
│  │              Rust Sidecar / Bridge                │   │
│  │  • 管理 OpenClaw Gateway 子进程生命周期           │   │
│  │  • WebSocket 客户端连接 Gateway                   │   │
│  │  • 转发 Gateway 事件到前端                        │   │
│  └──────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘
                         │ WebSocket (ws://127.0.0.1:18789)
┌─────────────────────────────────────────────────────────┐
│              OpenClaw Gateway (Node.js daemon)           │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌───────────┐  │
│  │ Agent    │ │ Skills   │ │ Sessions │ │ Heartbeat │  │
│  │ Runtime  │ │ System   │ │ Manager  │ │ Engine    │  │
│  └──────────┘ └──────────┘ └──────────┘ └───────────┘  │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌───────────┐  │
│  │ Tools    │ │ Memory   │ │ MCP      │ │ Provider  │  │
│  │ (bash/   │ │ (SQLite/ │ │ Server   │ │ (models)  │  │
│  │  file/   │ │  LanceDB)│ │          │ │           │  │
│  │  browse) │ │          │ │          │ │           │  │
│  └──────────┘ └──────────┘ └──────────┘ └───────────┘  │
│  ┌──────────────────────────────────────────────────┐   │
│  │              Channel Plugins (IM 渠道)             │   │
│  │  WhatsApp │ Telegram │ Discord │ Slack │ ...      │   │
│  └──────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────┐   │
│  │           ZCLAW Custom Plugins (我们的)            │   │
│  │  @zclaw/feishu │ @zclaw/wechat │ @zclaw/qq       │   │
│  │  @zclaw/chinese-models (GLM/Qwen/Kimi/MiniMax)   │   │
│  └──────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘
                         │
              ┌──────────┴──────────┐
              │  Bootstrap Files    │
              │  AGENTS.md          │
              │  SOUL.md            │
              │  IDENTITY.md        │
              │  USER.md            │
              │  TOOLS.md           │
              └─────────────────────┘
```

---

## 二、核心设计决策

### 1. OpenClaw 作为执行引擎

**不重新发明轮子**。OpenClaw 已经实现了：
- ✅ 真实工具执行 (bash/file/browser)
- ✅ Skills 系统 (SKILL.md + 渐进式披露)
- ✅ MCP 协议支持
- ✅ 心跳引擎 (Heartbeat)
- ✅ 持久记忆 (SQLite + LanceDB)
- ✅ Agent 运行时 (Session/Queue/Streaming)
- ✅ 10+ IM 渠道适配器
- ✅ 插件体系 (Channel/Tool/Memory/Provider)

我们只需要：**包装 + 定制 + 中文化**

### 2. Tauri 作为桌面壳

AutoClaw 用的是自己的桌面框架，QClaw 用 Electron。我们用 **Tauri 2.0** (Rust + React)：
- 更小体积 (~10MB vs Electron ~150MB)
- 更好性能 (Rust native)
- 系统级集成能力
- 管理 OpenClaw Gateway 子进程

### 3. 自定义插件做差异化

通过 OpenClaw 的 Plugin API 添加中国特色功能：

| 插件 | 功能 |
|------|------|
| `@zclaw/feishu` | 飞书 Channel Plugin |
| `@zclaw/wechat` | 微信 Channel Plugin (通过 WeCom API 或 itchat 桥接) |
| `@zclaw/qq` | QQ Channel Plugin |
| `@zclaw/chinese-models` | 中文模型 Provider (智谱GLM/通义千问/Kimi/MiniMax) |
| `@zclaw/zclaw-ui` | 自定义 Gateway RPC 方法供 Tauri UI 调用 |

---

## 三、项目结构 (重构后)

```
ZClaw/
├── desktop/                          # Tauri 2.0 桌面应用
│   ├── src-tauri/                    # Rust 后端
│   │   ├── src/
│   │   │   ├── main.rs              # Tauri 入口
│   │   │   ├── gateway.rs           # OpenClaw Gateway 子进程管理
│   │   │   ├── ws_client.rs         # WebSocket 客户端
│   │   │   └── commands.rs          # Tauri Commands (前端调用)
│   │   ├── Cargo.toml
│   │   └── tauri.conf.json
│   ├── src/                          # React 前端
│   │   ├── App.tsx
│   │   ├── main.tsx
│   │   ├── index.css
│   │   ├── components/
│   │   │   ├── Sidebar.tsx           # 左侧栏 (分身/IM/定时)
│   │   │   ├── ChatArea.tsx          # 聊天区域 + 工具调用展示
│   │   │   ├── RightPanel.tsx        # 右侧面板
│   │   │   └── Settings/             # 设置页面 (对标 AutoClaw)
│   │   │       ├── General.tsx       # 通用设置
│   │   │       ├── UsageStats.tsx    # 用量统计
│   │   │       ├── ModelsAPI.tsx     # 模型与 API
│   │   │       ├── MCPServices.tsx   # MCP 服务管理
│   │   │       ├── Skills.tsx        # 技能管理
│   │   │       ├── IMChannels.tsx    # IM 频道管理
│   │   │       ├── Workspace.tsx     # 工作区设置
│   │   │       ├── Privacy.tsx       # 数据与隐私
│   │   │       └── About.tsx         # 关于
│   │   ├── store/
│   │   │   ├── chatStore.ts          # 聊天状态
│   │   │   ├── gatewayStore.ts       # Gateway 连接状态
│   │   │   └── settingsStore.ts      # 设置状态
│   │   └── lib/
│   │       ├── gateway-client.ts     # WebSocket 客户端封装
│   │       └── protocol.ts           # Gateway 协议类型定义
│   └── package.json
│
├── plugins/                          # ZCLAW 自定义 OpenClaw 插件
│   ├── zclaw-feishu/                 # 飞书频道插件
│   │   ├── index.ts
│   │   ├── plugin.json               # 插件清单
│   │   └── README.md
│   ├── zclaw-wechat/                 # 微信频道插件
│   │   ├── index.ts
│   │   └── plugin.json
│   ├── zclaw-qq/                     # QQ 频道插件
│   │   ├── index.ts
│   │   └── plugin.json
│   ├── zclaw-chinese-models/         # 中文模型 Provider 插件
│   │   ├── index.ts
│   │   ├── providers/
│   │   │   ├── zhipu.ts              # 智谱 GLM
│   │   │   ├── qwen.ts              # 通义千问
│   │   │   ├── kimi.ts              # Moonshot Kimi
│   │   │   └── minimax.ts           # MiniMax
│   │   └── plugin.json
│   └── zclaw-ui/                     # UI 扩展 RPC 插件
│       ├── index.ts
│       └── plugin.json
│
├── skills/                           # ZCLAW 自定义 Skills
│   ├── chinese-writing/              # 中文写作技能
│   │   └── SKILL.md
│   ├── weibo-automation/             # 微博自动化技能
│   │   └── SKILL.md
│   └── feishu-docs/                  # 飞书文档操作技能
│       └── SKILL.md
│
├── config/                           # ZCLAW 默认配置
│   ├── openclaw.default.json         # 预设的 OpenClaw 配置
│   ├── SOUL.md                       # 默认人格
│   ├── AGENTS.md                     # 默认 Agent 指令
│   ├── IDENTITY.md                   # 默认身份
│   └── USER.md                       # 默认用户配置
│
├── scripts/                          # 构建/安装脚本
│   ├── setup.ts                      # 首次设置脚本
│   ├── install-openclaw.ts           # OpenClaw 安装检测
│   └── register-plugins.ts           # 注册自定义插件
│
├── docs/
│   ├── architecture-v2.md            # 本文件
│   ├── deviation-analysis.md         # 偏离分析报告
│   ├── DEVELOPMENT.md
│   └── autoclaw界面/                 # AutoClaw 参考截图
│
├── package.json                      # 根项目管理
├── tsconfig.json
└── README.md
```

---

## 四、与 AutoClaw 功能对标

### AutoClaw 设置页面 → ZCLAW 实现方式

| AutoClaw 功能 | ZCLAW 实现 |
|---|---|
| **通用** (账号/主题/开机启动/工具调用显示) | Tauri 窗口设置 + Gateway config |
| **用量统计** (会话/消息/Token 按模型分) | 读取 OpenClaw sessions JSONL + 统计 |
| **积分详情** | 自定义积分系统 (可选) |
| **模型与API** (内置+自定义模型+Gateway URL) | `openclaw config` + Provider Plugin |
| **MCP 服务** (File System/Web Fetch/+添加) | 读取 OpenClaw MCP 配置 + UI 管理 |
| **技能** (SKILL.md 管理/额外目录) | 读取 Skills 目录 + UI 管理 |
| **IM 频道** (添加/管理/快速添加飞书) | Channel Plugin 配置 UI |
| **工作区** (项目目录/文件限制/上下文保存/文件监听) | `agents.defaults.workspace` + sandbox 配置 |
| **数据与隐私** (本地路径/优化计划) | OpenClaw 数据目录 + 隐私配置 |
| **提交反馈** | 自定义反馈表单 |
| **关于** (版本/更新) | 显示 ZCLAW + OpenClaw 版本 |

### AutoClaw 主界面 → ZCLAW 对标

| 功能 | 实现 |
|---|---|
| **左侧 - 分身 Tab** | 通过 `agents.list` 配置管理多个 Agent |
| **左侧 - IM 频道 Tab** | 通过 `channels.*` 配置显示已连接频道 |
| **左侧 - 定时任务 Tab** | 通过 heartbeat + cron 事件显示 |
| **中间 - 聊天区域** | WebSocket 订阅 `agent` stream 事件 |
| **中间 - 模型选择器** | 通过 `agents.defaults.models` 配置 |
| **右侧 - 代码/文件面板** | 显示 Agent 工具调用结果 (file/bash output) |
| **快速配置弹窗** | 修改 IDENTITY.md + SOUL.md + USER.md |

---

## 五、WebSocket 通信协议

ZCLAW Tauri 客户端通过标准 OpenClaw Gateway 协议通信：

### 连接握手
```json
// 1. 服务器发送 challenge
{"type": "event", "event": "connect.challenge", "payload": {"nonce": "...", "ts": 1737264000000}}

// 2. 客户端发送 connect
{"type": "req", "id": "1", "method": "connect", "params": {
  "minProtocol": 3, "maxProtocol": 3,
  "client": {"id": "zclaw-tauri", "version": "0.1.0", "platform": "windows", "mode": "operator"},
  "role": "operator",
  "scopes": ["operator.read", "operator.write"],
  "auth": {"token": "..."}
}}

// 3. 服务器回复 hello-ok
{"type": "res", "id": "1", "ok": true, "payload": {"type": "hello-ok", "protocol": 3}}
```

### 核心 RPC 方法
```
agent          → 发送消息给 Agent (触发 Agent Loop)
agent.wait     → 等待 Agent 运行完成
send           → 通过 IM 频道发送消息
health         → 健康检查
status         → 获取 Gateway 状态
system-presence → 系统状态
```

### 事件订阅
```
agent    → Agent 流式输出 (assistant/tool/lifecycle)
chat     → 聊天消息
presence → 在线状态
health   → 健康状态
heartbeat → 心跳
cron     → 定时任务
tick     → 定时心跳
```

---

## 六、开发分期

### Phase 1: 基础连通 (当前优先)
1. 安装 OpenClaw 并验证 Gateway 可运行
2. 创建 Tauri 项目结构 (保留现有 desktop/)
3. 实现 Gateway 子进程管理 (Rust sidecar)
4. 实现 WebSocket 客户端连接
5. 前端显示 Gateway 状态 + 基础聊天

### Phase 2: 自定义插件
1. 实现 `@zclaw/chinese-models` Provider Plugin (智谱GLM/Qwen/Kimi)
2. 实现 `@zclaw/feishu` Channel Plugin
3. 注册插件到 OpenClaw Gateway

### Phase 3: 完整 UI
1. 实现设置页面体系 (对标 AutoClaw 10 个页面)
2. 实现分身管理 UI
3. 实现 Skills 管理 UI
4. 实现 MCP 服务管理 UI

### Phase 4: 高级功能
1. 微信/QQ Channel Plugin
2. 自定义 Skills 开发
3. 工作区管理
4. 打包发布

---

## 七、与之前代码的关系

### 可复用
- `desktop/` 前端组件 (需大幅扩展)
- `plugins/zclaw-chinese-models/` 可复用之前的 AI Provider 代码 (zhipu.ts/openai.ts)
- `plugins/zclaw-feishu/` 可复用之前的飞书适配器代码

### 废弃
- `src/core/remote-execution/` → OpenClaw 自带工具执行
- `src/core/task-orchestration/` → OpenClaw Agent Loop 自带
- `src/core/multi-agent/` → 改为 OpenClaw agents.list 多 Agent
- `src/core/memory/` → OpenClaw Memory Plugin 自带
- `src/core/proactive/` → OpenClaw Heartbeat Engine 自带
- `src/im/gateway.ts` → OpenClaw Channel 系统自带
- `src/app.ts` → OpenClaw Gateway 就是 app
- `src/api/` → 通过 WebSocket + Tauri Commands 替代
- `src/db/` → OpenClaw 自带 SQLite
- `src/config/` → OpenClaw 配置系统替代

---

*本架构设计基于对 OpenClaw 官方文档 (docs.openclaw.ai) 的深度研究，
参考 AutoClaw v0.2.12 的 13 张界面截图进行功能对标。*