# ZCLAW 功能 -> OpenClaw 子系统落地路线图

**日期**: 2026-03-12  
**依据**: `docs/openclaw-deep-dive.md`  
**目标**: 把 ZCLAW 从“像 OpenClaw 的桌面 UI”推进为“真正围绕 OpenClaw Runtime 的 Tauri 封装层”。

---

## 一、总原则

后续所有功能都按同一条映射链设计与验收：

> ZCLAW 功能 -> OpenClaw 子系统 -> 真实配置/文件/路由/运行时行为 -> 前端展示与操作

如果一个功能改完后：

- 没有改变 OpenClaw 的真实配置
- 没有改变 Agent 的真实身份/工作区/边界
- 没有改变 Channel / Heartbeat / Skills / MCP / Gateway 的真实行为

那它仍然只是 UI 占位，不算真正落地。

---

## 二、路线图总览

| 阶段 | 主题 | 目标 | 结果 |
|---|---|---|---|
| **R0** | Gateway 协议与连接 | 让 ZCLAW 成为一个可稳定连上 OpenClaw Gateway 的控制端 | `连接/重连/状态/错误` 可用 |
| **R1** | Agent 模型收敛 | 把 `分身/快速配置/右侧 Agent 面板` 收敛成真实 Agent Profile | `Clone -> Agent Profile` |
| **R2** | 配置控制面板化 | 把设置页从“本地状态”收敛为 OpenClaw 配置编辑器 | `config/get/patch/apply` |
| **R3** | Workspace / Bootstrap 文件 | 让 Agent 身份、人格、用户上下文落到 workspace 文件 | `IDENTITY/SOUL/USER/AGENTS` |
| **R4** | Channels / Bindings | 让 IM 页面真正管理渠道输入与路由 | `channels + bindings` |
| **R5** | Heartbeat / 定时任务 | 把“定时任务页”升级为 Heartbeat 控制台 | `heartbeat + HEARTBEAT.md` |
| **R6** | Skills / MCP | 让技能与工具能力成为真实可管理能力面 | `skills + mcp` |
| **R7** | 产品化壳层 | 完成 Tauri sidecar、安装、诊断、迁移与回归体系 | 可交付桌面产品 |

---

## 三、功能 -> OpenClaw 子系统映射

## 1. Gateway 连接

### 对应子系统

- `Gateway WebSocket Protocol`
- `device auth`
- `pairing`
- `scopes`
- `auth.token / auth.deviceToken`

### ZCLAW 当前功能

- 设置页里的 Gateway URL
- 右侧连接状态卡片
- 自动连接逻辑

### 应落地到

- `desktop/src/lib/gateway-client.ts`
- 协议握手适配
- 正确错误码展示
- 后续可补 `pairing required / token drift / device auth` 诊断提示

### 验收标准

- 能稳定连接本地 OpenClaw Gateway
- 状态能从 `disconnected -> connecting -> handshaking -> connected`
- 错误能区分：
  - token 问题
  - device auth 问题
  - mode/client id 问题
  - pairing 问题

### 优先级

- **最高**

---

## 2. 分身 / 快速配置 / 右侧 Agent 区域

### 对应子系统

- `agents.list[]`
- `workspace / agentDir`
- `IDENTITY.md`
- `SOUL.md`
- `USER.md`
- `AGENTS.md`

### ZCLAW 当前功能

- 左侧分身列表
- 快速配置弹层
- 右侧 `Agent` 标签页

### 正确语义

- **分身 = Agent 实例**
- **快速配置 = 新建 / 更新 Agent Profile**
- **右侧 Agent 区域 = 当前 Agent 的身份与上下文可视化**

### 应落地到

- 插件层：`zclaw-ui` 中的 Agent Profile RPC
- 数据层：从 `CloneConfig` 升级为 `AgentProfile`
- 前端层：`CloneManager / RightPanel / chatStore`
- 工作区层：为每个 Agent 生成/更新 bootstrap 文件

### 验收标准

- 创建 Agent 后，左侧、聊天头部、右侧 Agent 面板一致
- Agent 的身份字段有统一来源
- 不再依赖单纯前端本地 fallback agent

### 优先级

- **最高**

---

## 3. 工作区设置

### 对应子系统

- `agents.defaults.workspace`
- `agents.list[].workspace`
- `sandbox`
- `tools allow/deny`
- bootstrap files

### ZCLAW 当前功能

- 工作目录
- 文件限制
- 自动保存上下文
- 文件监听

### 正确语义

工作区不是 UI 里的一个路径输入框，而是：

- Agent 的上下文根目录
- bootstrap 文件所在位置
- 文件访问边界
- 工具执行边界的基础

### 应落地到

- `config.patch/apply`
- workspace info RPC
- Agent 级与 defaults 级区分

### 验收标准

- 改动工作区后，OpenClaw 配置能真实更新
- 右侧 Agent 面板能展示当前 Agent 的工作目录与边界

### 优先级

- **高**

---

## 4. IM 频道页

### 对应子系统

- `channels.*`
- `channels.<channel>.accounts`
- `bindings`
- mention / allowlist / route target

### 正确语义

IM 页不是“集成列表”，而是：

- 管理消息从哪里进入系统
- 管理这些消息如何路由到哪个 Agent

### 应落地到

- `channels.list/status` + 插件探测
- 后续补 `bindings` 可视化
- 账号级与渠道级配置区分

### 验收标准

- 至少能看清当前有哪些 channel/account
- 至少能表达“这个输入源会进入哪个 Agent”

### 优先级

- **高**

---

## 5. 定时任务页

### 对应子系统

- `agents.defaults.heartbeat`
- `agents.list[].heartbeat`
- `HEARTBEAT.md`

### 正确语义

不是单纯 cron 列表，而是：

- 哪些 Agent 会被定期唤醒
- 唤醒后看什么
- 没事时如何 ack
- 结果发去哪里

### 应落地到

- `heartbeat.tasks` 读取
- heartbeat 配置编辑
- `HEARTBEAT.md` 管理入口

### 验收标准

- UI 中明确 Heartbeat 是 Agent turn，不是普通定时脚本

### 优先级

- **中高**

---

## 6. 技能页

### 对应子系统

- `skills`
- `SKILL.md`
- extra skill dirs

### 正确语义

技能页的目标是：

- 告诉用户 Agent 会做什么
- 告诉用户这些能力从哪些 skill 目录和手册里来

### 应落地到

- 真实技能目录扫描
- `openclaw skills list/info/check` 对应能力
- extraDirs 与当前 Agent 能力面关联

### 验收标准

- 不只是维护一个字符串数组
- 能看到技能来源与状态

### 优先级

- **中高**

---

## 7. MCP 服务页

### 对应子系统

- MCP / RPC adapters / 外部工具能力面

### 正确语义

不是前端模板收藏，而是：

- Agent 当前能调用哪些外部能力
- 这些能力如何被配置、启用与管理

### 优先级

- **中高**

---

## 8. 用量统计 / 会话 / 系统信息

### 对应子系统

- sessions
- usage
- plugin status
- gateway health

### 目标

- 提供可观察性
- 让用户知道 Agent 是否真的在运行、运行了多少、谁在消耗成本

### 优先级

- **中**

---

## 四、阶段化执行方案

## Phase A：把“分身系统”收敛成 Agent Profile 层

### 目标

先把最接近用户感知的核心链路做对：

- 左侧分身
- 快速配置
- 右侧 Agent 面板
- 聊天头部 Agent 名称

### 具体动作

1. 引入统一 `AgentProfile` 类型
2. 插件层 `CloneConfig` 升级为更完整 profile
3. store 层把 `clones` 视为 `agentProfiles`
4. `chatStore.currentAgent` 不再自带孤立 fallback 逻辑
5. quick config 默认值与 workspace/profile 字段打通

### 阶段验收

- 创建出来的 Agent，在所有 UI 位置是一致实体
- 刷新后仍能从持久化数据恢复

---

## Phase B：让 Quick Config 不再只是 JSON 临时缓存

### 目标

把 quick config 从：

- `zclaw.config.quick` 的一份附加偏好

收敛到：

- Agent 创建向导 / 最近一次 Agent 草稿

### 具体动作

1. 区分 `quickConfigDraft` 与 `agentProfiles`
2. 保存快速配置时，不再误导成“系统总配置”
3. 后续为 bootstrap 文件生成预留字段映射

### 阶段验收

- quick config 有清晰职责
- 不和真实 Agent Profile 混淆

---

## Phase C：把 Agent Profile 继续落到 workspace/bootstrap 文件

### 目标

让 Agent 的身份不是只活在 `zclaw-data.json` 里。

### 具体动作

1. 为 Agent 生成独立 workspace 或 profile 目录
2. 写入/更新：
   - `IDENTITY.md`
   - `USER.md`
   - `SOUL.md`
   - `AGENTS.md`
3. 让右侧 Agent 面板字段与这些文件的内容有映射关系

### 阶段验收

- Agent 真正拥有可审计、可读、可迁移的文本身份

---

## Phase D：设置页全面收敛为 OpenClaw 配置控制台

### 目标

把现有 Settings 页从 local state 管理升级为：

- OpenClaw config 编辑器
- Gateway runtime 控制台

### 关键动作

- 优先用 `config.get / patch / apply`
- 区分：
  - defaults
  - per-agent
  - per-channel/account

---

## 五、当前代码库的立即修正项

## 1. 数据模型不一致

当前前端 `Clone` 已经包含：

- `workspaceDir`
- `restrictFiles`
- `privacyOptIn`
- `userName`
- `userRole`

但插件层 `CloneConfig` 仍未完整持久化这些字段。

### 立即动作

- 插件层升级 `CloneConfig`
- `create/update/list` 全链路透传这些字段

## 2. `chatStore` 与 `gatewayStore` 双重 Agent 模型并存

当前问题：

- `chatStore.agents/currentAgent` 仍是 UI 型实体
- `gatewayStore.clones` 是更接近真实 profile 的实体

### 立即动作

- 让 `currentAgent` 选择依赖真实 profile id
- 补一个从 profile 派生 chat agent 的适配层

## 3. quickConfig 语义仍不清晰

### 立即动作

- 在代码与文档中明确：
  - 它是草稿 / 最近一次快速配置输入
  - 它不是 Agent 全量真源

---

## 六、下一步开发顺序

### 立即执行

1. **修 Agent Profile 数据模型一致性**
2. **收敛 Quick Config 与 Agent Profile 的职责边界**
3. **让右侧 Agent 面板只读真实 profile 数据**

### 之后执行

4. Gateway 协议继续收口
5. Workspace / bootstrap 文件生成
6. IM / Heartbeat / Skills / MCP 分页逐个真实化

---

## 七、完成定义

当下面这些条件满足时，才能认为 ZCLAW 已经真正开始 OpenClaw 化：

- 分身不再只是 UI 列表，而是 Agent 实体
- 快速配置不再只是表单，而是 Agent 创建向导
- 右侧 Agent 面板展示真实 Agent Profile
- 设置页改的是 OpenClaw 真实运行配置
- Heartbeat / Channels / Skills / MCP 不再是占位页
- Gateway 连接协议稳定可诊断

---

## 八、本轮执行建议

本轮优先做：

- **Agent Profile 统一模型**
- **插件层持久化字段补齐**
- **前端选择/展示逻辑收敛**

原因：

- 这条链最贴近用户感知
- 能直接验证 `openclaw-deep-dive.md` 的核心判断
- 也是后续 workspace/bootstrap/channel/binding 的前置基础