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

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

1. 结论摘要

• zn-ai 当前已经具备一套可工作的本地聊天骨架：gateway:rpc、gateway:event、providerApiService、流式渲染、会话列表、附件发送、thinking/tool_use/tool_result 数据结构都已存在。
• ClawX 的核心优势不在单个聊天组件，而在于一整套“Electron Main 托管 OpenClaw Gateway + Host API 统一入口 + ~/.openclaw 运行时配置 + Agent/Session/Transcript`”的闭环。
• 如果目标是“对齐 ClawX 的对话能力”，推荐采用 ClawX 原生方案对齐，而不是继续把 zn-ai 现有轻量 gateway 做成长期主架构。
• 推荐实施路径是：先保持 zn-ai 现有 gateway:rpc / gateway:event 契约不变，逐步把底层执行面替换成 OpenClaw。这样可以最大化复用 Vue Renderer，降低一次性重写风险。

2. ClawX 集成 OpenClaw 的实现思路

层级	ClawX 做法	关键文件	对 zn-ai 的启发
OpenClaw 运行时打包	把 openclaw 包和全部运行时依赖打进应用资源目录，同时额外打包 uv、Windows Node 二进制	ClawX/scripts/bundle-openclaw.mjs ClawX/scripts/download-bundled-uv.mjs ClawX/electron/utils/paths.ts	zn-ai 不能只复用接口，必须把 OpenClaw runtime 一起嵌入，才能真正对齐 ClawX 的行为与目录结构
Gateway 生命周期	Electron utilityProcess 启动 openclaw.mjs，主进程负责 start/stop/restart/health/reconnect/orphan cleanup	ClawX/electron/gateway/manager.ts ClawX/electron/gateway/process-launcher.ts ClawX/electron/gateway/supervisor.ts	zn-ai 现有 in-process gateway 可作为过渡层，但目标应切到独立 OpenClaw 进程托管
Host API 统一接入	主进程启动本地 Host API Server，Renderer 统一通过 hostApiFetch() 与各类 /api/* 路由通信	ClawX/electron/api/server.ts ClawX/electron/api/routes/gateway.ts ClawX/electron/api/routes/sessions.ts ClawX/src/lib/host-api.ts	zn-ai 目前 hostapi:fetch 同时承担“本地 provider”与“远端业务后端”两套职责，后续需要把 OpenClaw 相关能力彻底本地化
Renderer 与 Gateway 通信	Renderer 通过 gateway:rpc 和 /api/app/gateway-info 建立统一通信链路，不直接知道 OpenClaw 进程细节	ClawX/src/lib/gateway-client.ts ClawX/electron/api/routes/gateway.ts	zn-ai 已经有相同方向的封装，这部分最值得保留
对话状态机	Chat Store 负责流式消息、历史回灌、错误恢复、附件缓存、tool/thinking 归并、会话切换	ClawX/src/stores/chat.ts ClawX/src/stores/chat/runtime-send-actions.ts ClawX/src/stores/chat/runtime-event-handlers.ts	zn-ai 现有 src/stores/chat.ts 已经很接近，可以按契约对齐而不必推倒重来
对话展示能力	Markdown、thinking 展示、tool cards、图片/文件附件、@agent 路由、执行图、sub-agent transcript	ClawX/src/pages/Chat/index.tsx ClawX/src/pages/Chat/ChatInput.tsx ClawX/src/pages/Chat/ChatMessage.tsx	zn-ai 需要补的是“真实能力闭环”，而不是单纯补 UI 外观
子任务/转录读取	通过 Session Transcript API 读取子 agent 的 jsonl 转录，驱动执行图	ClawX/electron/api/routes/sessions.ts ClawX/src/pages/Chat/index.tsx	这是 zn-ai 当前缺失最明显的一块，也是对齐 ClawX 对话体验的关键差异点

3. zn-ai 当前基础与差距

3.1 已有基础

能力	当前实现	关键文件	评估
主进程聊天入口	已有 gateway:rpc 与 hostapi:fetch	zn-ai/electron/main.ts	可复用
本地 gateway 骨架	已有 GatewayManager、chat.send/history/abort/session.list	zn-ai/electron/gateway/manager.ts zn-ai/electron/gateway/handlers/chat.ts zn-ai/electron/gateway/types.ts	适合做过渡层
Provider 本地存储	Provider 账户、默认账户、API Key 已本地化	zn-ai/electron/service/provider-api-service/index.ts	可作为 OpenClaw 配置同步源
Renderer chat 状态机	已支持流式更新、错误恢复、历史回读、附件、tool status	zn-ai/src/stores/chat.ts	高复用价值
消息模型	已定义 thinking/tool_use/tool_result/image	zn-ai/src/pages/home/model/ChatModel.ts	结构已接近 ClawX
聊天 UI	已有消息列表、输入框、附件、Markdown、会话侧栏	zn-ai/src/pages/home/ChatBox.vue zn-ai/src/pages/home/ChatHistory.vue zn-ai/src/pages/home/components/chat/*	可迭代增强

3.2 主要差距

差距	当前状态	对齐目标
OpenClaw runtime	还没有嵌入 openclaw 包、utilityProcess 启动链路、打包脚本	与 ClawX 一样由主进程托管 OpenClaw Gateway
Host API 本地闭环	hostapi:fetch 仍混合本地代理和远端服务转发	OpenClaw 相关 /api/* 统一落在本地主进程 Host API
Session key 约定	仍会生成 local:{defaultAccountId}:{uuid} 本地会话键	统一收敛到 ClawX 风格的 agent:{agentId}:{sessionId}
@agent 直达路由	输入框已有 Agent chip，但当前是占位能力，未接入真实 Agent 列表和主会话映射	像 ClawX 一样把下一条消息直接送到目标 Agent 的主会话
Agent/Session/Transcript	缺少完整的 Agent 配置、main session 映射、子 agent transcript 加载	对齐 ClawX 的 Agent/Session/Transcript API
执行图与子任务闭环	当前没有基于 transcript 的执行图、handoff、sub-agent 展示	对齐 ClawX 的任务执行可视化能力
Gateway 生命周期治理	当前 gateway 只是主进程 service，没有 OpenClaw 进程治理、健康检查、重连策略	对齐 ClawX 的启动、重启、健康、孤儿进程治理逻辑

4. 推荐目标架构

Vue Renderer
  ├─ src/stores/chat.ts
  ├─ src/lib/gateway-client.ts
  └─ src/lib/host-api.ts
            │
            │ IPC + Host API
            ▼
Electron Main
  ├─ GatewayManager (OpenClaw process owner)
  ├─ Host API Server (/api/gateway /api/providers /api/agents /api/sessions ...)
  ├─ Provider/Agent/Session sync layer
  └─ file stage / upload / local config bridge
            │
            │ utilityProcess + ~/.openclaw
            ▼
OpenClaw Gateway
  ├─ providers / auth profiles
  ├─ agents / sessions / transcripts
  ├─ tool use / thinking / attachments
  └─ channel / cron / skills / model routing

架构原则

1. Renderer 尽量不直接感知 OpenClaw 进程细节，只认 gateway:rpc 和 hostApiFetch。
2. zn-ai 已有聊天 UI 保留，主要做协议对齐和能力补全，不追求把 React 页面逐组件翻译成 Vue。
3. providerApiService 在过渡期作为配置真源，后续逐步演进为 “zn-ai 配置面板 <-> OpenClaw runtime config” 的双向同步桥。
4. 第一阶段只聚焦“对齐 ClawX 对话能力”，不把 ClawHub、完整 Channel UI、完整 Skills UI 一次性并入首个里程碑。

5. 目标对齐范围

5.1 P0：必须对齐的对话核心能力

• 多会话创建、切换、历史加载、删除、重命名
• 流式输出、Markdown 渲染、错误恢复、Abort
• thinking 展示开关
• 工具调用状态与工具结果归并
• 图片/文件附件发送与展示
• 默认模型选择生效
• 主进程 Gateway 自动启动、状态展示、重启

5.2 P1：推荐在首轮迁移后立即补齐

• @agent 直接路由到目标 Agent 主会话
• Agent 级 provider/model override
• Session Transcript API
• 执行图卡片与子任务可视化
• 历史轮询与 history fallback 逻辑对齐

5.3 P2：对话增强能力

• sub-agent transcript 树展示
• channel 会话历史与对话页面联动
• OpenClaw doctor / Control UI / 调试入口
• 更完整的 tool_result 文件回灌与 message-ref 展示

6. 分阶段迁移计划

阶段	目标	主要改动路径	退出标准
Phase 0：契约冻结	冻结 Chat/Gateway/Session/Agent 的目标契约，避免边做边漂移	新增本计划文档；整理 gateway:rpc、GatewayEvent、RawMessage、sessionKey 约定	所有 sub-agent 使用同一套消息模型与接口名
Phase 1：OpenClaw 运行时嵌入	在 zn-ai 中打进 openclaw、uv、必要运行时，能由主进程拉起 Gateway	zn-ai/package.json zn-ai/scripts/* zn-ai/electron/gateway/** zn-ai/electron/utils/paths.ts	开发态与打包态都能启动 OpenClaw Gateway，并能返回 health/status
Phase 2：Host API 与配置同步	把 Provider/Agent/Session/Gateway 相关接口统一落到本地主进程；建立 zn-ai -> ~/.openclaw 配置同步	zn-ai/electron/main.ts zn-ai/electron/api/** zn-ai/electron/service/provider-api-service/**	Renderer 可从本地拉到 gateway-info、providers、agents、sessions、transcripts
Phase 3：Renderer Chat Store 对齐	保留 Vue UI，改造 chat store 与 OpenClaw 事件/历史契约对齐	zn-ai/src/stores/chat.ts zn-ai/src/lib/gateway-client.ts zn-ai/src/lib/host-api.ts zn-ai/src/pages/home/model/ChatModel.ts	流式聊天、历史回灌、Abort、错误恢复、附件发送全链路稳定
Phase 4：对话 UI 对齐	补齐当前 Agent、thinking、tool cards、session sidebar、gateway 状态等体验	zn-ai/src/pages/home/ChatBox.vue zn-ai/src/pages/home/ChatHistory.vue zn-ai/src/pages/home/components/chat/*	视觉与交互能力对齐 ClawX 聊天页的核心功能
Phase 5：Agent 直达与执行图	接入 Agent 主会话映射、transcript 读取、执行图、sub-agent 展示	zn-ai/electron/api/routes/sessions.ts zn-ai/src/pages/home/components/* 新增执行图组件	至少支持一个子任务 transcript 展示与执行过程可视化
Phase 6：验收与回归	做端到端验收与回归检查，避免对脚本、任务、模型管理页面造成回归	zn-ai 测试脚本、调试脚本、文档	通过验收清单，具备对外演示条件

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 为什么推荐 2 + 5 + 1

• ClawX 与 zn-ai 的主要差距横跨“打包、主进程、Host API、配置同步、Renderer 状态机、UI、转录/执行图”七个面。
• 其中 OpenClaw runtime 嵌入 和 Renderer 对话能力对齐 之间依赖明确，但文件改动面基本可分离，适合并行。
• 如果迁移 sub-agent 少于 4，会出现“主进程迁移完成但 Renderer 无法及时接入”或“UI 已变更但 transcript/API 尚未可用”的串行瓶颈。

8. 功能迁移 sub-agent 分工方案

角色	数量	负责范围	建议文件所有权
分析 A1：ClawX/OpenClaw 契约分析	1	梳理 ClawX 的 OpenClaw runtime、Gateway、Host API、Session Transcript 契约	只读分析，不改文件
分析 A2：zn-ai 落点映射	1	梳理 zn-ai 当前可复用模块、差距、替换顺序	只读分析，不改文件
迁移 M1：Runtime/Packaging	1	嵌入 openclaw、迁移启动脚本、补 paths、补打包资源	package.json scripts/* electron/gateway/** electron/utils/paths.ts
迁移 M2：Host API/Config Sync	1	新建/迁移 Host API Server、Gateway routes、Provider/Agent/Session 同步	electron/main.ts electron/api/** electron/service/provider-api-service/**
迁移 M3：Renderer 协议与 Chat Store	1	让 Vue chat store 对齐 ClawX 的 chat.send/history/abort/session.list 与事件状态机	src/stores/chat.ts src/lib/gateway-client.ts src/lib/host-api.ts src/pages/home/model/ChatModel.ts
迁移 M4：聊天 UI/侧栏/输入框	1	侧栏会话管理、Agent picker、gateway 状态、thinking/tool/file 展示对齐	src/pages/home/ChatBox.vue src/pages/home/ChatHistory.vue src/pages/home/components/chat/*
迁移 M5：Transcript/Execution Graph	1	transcript API、执行图、sub-agent 展示、验收脚本	electron/api/routes/sessions.ts 新增执行图组件与测试/调试脚本
验收 I1：集成收口	1	联调、回归、验收 checklist、发布说明	测试与文档，不抢占前面文件所有权

8.1 并行施工波次

波次	并行 sub-agent	说明
Wave 1	A1 + A2	只读分析，同步冻结契约与边界
Wave 2	M1 + M2	一边搭 OpenClaw runtime，一边准备 Host API 与配置同步
Wave 3	M3 + M4	Runtime 和 API 基础稳定后，同时推进 store 与 UI
Wave 4	M5 + I1	接入 transcript/执行图，并完成端到端验收

8.2 依赖关系

1. M3 依赖 M2 提供稳定的 Host API/Gateway 契约。
2. M4 依赖 M3 暴露真实的 Agent/session/tool/thinking 状态。
3. M5 依赖 M2 的 session/transcript API 和 M3 的消息模型归一。
4. I1 在 M1-M5 基本完成后统一收口。

9. 推荐实施细节

9.1 优先保留的 zn-ai 资产

• src/stores/chat.ts
• src/pages/home/model/ChatModel.ts
• src/pages/home/components/chat/ChatMessage.vue
• src/pages/home/ChatHistory.vue
• src/lib/gateway-client.ts
• electron/service/provider-api-service/index.ts

这些模块的价值在于：

• 已经具备较成熟的流式状态机，不需要重新从零写一套 Vue Chat Store。
• 已经定义了与 ClawX 接近的结构化消息模型。
• 已经把 Provider 配置和默认模型选择本地化，可以作为 OpenClaw 配置同步源。

9.2 建议替换或重构的部分

• 当前 electron/gateway/manager.ts 及 handlers/chat.ts
• 当前 hostapi:fetch 里“远端后端代理优先”的混合职责
• 当前 local:{accountId}:{uuid} 会话键体系
• 当前只做占位的 Agent mention 逻辑

9.3 首个里程碑不建议纳入的范围

• ClawHub 全量迁移
• Skills 页面全量迁移
• Channels 页面全量迁移
• Cron 与对话的深度联动

原因是这几个模块都依赖 OpenClaw runtime 完整稳定，但不属于“先对齐 ClawX 对话能力”的最小闭环。

10. 风险与决策点

风险	说明	建议
远端 Host API 与本地 Host API 混用	迁移期间容易出现一部分接口走远端、一部分走本地，导致行为不一致	明确约定：OpenClaw 相关接口全部本地化，其余业务接口保留远端
Session key 不统一	local:* 与 agent:* 并存会导致历史、侧栏、Agent 路由混乱	Phase 0 就冻结统一命名规则
Provider 配置双写	zn-ai 本地配置与 ~/.openclaw 运行时配置如果不同步，会出现“设置页一套、对话页一套”	Phase 2 建立单向真源和同步策略
Vue/React 页面一比一翻译冲动	会导致迁移周期失控	只对齐能力，不对齐组件实现细节
打包态差异	OpenClaw 在开发态和打包态的路径、资源、uv/node 依赖不同	M1 单独负责 dev/package 双态验证

11. 完成验收标准

• zn-ai 可以在开发态和打包态拉起 OpenClaw Gateway。
• 聊天页默认使用本地默认模型配置，且修改默认模型后下一轮对话生效。
• 会话列表支持新建、切换、加载、删除、重命名。
• 聊天页支持流式文本、Markdown、thinking、tool cards、图片/文件附件。
• Abort、错误恢复、历史回灌稳定可用。
• @agent 能把消息送到目标 Agent 主会话，而不是仅显示占位 chip。
• 至少一个子任务 transcript 能被加载并展示为执行图或子任务明细。
• 不影响 Scripts、Tasks、模型管理页的现有主流程。

12. 与现有文档的关系

• docs/model-chat-migration-plan.md：更偏“模型对话重构”的早期版本，可继续作为 Renderer/Gateway 迁移参考。
• docs/ChatPageMigrationPlan.md：更偏聊天页面结构与 UI 迁移。
• docs/agents.md：更偏 Agent 系统分析。

本文件是上述文档的 OpenClaw 对话能力总计划整合版，适合作为后续 sub-agent 排活与里程碑跟踪的主文档。