# ZCLAW 偏离分析报告

**日期**: 2026-03-11  
**目的**: 对标 QClaw / AutoClaw / OpenClaw，分析当前项目是否偏离初衷

---

## 一、三大产品深度理解

### 1. OpenClaw — 开源核心 (GitHub 28万+ Stars)

OpenClaw 是一个**本地优先的 AI 代理平台**，不是简单的聊天机器人，而是一个能真正操控电脑执行任务的系统。

**核心架构:**

| 组件 | 说明 |
|------|------|
| **Gateway** | Node.js 进程，是整个系统的**核心控制面板**，管理 sessions、channels、tools、events |
| **Channel Plugins** | IM 渠道适配器 — WhatsApp, Telegram, Slack, Discord, iMessage 等 10+ 种 |
| **心跳引擎 (Heartbeat)** | 定期唤醒，检查 HEARTBEAT.md 任务清单，**主动**执行预定任务 |
| **持久化身份** | SOUL.md(性格)、MEMORY.md(长期记忆)、AGENTS.md(角色配置) — **纯文本，Git 可控** |
| **Skills 系统** | SKILL.md 文件 + 脚本，三级渐进式披露，100+ 预配置技能 |
| **MCP 支持** | 模型上下文协议，JSON-RPC 2.0，扩展外部工具 (File System, Web Fetch, DB 等) |
| **核心工具** | bash(命令行)、read/write(文件系统)、browser(浏览器控制) |
| **插件体系** | Channel / Memory / Tool / Provider 四类插件 |
| **存储** | 默认 SQLite，支持向量存储、知识图谱 |

**关键设计哲学:**
- **本地优先**: 所有数据和执行都在本地
- **透明可控**: 纯文本配置，用户能完全掌控 AI 的"大脑"
- **执行而非建议**: 不是只出主意，而是真正动手做事
- **自我进化**: Agent 可修改自身指令、改进工作流

---

### 2. QClaw — 腾讯产品化封装

QClaw **不是**腾讯从零重写的框架，而是**围绕 OpenClaw 做的一次产品化封装**。

**核心卖点:**
- **一键安装**: 下载即用，无需配置环境
- **微信 + QQ 双端接入**: 腾讯核心优势，在微信/QQ中直接对话指挥电脑
- **内置国产模型**: Kimi, MiniMax, GLM, DeepSeek + 自定义模型
- **5000+ Skills 生态**: ClawHub、GitHub 等丰富生态
- **持续记忆**: 记住偏好和上下文
- **本地部署**: 操控文件、浏览器、邮件

**使用场景:**
- 远程操作电脑文件/网页
- 社媒自动运营
- GitHub 项目自动开发
- 学术论文自动整理
- 每日天气定时提醒

---

### 3. AutoClaw — 智谱 AutoGLM 定制版 (v0.2.12)

基于 OpenClaw 的智谱定制版，核心是**飞书集成**。

**从 13 张界面截图提取的完整功能架构:**

#### 主界面布局
- **左侧栏 3 个 Tab**: 分身 / IM频道 / 定时任务
- **中间**: 聊天区域 + 发送框 + 模型选择器 (glm-5)
- **右侧**: 代码/文件区域 + Agent 面板

#### 设置系统 (10 个页面)
| 页面 | 功能 |
|------|------|
| 通用 | 账号安全、主题(白色/Neon Noir)、开机自启、显示工具调用 |
| 用量统计 | 会话数/消息数/总Token，按模型分类统计 |
| 积分详情 | 积分总量、消耗/获得明细 |
| **模型与API** | 内置模型(Pony-Alpha-2) + 自定义模型(glm-5/qwen3.5-plus/kimi-k2.5/MiniMax-M2.5) + **Gateway URL** (ws://127.0.0.1:18789) |
| **MCP 服务** | File System / Web Fetch + 快速添加(Brave Search, SQLite) |
| **技能** | SKILL.md 文件管理，额外技能目录 (~/.opencode/skills) |
| **IM 频道** | 添加/管理频道，快速添加飞书 |
| **工作区** | 项目目录、文件访问限制、自动保存上下文、文件监听、从OpenClaw迁移 |
| 数据与隐私 | 本地数据路径、优化计划 |
| 提交反馈 / 关于 | 反馈表单、版本信息 |

#### 核心概念
- **分身 (Clone)**: 每个分身是独立的 Agent 实例，有自己的配置和对话历史
- **快速配置**: 名字、角色、昵称、使用场景(编程/写作/产品/数据分析/设计/运维/研发/营销)
- **Gateway WebSocket 连接**: ws://127.0.0.1:18789 — 这是 OpenClaw Gateway 的连接方式
- **工作区**: 默认 ~/.openclaw-autoclaw/workspace，文件访问沙盒

---

## 二、当前 ZCLAW 项目现状

### 已有的代码 (37 文件, 2378 行)

| 模块 | 内容 |
|------|------|
| src/config/ | Zod 配置管理 |
| src/utils/ | Logger + ID 生成器 |
| src/db/ | SQLite Schema (8表) + BaseDAO |
| src/core/ai/ | 智谱GLM + OpenAI Provider + AIManager |
| src/core/multi-agent/ | MessageBus + BaseAgent + Planner/Executor/Combiner + Orchestrator |
| src/core/remote-execution/ | 并发队列 + 任务管理 |
| src/core/task-orchestration/ | 拓扑排序 + 计划执行 |
| src/core/memory/ | 内存记忆 + 用户画像 |
| src/core/proactive/ | node-cron 定时任务 |
| src/im/ | IM Gateway + 飞书适配器 |
| src/api/ | ZClawAPI for Tauri |
| src/app.ts | ZClawApp 主类 |
| desktop/ | Tauri + React 三栏布局 |

---

## 三、偏离分析 — 核心问题

### 🔴 严重偏离

#### 1. 架构根本性偏离 — 没有基于 OpenClaw

**问题**: 项目初衷是"学习 QClaw 跟 AutoClaw，打造结合 Tauri + OpenClaw 的系统"，但当前代码**完全没有 OpenClaw 的影子**。

- OpenClaw 的核心是 **Gateway** (Node.js 进程 + WebSocket)
- QClaw 和 AutoClaw 都是**围绕 OpenClaw 做封装**
- 我们的 ZCLAW 却从零自己发明了一套架构 (RemoteExecutionEngine / TaskOrchestrator / AgentOrchestrator)
- 这些自创系统**不是 OpenClaw 的概念**，等于在重造轮子

**应该**: 直接集成 OpenClaw Gateway，或至少学习其架构模式来构建

#### 2. Skills 系统完全缺失

**问题**: Skills 是 OpenClaw/QClaw/AutoClaw 的**核心扩展机制**。

- OpenClaw 有 100+ 预配置技能
- QClaw 有 5000+ Skills 生态
- AutoClaw 截图显示有完整的技能管理界面
- Skills 基于 SKILL.md 文件，三级渐进式披露，解决 Token 成本
- 我们的 `src/skills/` 目录是**空的**，完全没有实现

#### 3. MCP (模型上下文协议) 完全缺失

**问题**: MCP 是现代 AI Agent 的标准工具扩展协议。

- AutoClaw 内置: File System、Web Fetch，可快速添加 Brave Search、SQLite
- OpenClaw 原生支持 MCP
- 我们完全没有 MCP 支持

#### 4. 工具执行层是"假的"

**问题**: OpenClaw 能**真正**操控电脑 — 执行 Shell 命令、读写文件、控制浏览器。

- 我们的 BrowserAgent / FileAgent / TerminalAgent 实际上是**用 AI 模拟输出结果**
- 没有任何真实的命令执行、文件操作或浏览器控制能力
- 用户期望"操控电脑完成任务"，我们只能"假装操作然后编结果"

---

### 🟡 方向偏离

#### 5. "多Agent协作" vs "分身(Clone)"概念错位

**问题**: 
- AutoClaw 的"分身"是**独立的 Agent 实例**，每个分身有自己的名字、角色、记忆、对话
- 我们的"多 Agent"是面向**任务拆解**的 (Planner → Executor → Combiner)
- 这是两种完全不同的概念

**AutoClaw 的分身**: 像是雇了多个助手，每个负责不同领域  
**我们的多 Agent**: 像是一个任务流水线，Planner 规划 → Executor 执行 → Combiner 汇总

#### 6. 持久化方式偏离

**问题**:
- OpenClaw 用**纯文本文件**: SOUL.md, MEMORY.md, AGENTS.md — 透明、Git 可控
- 我们用 SQLite 数据库表
- 数据库不是错的，但缺少 OpenClaw 的**透明可控**理念
- 用户无法像 Git 那样管理 AI 的"大脑"

#### 7. 心跳引擎缺失

**问题**:
- OpenClaw 的核心特色是**心跳引擎** — 定期唤醒，检查 HEARTBEAT.md，主动执行任务
- 这是"主动服务"的真正含义
- 我们的 ProactiveServiceSystem 只是简单的 node-cron 定时器包装

#### 8. 工作区 (Workspace) 概念缺失

**问题**:
- AutoClaw 有完整的工作区管理: 项目目录、文件访问沙盒、上下文自动保存、文件监听
- 这是 Agent 安全执行的基础
- 我们完全没有工作区概念

---

### 🟢 方向正确

| 功能 | 评价 |
|------|------|
| 左侧栏三个 Tab (分身/IM频道/定时任务) | ✅ 与 AutoClaw 布局一致 |
| 多模型 Provider 支持 | ✅ 但需加 Gateway WebSocket 连接 |
| IM 网关 + 飞书适配器 | ✅ 但应更像 OpenClaw Channel Plugin |
| 定时任务 | ✅ 需升级为心跳引擎模式 |
| SQLite 数据库 | ✅ OpenClaw 也用 SQLite，但需补充纯文本文件 |
| Tauri 桌面应用 | ✅ 与目标一致 (QClaw用Electron, 我们用Tauri更好) |
| 配置管理 (.env) | ✅ 需要但方向对 |

---

## 四、偏离程度评估

```
整体偏离程度: ████████░░ 75%
```

**核心原因**: 项目从**"基于 OpenClaw 做 Tauri 封装"**变成了**"从零自建 AI Agent 框架"**。

这就像是：
- 目标是造一辆"基于丰田平台的改装车"
- 实际上在从零造发动机、底盘和变速箱
- 造出来的还跟丰田的规格不兼容

---

## 五、修正建议

### 方案 A: 直接集成 OpenClaw（推荐）

```
OpenClaw Gateway (npm install openclaw)
      ↕ WebSocket (ws://127.0.0.1:18789)
Tauri Desktop App (我们的前端)
      ↕ Tauri Commands
React UI (学习 AutoClaw 的界面设计)
```

**步骤:**
1. 安装 OpenClaw 作为依赖（或子进程启动）
2. 通过 WebSocket 连接 OpenClaw Gateway
3. Tauri 前端做 UI 封装（学 AutoClaw 的设计）
4. 添加自定义 Channel Plugin (微信/QQ/飞书)
5. 添加自定义 Skills
6. 添加 MCP 服务管理

**优点**: 直接获得 OpenClaw 的全部能力 (真实工具执行、Skills 生态、MCP 等)  
**缺点**: 学习成本，依赖外部项目

### 方案 B: 学习架构重构（折中）

保留 Tauri + 自己的后端，但按 OpenClaw 的架构模式重构：

1. **重构为 Gateway 模式**: 把我们的后端重构为 OpenClaw 风格的 Gateway
2. **实现 Skills 系统**: SKILL.md 文件 + 渐进式披露
3. **实现 MCP 支持**: JSON-RPC 2.0 工具扩展协议
4. **实现真实工具**: bash 命令执行、文件读写、浏览器控制 (Playwright)
5. **实现分身系统**: 每个分身 = 独立 Agent 实例 + 独立配置/记忆
6. **实现心跳引擎**: HEARTBEAT.md + 定期检查 + 主动执行
7. **实现工作区**: 项目沙盒 + 文件监听 + 上下文保存
8. **补充纯文本持久化**: SOUL.md + MEMORY.md + AGENTS.md

**优点**: 深度学习理解架构，自主可控  
**缺点**: 工作量大，可能重复造轮子

### 方案 C: 混合方案（务实）

- OpenClaw 作为执行引擎（子进程运行或 WebSocket 连接）
- Tauri 做桌面 UI 封装（仿 AutoClaw 界面）
- 自己实现差异化功能（微信接入、中文 Skills、国产模型优化）

---

## 六、需要保留 vs 需要重写 vs 需要新建

### ✅ 保留
- `src/config/` — 配置管理（调整 key 名称对标 OpenClaw）
- `src/utils/` — Logger + ID 生成器
- `src/db/` — SQLite 层（OpenClaw 也用 SQLite）
- `src/core/ai/` — 多模型 Provider（补充 Gateway 连接方式）
- `src/im/` — IM 网关（重构为 Channel Plugin 模式）
- `desktop/` — Tauri 前端（大幅扩展界面）

### 🔄 重写
- `src/core/multi-agent/` → 重构为**分身 (Clone) 系统**
- `src/core/remote-execution/` → 重构为**真实工具执行层** (bash/file/browser)
- `src/core/task-orchestration/` → 简化，交给 LLM 自主规划
- `src/core/proactive/` → 重构为**心跳引擎**
- `src/core/memory/` → 补充纯文本文件 (MEMORY.md)
- `src/app.ts` → 重构为 **Gateway 模式**

### 🆕 新建
- `src/skills/` — Skills 系统（SKILL.md 加载/解析/注册）
- `src/mcp/` — MCP 协议支持
- `src/tools/` — 真实工具执行 (bash, file, browser via Playwright)
- `src/workspace/` — 工作区管理（沙盒、文件监听、上下文保存）
- `src/gateway/` — WebSocket Gateway 服务
- 前端设置页面（通用/用量统计/模型API/MCP/技能/IM/工作区/隐私）

---

## 七、结论

**当前项目已经严重偏离了"学习 QClaw/AutoClaw + 基于 OpenClaw"的初衷。**

核心问题不在于代码质量（代码是可以编译的），而在于**架构方向**：我们在自己发明一套 AI Agent 框架，而不是基于 OpenClaw 做 Tauri 封装。

建议选择方案后，优先做以下事情：
1. 深入研究 OpenClaw 源码和 Gateway 架构
2. 确定是直接集成还是学习重构
3. 实现 Skills 系统和 MCP 支持
4. 实现真实工具执行能力
5. 按 AutoClaw 界面设计前端

---

*本报告基于 QClaw 官网、AutoClaw 官网 + 13张界面截图、OpenClaw GitHub + 技术文章的深度分析*
