iven/zclaw_openfang
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
b8a83b5a26b1aedef21423c8859a63eacc772416
zclaw_openfang/docs/NEXT_SESSION.md
iven ef849c62ab cc工作前备份
2026-03-12 00:23:42 +08:00

9.4 KiB
Raw Blame History

ZCLAW v2 开发 - 新会话提示词

项目状态概览

ZCLAW v2 是基于 OpenClaw 的定制化 AI Agent 平台（类似 AutoClaw/QClaw），使用 Tauri 2.0 桌面 + OpenClaw Gateway 架构。

当前进度: Phase 1-3.5 已完成 ✅
下一步: Phase 4 - OpenClaw 真实集成测试（QQ官方插件 + 飞书）

Phase 1-3 已完成工作

✅ Phase 1: 后端 Gateway 层 + 插件 + Skills

  • src/gateway/ — GatewayManager (子进程管理), GatewayWsClient (WebSocket Protocol v3)
  • plugins/zclaw-chinese-models/ — 智谱GLM/通义千问/Kimi/MiniMax Provider 插件
  • plugins/zclaw-feishu/ — 飞书 Channel 插件 (OAuth token 管理 + 消息发送)
  • plugins/zclaw-ui/ — UI 扩展 RPC (分身CRUD/统计/配置/工作区)
  • skills/ — chinese-writing + feishu-docs (SKILL.md 格式)
  • config/ — openclaw.default.json + SOUL/AGENTS/IDENTITY/USER.md
  • scripts/setup.ts — 首次设置脚本 (检测OpenClaw → 复制配置 → 注册插件)

✅ Phase 2: 前端 Settings 页面体系

  • desktop/src/components/Settings/ — 10个设置页面对标 AutoClaw
    • SettingsLayout (左侧导航 + 右侧内容)
    • General, UsageStats, ModelsAPI, MCPServices, Skills, IMChannels, Workspace, Privacy, About
  • App.tsx — main/settings 视图切换
  • 构建修复 — Tailwind v4, BOM 清除, TypeScript 0 errors

✅ Phase 3: 聊天对接 + 分身管理

  • desktop/src/store/chatStore.ts — Gateway WS 集成 (sendMessage → agent RPC, initStreamListener → delta/tool/lifecycle)
  • desktop/src/components/ChatArea.tsx — 流式输出 + 工具调用展示 + 模型选择器 + 连接状态
  • desktop/src/components/CloneManager.tsx — 分身 CRUD (创建表单 + 列表 + 删除)
  • desktop/src/components/Sidebar.tsx — 3标签 (分身/IM频道/定时任务) + CloneManager 集成

✅ Phase 3.5: 前端质量提升

  • App.tsx — Gateway 自动连接 (启动时 silent connect)
  • RightPanel.tsx — 重写为实时数据面板 (连接状态/会话统计/分身/用量/插件/系统信息)
  • ChatArea.tsx — 多行 textarea 输入 + Markdown 渲染 (代码块/粗体/斜体/链接) + 新对话按钮
  • chatStore.ts — 对话会话管理 + Zustand persist (localStorage 持久化对话历史 + currentModel)
  • ConversationList.tsx (新) — 对话历史列表 + 标题自动提取 + 相对时间
  • Sidebar.tsx — 四标签 (对话/分身/频道/任务), 全部使用真实组件
  • ChannelList.tsx (新) — IM 频道列表 (飞书/QQ 状态探测 + 配置入口)
  • TaskList.tsx (新) — Heartbeat 定时任务列表 (状态图标/cron 表达式/执行时间)
  • gatewayStore.ts — 新增 channels/scheduledTasks 状态 + loadChannels/loadScheduledTasks
  • gateway-client.ts — 新增 listChannels() + getFeishuStatus() + listScheduledTasks()
  • Settings/General.tsx — 接入真实 Gateway 连接数据 + 连接/断开按钮
  • Settings/ModelsAPI.tsx — 接入 chatStore 模型切换 + Gateway 连接状态

编译状态: TypeScript 0 errors, Vite build ✅ (1766 modules, 268KB JS + 26KB CSS)

Phase 4: OpenClaw 集成测试 (下一步工作)

重要提示：避免封号

前期只对接 QQ (官方插件) 和 飞书，微信暂缓。

任务清单

1. 安装 OpenClaw

# Windows
iwr -useb https://openclaw.ai/install.ps1 | iex

# 验证安装
openclaw --version
openclaw doctor

2. 配置 QQ 机器人 (使用官方插件)

# 安装 OpenClaw 开源社区 QQBot 插件
openclaw plugins install @tencent-connect/openclaw-qqbot@latest

# 配置绑定 QQ 机器人
openclaw channels add --channel qqbot --token "1903376513:Z5UkttjPxLZbVFxW"

# 重启 Gateway
openclaw gateway restart

3. 配置飞书 Channel

# 运行 ZCLAW 设置脚本
cd g:\ZClaw
pnpm setup

# 手动配置飞书插件 (如果 setup 脚本未自动注册)
openclaw plugins register ./plugins/zclaw-feishu

# 编辑 ~/.openclaw/openclaw.json 添加飞书配置
# channels.feishu.appId, appSecret, verificationToken, encryptKey

4. 注册 ZCLAW 自定义插件

cd g:\ZClaw

# 注册中文模型 Provider
openclaw plugins register ./plugins/zclaw-chinese-models

# 注册 UI 扩展 RPC
openclaw plugins register ./plugins/zclaw-ui

# 重启 Gateway
openclaw gateway restart

5. 测试 Gateway 连接

# 启动 Gateway (如果未运行)
openclaw gateway

# 在另一个终端启动 ZCLAW 前端
cd g:\ZClaw\desktop
pnpm dev

# 访问 http://localhost:1420
# 点击右下角齿轮 → 设置 → 通用 → 查看 Gateway 连接状态

6. 测试中文模型调用

  • 在聊天区域发送消息
  • 点击模型选择器切换到 glm-5 / qwen3.5-plus / kimi-k2.5 / minimax-m2.5
  • 观察流式输出效果
  • 检查工具调用是否正常显示

7. 测试飞书消息收发

  • 在飞书中 @机器人 发送消息
  • 观察 Gateway 日志和前端消息列表
  • 测试从前端发送消息到飞书

8. 测试 QQ 消息收发

  • 在 QQ 中 @机器人 发送消息
  • 观察 Gateway 日志
  • 测试双向消息流

关键文件路径

配置文件

  • g:\ZClaw\config\openclaw.default.json — OpenClaw 默认配置模板
  • ~\.openclaw\openclaw.json — OpenClaw 用户配置 (运行时生成)
  • g:\ZClaw\config\SOUL.md — ZCLAW 人格定义

插件目录

  • g:\ZClaw\plugins\zclaw-chinese-models\ — 中文模型 Provider
  • g:\ZClaw\plugins\zclaw-feishu\ — 飞书 Channel
  • g:\ZClaw\plugins\zclaw-ui\ — UI 扩展 RPC

前端代码

  • g:\ZClaw\desktop\src\store\gatewayStore.ts — Gateway 状态管理
  • g:\ZClaw\desktop\src\store\chatStore.ts — 聊天状态管理
  • g:\ZClaw\desktop\src\lib\gateway-client.ts — Gateway WebSocket 客户端

后端代码

  • g:\ZClaw\src\gateway\manager.ts — Gateway 子进程管理
  • g:\ZClaw\src\gateway\ws-client.ts — Node.js WebSocket 客户端

常见问题排查

Gateway 连接失败

  1. 检查 Gateway 是否运行: openclaw status
  2. 检查端口占用: netstat -ano | findstr 18789
  3. 查看 Gateway 日志: openclaw gateway (前台运行查看输出)
  4. 检查防火墙设置

插件未加载

  1. 验证插件注册: openclaw plugins list
  2. 检查插件 manifest: g:\ZClaw\plugins\*/plugin.json
  3. 查看 Gateway 启动日志中的插件加载信息
  4. 确认 ~\.openclaw\openclaw.json 中 plugins.load.paths 包含插件路径

飞书消息收发失败

  1. 检查 openclaw.json 中飞书配置 (appId, appSecret, verificationToken)
  2. 验证 OAuth token 是否有效: 查看 Gateway 日志中的 token 刷新记录
  3. 检查飞书机器人权限配置
  4. 确认回调 URL 配置正确

QQ 消息收发失败

  1. 验证 QQBot 插件安装: openclaw plugins list | findstr qqbot
  2. 检查 token 格式: "botAppId:token"
  3. 查看 Gateway 日志中的 QQ 连接状态
  4. 确认 QQ 机器人已启用并在线

开发命令速查

# 后端 (Gateway 层)
cd g:\ZClaw
pnpm install
pnpm setup              # 运行设置脚本
pnpm build              # 编译 TypeScript
npx tsc --noEmit        # 类型检查

# 前端 (Tauri Desktop)
cd g:\ZClaw\desktop
pnpm install
pnpm dev                # 启动 Vite dev server (http://localhost:1420)
pnpm build              # 构建生产版本
npx tsc --noEmit        # 类型检查

# OpenClaw 命令
openclaw gateway                    # 启动 Gateway (前台)
openclaw gateway restart            # 重启 Gateway
openclaw status                     # 查看状态
openclaw doctor                     # 诊断工具
openclaw plugins list               # 列出已安装插件
openclaw plugins install <pkg>      # 安装插件
openclaw plugins register <path>    # 注册本地插件
openclaw channels add --channel <type> --token <token>  # 添加 IM 频道
openclaw configure                  # 交互式配置

参考文档

  • 架构设计: g:\ZClaw\docs\architecture-v2.md
  • 偏离分析: g:\ZClaw\docs\deviation-analysis.md
  • 进度报告: g:\ZClaw\PROGRESS.md
  • AutoClaw 界面参考: g:\ZClaw\docs\autoclaw界面\ (13张截图)

预期成果

完成 Phase 4 后，应达到以下状态：

  1. ✅ OpenClaw Gateway 正常运行并连接到前端
  2. ✅ QQ 机器人可以收发消息 (使用官方 @tencent-connect/openclaw-qqbot 插件)
  3. ✅ 飞书机器人可以收发消息 (使用自定义 zclaw-feishu 插件)
  4. ✅ 中文模型 (GLM/Qwen/Kimi/MiniMax) 可以正常调用
  5. ✅ 前端聊天区域显示流式输出 + 工具调用
  6. ✅ 分身管理功能正常 (创建/列表/删除)
  7. ✅ Settings 页面所有配置项可用

注意事项

  1. 避免封号: 前期只对接 QQ (官方插件) 和飞书，微信暂缓
  2. QQ 使用官方插件: @tencent-connect/openclaw-qqbot@latest，不要自己实现
  3. 飞书使用自定义插件: plugins/zclaw-feishu/ 已实现 OAuth + 消息发送
  4. API Key 安全: 不要在代码中硬编码 API Key，使用 openclaw configure 或环境变量
  5. Gateway 日志: 前台运行 openclaw gateway 可以实时查看日志，便于调试
  6. 插件热重载: 修改插件代码后需要 openclaw gateway restart

后续 Phase 5 规划

  • Tauri Rust sidecar (在 Tauri 中管理 Gateway 子进程)
  • 更多 Skills 开发 (代码生成、文档写作、数据分析等)
  • 微信 Channel Plugin (待 OpenClaw 官方支持或社区插件成熟后)
  • 打包发布 (Windows/macOS/Linux)
  • 性能优化 + 错误处理增强