zclaw_openfang/desktop/NEXT_SESSION_PROMPT.md

ZCLAW Desktop 新会话提示词

当前状态

已完成的工作 (2026-03-14)

1. ZCLAW 连接适配 ✅

   • ZCLAW Desktop 已成功连接 ZCLAW (端口 50051)
   • 对话功能测试通过，AI 响应正常

2. WebSocket 流式聊天 ✅ (新完成)

   • 实现了 chatStream() 方法支持流式响应
   • 添加了 onDelta, onTool, onHand, onComplete, onError 回调
   • Vite 代理已启用 WebSocket 支持 (ws: true)
   • chatStore 优先使用流式 API，REST API 作为 fallback

3. 动态 Agent 选择 ✅ (新完成)

   • 添加了 setDefaultAgentId() 和 getDefaultAgentId() 方法
   • loadClones 时自动设置第一个可用 Agent 为默认

关键修改

文件	修改内容
gateway-client.ts	添加 chatStream(), cancelStream(), setDefaultAgentId()
chatStore.ts	sendMessage 优先使用流式 API
gatewayStore.ts	loadClones 自动设置默认 Agent
vite.config.ts	启用 WebSocket 代理

ZCLAW vs OpenClaw 协议差异

方面	OpenClaw	ZCLAW
端口	18789	50051
聊天 API	/api/chat	/api/agents/{id}/message
WebSocket	/ (单一连接)	/api/agents/{id}/ws (流式)
连接方式	WebSocket 握手	REST API 健康检查

运行环境

• ZCLAW: ~/.zclaw/ (config.toml, .env)
• OpenClaw: ~/.openclaw/ (openclaw.json, devices/)
• ZCLAW 前端: http://localhost:1420 (Vite)
• 默认 Agent: 动态获取第一个可用 Agent

localStorage 配置

localStorage.setItem('zclaw-backend', 'zclaw');
localStorage.setItem('zclaw_gateway_url', 'ws://127.0.0.1:50051/ws');

---

待完成工作

优先级 P1 - 功能完善

1. Hands 面板 - UI 已存在，需要验证 API 连接
2. Workflow 管理 - UI 已存在，需要验证 API 连接
3. 审计日志 - Merkle 哈希链审计查看

优先级 P2 - 优化

4. 后端切换优化 - 代理配置应动态切换 (OpenClaw: 18789, ZCLAW: 50051)
5. 错误处理 - 更友好的错误提示
6. 连接状态显示 - 显示 ZCLAW 版本号

---

快速启动命令

# 启动 ZCLAW
cd "desktop/src-tauri/resources/zclaw-runtime" && ./zclaw.exe start

# 启动 Vite 开发服务器
cd desktop && pnpm dev

# 检查 ZCLAW 状态
./zclaw.exe status

# 测试 API
curl http://127.0.0.1:50051/api/health
curl http://127.0.0.1:50051/api/agents

---

关键文件路径

文件	用途
desktop/src/lib/gateway-client.ts	Gateway 通信客户端 (WebSocket + REST)
desktop/src/store/gatewayStore.ts	Gateway 状态管理
desktop/src/store/chatStore.ts	聊天状态管理
desktop/src/components/Settings/General.tsx	后端切换设置
desktop/vite.config.ts	Vite 代理配置
docs/zclaw-technical-reference.md	ZCLAW 技术文档

---

新会话起始提示

请继续 ZCLAW Desktop 的开发工作。

当前状态：
- ZCLAW REST API 聊天已可用 ✅
- WebSocket 流式聊天已实现 ✅
- 动态 Agent 选择已实现 ✅

首要任务建议：
1. 验证 Hands/Workflow 面板 API 连接
2. 实现审计日志面板
3. 优化后端切换逻辑