# ZCLAW 交付执行计划（2026-03-12） ## 1. 计划目标 本计划的目标不是继续做“功能堆叠”，而是把当前仓库推进到**可安装、可启动、可连接、可对话、可配置、可验证**的可交付状态。 当前对“完整可用 ZCLAW”的定义如下： - 用户能够在本机启动 ZCLAW 桌面应用 - 用户安装 ZCLAW 时，OpenClaw 运行时已经随包提供，而不是要求用户另行安装 - 桌面应用能够引导并管理随 ZCLAW 一起分发的本地 OpenClaw Gateway - 前端能够稳定连接 Gateway，并完成基础握手与鉴权 - 用户能够创建、编辑、切换 Agent（Clone） - 用户能够发起真实对话并收到流式回复 - 关键设置页不再只是静态占位，而是尽量接到真实后端能力 - 有一套清晰的验收与收尾流程，支持阶段性提交与后续发布 --- ## 2. 当前基线 ### 2.1 已完成的关键能力 - Gateway 握手参数已修正，能够兼容 OpenClaw 2026.3.11 - Token 鉴权已接入前端连接流程 - `zclaw-ui` 插件可被 Gateway 正常加载 - Agent 的创建、编辑、保存链路已打通 - `scripts/setup.ts` 已可在已有 `~/.openclaw/openclaw.json` 时非破坏性合并插件与 skills 路径 - 自定义插件 manifest/package id 对齐问题已修复 ### 2.2 当前仍阻塞交付的核心问题 按交付优先级排序，当前最关键的缺口为： 1. **桌面端尚未真正接管 Gateway 生命周期** - `src/gateway/manager.ts` 已存在，但未被 Tauri 壳使用 - `desktop/src-tauri/src/lib.rs` 仍是默认模板 - 当前产品更像“前端连接外部 Gateway”，还不是“完整桌面应用” 2. **当前仍默认依赖用户独立安装 OpenClaw** - 这与最终产品目标不一致 - 最终必须做到：安装 ZCLAW 后即可直接使用 OpenClaw 能力 - 因此现阶段的 CLI/PATH 依赖只能作为开发期和过渡期方案 3. **真实桌面链路缺少本地运行闭环验证** - 需要验证 Tauri 内从启动 Gateway 到连接、到拉数据、到发消息的完整过程 4. **设置体系中仍有若干页面/按钮处于占位状态** - 部分页面已有 UI 但尚未连接真实能力 - 会影响“可用”判断，尤其是用户首次体验 5. **交付收尾缺少固定验收流程** - 需要统一 smoke test、安装前检查、文档更新、阶段提交点 --- ## 3. 总体推进策略 ### 3.1 核心原则 - **先打通闭环，再做扩展**：优先修复阻塞真实使用的能力缺口，而不是继续加功能 - **优先最短交付路径**：优先复用 OpenClaw 现有 CLI/service 能力，而不是一开始就做完整 sidecar 架构 - **最终必须内置 OpenClaw**：开发阶段允许复用系统已安装的 OpenClaw，但交付阶段必须改为随 ZCLAW 一起分发和托管 - **浏览器模式不回退**：新增 Tauri 能力必须有运行时保护，不影响现有浏览器预览/开发体验 - **阶段可提交**：每个阶段都有独立验收标准，达到后可形成 clean checkpoint ### 3.2 本轮优先级 - **P0**：Tauri 桌面壳接入本地 Gateway 生命周期管理 - **P0**：完成真实桌面端基础闭环验证 - **P0**：确定并落地“ZCLAW 安装即内置 OpenClaw”的分发方案 - **P1**：补齐最影响可用性的设置页占位项 - **P1**：形成交付前 smoke checklist 和文档更新 - **P2**：补测试、清理遗留代码、准备打包发布 --- ## 4. 分阶段执行计划 ## Phase A：桌面端本地 Gateway 生命周期管理（当前最高优先级） ### A.1 目标 让 ZCLAW 桌面应用在 Tauri 环境下具备对本地 OpenClaw Gateway 的基础管理能力： - 查询本地 Gateway 状态 - 启动本地 Gateway - 停止本地 Gateway - 重启本地 Gateway - 在前端展示本地状态，并与现有 WebSocket 连接状态区分开 ### A.2 实现策略 优先采用**Tauri Rust 命令封装 OpenClaw CLI** 的方式，而不是直接引入完整 sidecar： - Rust 侧封装以下命令： - `openclaw gateway status --json` - `openclaw gateway start --json` - `openclaw gateway stop --json` - `openclaw gateway restart --json` - 前端通过 `invoke` 调用 Rust 命令 - 通过运行时判断，仅在 Tauri 环境中启用这组能力 - 浏览器模式继续保留“手工连接外部 Gateway”的现有逻辑 说明： - 这一阶段是**开发期过渡方案** - 它的价值是先把桌面端产品闭环跑通 - 但它**不是最终交付形态** - 最终交付必须把 OpenClaw 运行时随 ZCLAW 一起打包，而不是要求用户本机已有 `openclaw` ### A.3 代码范围 - `desktop/src-tauri/src/lib.rs` - `desktop/src/lib/tauri-gateway.ts`（新增） - `desktop/src/store/gatewayStore.ts` - `desktop/src/components/Settings/General.tsx` - 如有必要：`desktop/src/components/RightPanel.tsx` ### A.4 验收标准 - Tauri 环境可正常调用本地 Gateway 管理命令 - 设置页能看到“本地 Gateway”状态卡片 - 用户可点击启动/停止/重启 - 启动成功后，前端可继续连接并拉取基础数据 - 浏览器模式不因该改动而报错或白屏 - 开发环境下，即使仍依赖系统 `openclaw`，也已经明确与最终 bundling 方案解耦 ### A.5 风险与应对 - **风险**：不同机器上 `openclaw` 不在 PATH - **应对**：前端明确提示“未安装 OpenClaw CLI”或“命令不可用” - **风险**：`status --json` / `start --json` 输出结构不稳定 - **应对**：Rust 侧优先使用 `serde_json::Value` 宽松解析，再映射到前端稳定结构 - **风险**：服务模式与前台 `gateway run` 并存导致认知混乱 - **应对**：UI 文案明确说明“本地服务状态”和“当前 WebSocket 连接状态”是两层状态 --- ## Phase B：真实桌面端基础闭环验证 ### B.1 目标 确认 ZCLAW 在 Tauri 壳内已经不是“能打开 UI”，而是“能完成一次真实任务闭环”： - 本地 Gateway 启动/可达 - 前端连接成功 - Clone 列表加载成功 - Agent 创建/编辑成功 - 首条消息发送成功 - 收到真实流式回复 ### B.2 任务清单 - 启动桌面应用并检查本地 Gateway 状态 - 验证连接状态、版本、插件状态、workspace 信息是否能拉取 - 验证创建 Agent - 验证编辑 Agent 并刷新右侧面板数据 - 验证 bootstrap 文件生成状态 - 验证聊天发送与回复流 - 记录关键报错与回退路径 ### B.3 验收标准 - 至少完成一次完整桌面端对话闭环 - Agent 的创建与编辑在真实环境可用 - 连接失败、Gateway 未安装、未启动等错误能明确提示 - 关键路径没有阻塞性的控制台报错 --- ## Phase C：OpenClaw 随包分发与运行时托管 ### C.1 目标 把当前“依赖用户本机单独安装 OpenClaw”的开发态方案，推进到真正可交付的产品方案： - 用户安装 ZCLAW 时，OpenClaw 运行时已经包含在安装包内 - ZCLAW 启动后，能够直接找到并启动内置 OpenClaw - 用户不需要再单独安装一套 OpenClaw CLI / 环境 ### C.2 目标形态 最终交付建议采用以下形态： - 安装包内包含 OpenClaw 可执行运行时或受控分发产物 - Tauri Rust 侧通过固定相对路径或 sidecar 机制调用该运行时 - ZCLAW 负责： - 初始化 OpenClaw home / workspace - 写入或合并默认配置 - 启动 / 停止 / 重启 Gateway - 读取日志与状态 ### C.3 方案比较 #### 方案 1：继续依赖系统安装的 `openclaw` 优点： - 当前开发改造最少 缺点： - 不符合最终产品目标 - 用户安装体验差 - 环境差异和 PATH 问题会显著增加支持成本 结论： - **仅适合开发期，不可作为最终交付方案** #### 方案 2：把 OpenClaw 作为 sidecar / bundled runtime 随 ZCLAW 分发 优点： - 符合 QClaw / AutoClaw 式的一体化交付体验 - 可控性高 - 便于做安装后自启动、版本锁定、升级兼容 缺点： - 需要处理体积、签名、跨平台打包、路径定位 结论： - **这是最终推荐方案** ### C.4 实施任务 - 确认 OpenClaw 可分发形态 - npm 包直接落地 - 预构建二进制 - 内置 Node + OpenClaw 组合运行时 - 确认 Tauri 2 下 sidecar / bundled binary 的最佳实现方式 - 为 Windows 优先落地一版 bundling 方案 - 调整 Rust 侧命令执行逻辑 - 优先调用内置运行时 - 开发模式可回退到系统 `openclaw` - 验证安装后首次启动流程 - 不依赖用户额外安装 - 可直接启动 Gateway - 可连接、可聊天、可配置 ### C.5 验收标准 - 全新机器上，未单独安装 OpenClaw 的情况下，可直接安装并启动 ZCLAW - ZCLAW 可成功拉起内置 OpenClaw Gateway - Agent / 聊天 / 设置等核心功能可正常工作 - 用户文档不再要求“先安装 OpenClaw 再使用 ZCLAW” --- ## Phase D：设置页可用性补齐 ### D.1 目标 梳理 Settings 体系中“看起来像功能、实际上还是占位”的部分，优先补齐最影响交付感知的项。 ### D.2 优先补齐范围 优先级从高到低建议如下： 1. **General / ModelsAPI** - Gateway 管理与连接语义统一 - 去掉误导性按钮或接到真实逻辑 2. **Workspace / Skills / MCPServices** - 至少展示真实读取结果 - 对未支持能力明确标注“暂未接入”而不是伪交互 3. **IMChannels** - 飞书状态尽量走真实探测 - 对未完成渠道使用明确状态说明 4. **Privacy / UsageStats / About** - 以展示真实数据和静态说明为主，收尾体验 ### D.3 判定标准 - 对用户可点击的动作，尽量有真实效果 - 对暂未接入的能力，明确说明而不是假按钮 - 页面不出现明显“假功能”感 --- ## Phase E：交付前 smoke test 与文档收尾 ### E.1 目标 形成一套最小但明确的交付前检查流程，避免“本地看起来能用、别人拿到跑不起来”。 ### E.2 交付前 smoke checklist #### 环境检查 - `pnpm -v` - `pnpm --dir desktop tauri --version` 说明： - 最终交付 smoke test 不应再把系统级 `openclaw --version` 作为前置要求 - 应改为验证 ZCLAW 内置运行时是否可用 #### 桌面启动检查 - `pnpm --dir desktop tauri dev` - UI 能正常打开 - 设置页不白屏 #### Gateway 闭环检查 - 本地 Gateway 状态可读 - 能启动/停止/重启 - 前端连接成功 #### 核心功能检查 - Clone 列表加载 - 新建 Clone - 编辑 Clone - 发送首条消息 - 收到流式回复 #### 配置检查 - quick config 可读写 - workspace 信息可读取 - 插件状态可显示 #### 安装闭环检查 - 全新环境中无需单独安装 OpenClaw - 安装 ZCLAW 后首次启动即可使用 - 若内置运行时损坏或缺失，错误提示明确 ### E.3 文档更新项 - 更新 README：区分浏览器模式与 Tauri 桌面模式 - 补充本地 Gateway 启动/连接说明 - 补充已知限制与后续路线 - 在 `PROGRESS.md` 中登记本轮交付成果 --- ## Phase F：交付后加强项（不是当前阻塞项） 以下事项重要，但不应阻塞本轮“完整可用”目标： - 更完整的 Tauri sidecar / 进程托管架构 - 安装包/自动更新 - 更高覆盖率测试 - v1 归档代码清理 - 微信 / QQ Channel 扩展 - 新 Session Prompt 等增强功能 这些能力应在当前闭环稳定后进入下一轮计划。 --- ## 5. 实施顺序与里程碑 ## Milestone 1：桌面端本地 Gateway 管理打通 输出物： - Tauri 命令桥 - 前端本地 Gateway 状态卡片 - 启停/重启操作 完成标志： - 能在桌面应用中看到并操作本地 Gateway 服务状态 ## Milestone 2：真实桌面闭环通过 输出物： - 真实运行验证记录 - 阻塞 bug 列表（若有） - 修复后的可用路径 完成标志： - 从桌面打开到完成一次对话全链路可用 ## Milestone 3：OpenClaw 随包分发打通 输出物： - Windows 优先的一体化 bundling 方案 - ZCLAW 优先调用内置 OpenClaw 运行时 - 安装后无需用户额外安装 OpenClaw 的可运行链路 完成标志： - 在未安装 OpenClaw 的机器/环境中，安装 ZCLAW 后即可直接使用 ## Milestone 4：设置页与交付收尾 输出物： - 最小可交付设置体验 - smoke checklist - README / PROGRESS 更新 完成标志： - 仓库进入“可给他人试用”的状态 --- ## 6. 本轮立即执行项 按当前优先级，接下来立刻执行： 1. 在 Tauri Rust 侧实现 Gateway 管理命令 2. 在前端新增 Tauri Gateway bridge 3. 在 `gatewayStore` 中接入本地 Gateway 状态与动作 4. 在 Settings > General 中增加本地 Gateway 管理卡片 5. 明确 OpenClaw 随包分发方案，避免把系统安装依赖固化为最终设计 6. 进行编译/运行级验证 7. 若验证通过，记录到 `PROGRESS.md` --- ## 7. 阶段提交策略 本轮按以下 checkpoint 推进： ### Checkpoint A - 完成计划文档 - 完成 Tauri 命令桥与前端接线 ### Checkpoint B - 完成本地 Gateway 管理 UI - 完成基础验证 ### Checkpoint C - 完成 OpenClaw bundling / sidecar 方案设计 - 明确 Windows 优先的交付路径 ### Checkpoint D - 完成设置页收尾 / 文档更新 / smoke checklist 说明： - 代码会按干净阶段组织 - 如需执行远端 `push`，仍单独确认 --- ## 8. 结论 当前最短、最正确的交付路径，不是继续扩展更多功能，而是先把 ZCLAW 从“能连 Gateway 的前端”推进成“能在桌面端真正管理并使用内置 OpenClaw 的产品”。 因此，本轮执行的核心结论是： - **先做 Tauri 本地 Gateway 生命周期管理** - **再完成 OpenClaw 随包分发方案** - **然后做真实桌面端闭环验证** - **最后收尾设置页与交付文档** 这条路线最符合当前仓库状态，也最接近“完整可用 ZCLAW”的真实交付目标。