zn-ai/docs/OpenClaw-Chat-Alignment-Plan.md

zn-ai 对齐 ClawX 对话能力的 OpenClaw 集成与迁移计划

1. 当前结论

• zn-ai 已完成 React 平替，当前 Renderer 主链路已经是 src/App.tsx + src/router/index.tsx + src/pages/Home/index.tsx，不再按 Vue 页面作为迁移前提。
• 这意味着接下来的 OpenClaw 对齐重点不再是“技术栈迁移”，而是 Host API / Gateway Lifecycle / Session / Transcript / Agent Routing / Runtime Packaging 这几个能力闭环。
• 推荐继续保留 zn-ai 现有的 gateway:rpc 与 hostApiFetch() 契约，逐步把底层执行面替换成 ClawX + OpenClaw 风格，而不是直接推翻现有 React 聊天页。
• 第一批集成开发已经开始：本地 Host API 路由骨架已从 electron/main.ts 拆出，新增了 Gateway / Sessions / Files / Providers 四类本地路由，为后续 OpenClaw 接入打底。

2. React 平替后的新前提

2.1 当前 React 主链路

模块	当前文件	说明
React App 入口	src/App.tsx	已由 React Router 托管
路由	src/router/index.tsx	主页面已经走 React 路由
主聊天页	src/pages/Home/index.tsx	当前对话、任务中心、渠道入口都在这里
聊天组件	src/components/chat/*	会话列表、消息列表、输入框、任务板
Chat Store	src/stores/chat.ts	已支持流式输出、历史回灌、附件 staging、session 删除
Task/Channel Store	src/stores/task.ts src/stores/channel.ts	已有任务与渠道配置的 React 状态层

2.2 已完成或已落地的基础能力

能力	当前状态	关键文件
Renderer 已 React 化	已完成	src/App.tsx src/router/index.tsx
Home/Chat 主链路	已完成 React 化	src/pages/Home/index.tsx src/components/chat/*
gateway:rpc / gateway:event	已可用	electron/gateway/manager.ts src/lib/gateway-client.ts
hostApiFetch	已可用	src/lib/host-api.ts electron/main.ts
Transcript 写入	已有 jsonl 写入	electron/gateway/handlers/chat.ts electron/utils/token-usage-writer.ts
Provider 本地化	已可用	electron/service/provider-api-service.ts
本地 Session Key	已初步收敛到 agent:*	src/stores/chat.ts

2.3 仍未对齐 ClawX 的关键差距

差距	当前状态	对齐目标
OpenClaw runtime 打包	还没有 openclaw / uv / resource bundling	像 ClawX 一样由主进程打包并启动
Gateway 生命周期治理	当前仍是 in-process manager	对齐 start / stop / restart / health / supervisor
Host API 路由层	刚开始拆分，本地路由还不是完整体系	对齐 ClawX/electron/api/routes/* 风格
Session Transcript API	刚开始补 /api/sessions/transcript	对齐 transcript 读取、删除、后续执行图基础
Agent/Session 主会话映射	仍未有完整 agents 本地接口	对齐 @agent 路由与主会话映射
执行图 / 子任务展示	尚未接入 UI	对齐 ClawX 的 task visualizer / transcript tree

3. ClawX 最小闭环对齐点

当前不需要一次搬运整个 ClawX。根据已完成分析，最值得先对齐的是这 5 个契约：

1. hostApiFetch 所依赖的本地 Host API transport 契约。
2. gateway.status / gateway.health / gateway.ready 生命周期契约。
3. sessions.list / sessions.delete / sessions.transcript 会话目录与 transcript 契约。
4. chat.history 历史回灌契约。
5. chat.send / chat.abort / chat:delta / chat:final / chat:error 流式发送契约。

对应的 ClawX 关键参考文件：

• ClawX/electron/api/routes/gateway.ts
• ClawX/electron/api/routes/sessions.ts
• ClawX/electron/gateway/manager.ts
• ClawX/electron/gateway/process-launcher.ts
• ClawX/src/lib/host-api.ts
• ClawX/src/stores/chat.ts

当前建议只迁“最小闭环”，不一次性搬全：

• 先做 gateway-info / gateway-status / sessions-transcript / stage-buffer。
• 再做 OpenClaw runtime 打包与进程托管。
• 最后才做 Agent Routing / Execution Graph / Control UI / Doctor。

4. 目标架构

React Renderer
  ├─ src/pages/Home/index.tsx
  ├─ src/stores/chat.ts
  ├─ src/stores/task.ts
  ├─ src/stores/channel.ts
  ├─ src/lib/gateway-client.ts
  └─ src/lib/host-api.ts
            │
            │ IPC + Local Host API
            ▼
Electron Main
  ├─ GatewayManager (过渡期 in-process，目标是 OpenClaw process owner)
  ├─ Host API Router (/api/providers /api/gateway /api/sessions /api/files ...)
  ├─ Provider / Agent / Session config sync
  └─ Runtime / packaging / paths
            │
            │ utilityProcess + ~/.openclaw
            ▼
OpenClaw Gateway
  ├─ providers / auth profiles
  ├─ agents / sessions / transcripts
  ├─ tool use / thinking / attachments
  └─ sub-agent / execution graph / control ui

5. 分阶段迁移计划

阶段	状态	目标	主要文件
Phase 0：React 基线收口	已完成	让聊天页、任务中心、渠道入口都运行在 React 主链路	src/App.tsx src/router/index.tsx src/pages/Home/index.tsx
Phase 1：Host API 路由层重构	进行中	把本地 Provider/Gateway/Sessions/Files 从 electron/main.ts 中拆成独立 Host API 路由	electron/api/* electron/main.ts
Phase 2：OpenClaw Runtime/Packaging	待开始	引入 openclaw、uv、runtime path 与 dev/package 双态启动能力	package.json scripts/* electron/utils/paths.ts electron/gateway/*
Phase 3：Gateway Lifecycle + Config Sync	待开始	让 GatewayManager 从 in-process 过渡到 OpenClaw 进程 owner，并同步 provider/agent/session 配置	electron/gateway/* electron/service/provider-api-service.ts
Phase 4：React Chat Store 对齐	待开始	让 React Chat Store 对齐 ClawX 的 session/history/send/abort/transcript 契约	src/stores/chat.ts src/lib/host-api.ts src/lib/gateway-client.ts
Phase 5：Agent Routing + Execution Graph	待开始	接入 @agent 主会话映射、transcript 读取、执行图和子任务展示	src/pages/Home/* src/components/chat/* electron/api/routes/sessions.ts
Phase 6：验收与收口	待开始	做 E2E 与回归，清理过渡实现，准备进入 OpenClaw 主架构	文档、测试、构建脚本

6. 第一批已开工内容

这轮已经开始落地的文件：

• electron/api/router.ts
• electron/api/context.ts
• electron/api/route-utils.ts
• electron/api/routes/providers.ts
• electron/api/routes/gateway.ts
• electron/api/routes/files.ts
• electron/api/routes/sessions.ts
• electron/gateway/manager.ts
• electron/main.ts

当前已完成的第一批能力：

• 本地 Host API 路由分发骨架已经建立。
• Provider 本地接口已从 electron/main.ts 的大 switch 逻辑中拆分。
• 新增 Gateway 本地路由：/api/app/gateway-info、/api/gateway/status、/api/gateway/health。
• 新增 Sessions 本地路由：/api/sessions/transcript、/api/sessions/delete。
• 新增 Files 本地路由：/api/files/stage-buffer、/api/files/stage-paths。
• GatewayManager 已补充最小 status / health / start / stop / restart 接口，作为向 OpenClaw process owner 演进的过渡层。

7. sub-agent 数量估算

7.1 推荐编制

• 分析 sub-agent：2
• 迁移开发 sub-agent：5
• 集成验收 sub-agent：1
• 推荐总数：8

7.2 最小可行编制

• 分析 sub-agent：2
• 迁移开发 sub-agent：4
• 验收由主协调 agent 兼任
• 最小总数：6

7.3 为什么推荐 8 个

• React 技术栈迁移已经完成，所以不再需要专门的“Vue/React 双栈迁移” sub-agent。
• 但 OpenClaw 对齐仍横跨 Runtime Packaging、Gateway Lifecycle、Host API、Config Sync、React Chat Store、Transcript / Execution Graph 六条线。
• 如果迁移 sub-agent 少于 5，很容易出现“主进程基础已经就绪，但 React 聊天页迟迟接不上”或“Transcript API 已有但 UI 不可见”的串行瓶颈。

8. sub-agent 分工与开工安排

8.1 分工方案

角色	数量	负责范围	文件所有权
A1：ClawX/OpenClaw 契约分析	1	提炼 ClawX 的最小闭环契约、关键文件与最小迁移子集	只读分析
A2：zn-ai 差距映射	1	盘点当前 React/Gateway/Host API 的实际状态与缺口	只读分析
M1：Host API / Gateway Foundation	1	拆本地 Host API 路由，补 Gateway info/status/health，建立本地接口框架	electron/api/* electron/main.ts electron/gateway/manager.ts
M2：OpenClaw Runtime / Packaging	1	迁移 openclaw 打包、uv、runtime 路径和 dev/package 启动链路	package.json scripts/* electron/utils/paths.ts electron/gateway/*
M3：Config Sync / Providers / Agents / Sessions	1	把 provider 配置逐步收敛成 OpenClaw 可消费格式，并补本地 agent/session 接口	electron/service/provider-api-service.ts electron/api/routes/*
M4：React Chat Store / History / Send	1	对齐 chat.send/history/abort/session.list 与 transcript fallback	src/stores/chat.ts src/lib/host-api.ts src/lib/gateway-client.ts
M5：React Chat UI / Agent Routing / Execution Graph	1	接 @agent、thinking/tool cards、transcript 展示与执行图入口	src/pages/Home/* src/components/chat/*
I1：集成验收与收口	1	联调、回归、验收 checklist、发布说明	测试与文档

8.2 当前已启动的角色

角色	当前状态	备注
A1	已启动并完成首轮分析	已明确最小闭环是 transport -> gateway lifecycle -> sessions -> history -> send/stream
A2	已启动但中途断流	不阻塞主线，已由主协调 agent 接管现状映射
M1	已启动	第一批 Host API 路由骨架已落地
主协调 agent	已启动	正在更新总计划文档并推进 Phase 1 基建

8.3 建议并行波次

波次	并行角色	目标
Wave 1	A1 + A2 + 主协调 agent	冻结契约与当前状态，确认迁移边界
Wave 2	M1 + M2	一边拆 Host API，一边准备 OpenClaw runtime 打包与路径层
Wave 3	M3 + M4	配置同步与 React Chat Store 并行接入
Wave 4	M5 + I1	执行图 / Agent Routing / UI 收口与联调验收

9. 接下来的直接开发任务

按优先级建议这样推进：

1. 完成 Phase 1：
   • 继续把 hostapi:fetch 中本地可处理接口迁入 electron/api/routes/*。
   • 明确 gateway-info 与 session-transcript 的返回结构，冻结给前端使用。
2. 启动 Phase 2：
   • 新增 electron/utils/paths.ts，对齐 ClawX 的 runtime 路径管理。
   • 迁移 openclaw bundling 脚本与 uv 下载脚本。
3. 启动 Phase 3：
   • 增加 agents 本地接口与 main session 映射。
   • 让当前 DEFAULT_AGENT_ID / DEFAULT_SESSION_KEY 不再硬编码。
4. 启动 Phase 4：
   • 让 React Chat Store 能读取 Host API 的 gateway-info 与 session-transcript。
   • 把当前 history/session 逻辑从“本地过渡实现”逐步切向 OpenClaw 兼容契约。

10. 风险与约束

风险	说明	当前策略
Host API 本地/远端混用	迁移期容易出现一部分接口本地、一部分接口远端，行为不一致	所有 OpenClaw 相关接口逐步收敛到本地 Host API，业务后台接口继续远端代理
Gateway 仍是 in-process	当前还不是真正的 OpenClaw 进程托管	先补生命周期接口与路由层，再替换运行时
Agent 路由尚未真实接入	当前 sessionKey 虽是 agent:* 风格，但主会话映射仍不完整	放在 M3 / M5 联合推进
Transcript 能力有后端无前端	当前先补 Host API 路由，不代表 UI 已展示	通过 M4 / M5 分批接前端
仓库已有 TS 历史债	当前 tsc 仍存在一批既有错误	先以构建通过和新增链路可用为准，不在本轮一口气清旧债

11. 当前验收口径

当前这一轮不以“OpenClaw 全部接通”为验收，而是以以下条件作为 Phase 1 开工完成标准：

• zn-ai 仍能正常构建。
• 本地 Host API 路由骨架已经独立存在，不再全部堆在 electron/main.ts。
• 已有 gateway-info / gateway-status / session-transcript / file-stage 这类 ClawX 风格本地路由。
• 文档中的 sub-agent 分工和实际代码开工状态一致。

本轮之后，正式进入 Phase 2-4 的并行迁移。