Skip to content
Back to search

kkclaw

SkillWorks with Claude CodeGitHub

🦞 一个可爱的桌面龙虾AI助手 - Desktop lobster pet with OpenClaw AI, Edge TTS voice, and emotion animations

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/kk43994--kkclaw/badge.svg)](/listings/kk43994--kkclaw)

HTML

<a href="/listings/kk43994--kkclaw"><img src="/api/listings/kk43994--kkclaw/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

- 🎮 **RPG 游戏风格** — 木质边框 + 羊皮纸背景 + 龙虾向导角色 - 📋 **7 步引导流程** — Gateway → 模型 → 渠道 → TTS → 语音播报 → 显示 → 测试 - 🎤 **一键音色克隆** — 上传30秒录音,自动调 MiniMax/CosyVoice API 创建专属音色 - 🎭 **人设定制系统** — 5种预设风格(甜妹/专业/幽默/酷帅/自定义) - 📝 **全套文件生成** — 一键生成 `AGENTS.md` + `SOUL.md` + `USER.md` + `HEARTBEAT.md` + `desktop-bridge.js` - 🔗 **完整 AGENTS.md 模板** — 对齐生产级配置(记忆系统 + 安全规则 + 群聊规则 + 心跳检查 + 语音播报) - 🔔 **播报机制说明** — AI 回复语音不是“只要配好 TTS 就会自动朗读”。真正生效依赖 3 层:TTS 服务可用、`desktop-bridge.js` 已生成且可执行、agent 按 `AGENTS.md` 在每次回复前主动调用 `node desktop-bridge.js agent-response "要播报的内容"` - 💡 **模型兼容性提示** — 推荐 Claude Sonnet 4+ 旗舰模型获得最佳播报体验 - ✅ **7 项全链路测试** — Gateway / 模型 / TTS / 播报 / 歌词 / Agent文件 / 音色

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 82 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: kkclaw
  3. description: 给你的 AI Agent 一个桌面身体 — Setup Wizard、14情绪球体、语音克隆、歌词窗、Doctor 自检、跨平台支持(Windows + macOS)
  4. version: 3.1.2
  5. author: xiao-k-assistant
  6. tags: [desktop-pet, electron, tts, voice, emotion, openclaw, visualization, cross-platform]
  7. ---
  8. # kkclaw — 桌面龙虾 AI 伴侣
  9. 给你的 AI Agent 一个桌面身体:可视化球体 + 语音交互 + 情绪表达。
  10. ## 功能特性
  11. - 🧙 **Setup Wizard** — 首次运行引导配置,3 分钟上手
  12. - 🔐 **safeStorage 加密** — API Key 本地加密存储,不再明文
  13. - 🎭 **人设定制** — 自动生成 `AGENTS.md` / `SOUL.md` / `USER.md` / `HEARTBEAT.md`
  14. - 🎵 **声音系统** — MiniMax 声音克隆 + CosyVoice + Edge TTS 三级降级,永不失声
  15. - 👀 **情绪表达** — 14 种情绪 + 多种眼睛微表情 + 动态 glow 光效
  16. - 🩺 **Doctor 自检** — 一键诊断 Gateway / 模型 / TTS / 端口 / 日志 / 歌词窗
  17. - 🎛️ **模型管理** — Provider CRUD、模型增删、延迟测速、预设快速添加
  18. - 🧠 **Gateway 同步** — WebSocket 实时同步 OpenClaw Agent 状态,毫秒级响应
  19. - 💪 **7x24 可靠** — 自动恢复、健康评分监控、Switch Logger
  20. - 🖥️ **轻量渲染** — 纯 HTML/CSS/JS 球体,CSS radial-gradient 琉璃质感,不依赖框架
  21. - 🎤 **语音播报** — Agent 回复自动转语音,支持情感识别与停顿标记
  22. - 🖱️ **桌面集成** — 窗口置顶、鼠标穿透、拖动跟随、歌词式字幕窗口
  23. ## 技术栈
  24. - Electron(桌面容器)
  25. - OpenClaw Gateway(WebSocket 通信)
  26. - MiniMax Speech / CosyVoice / Edge TTS(语音合成)
  27. - CSS Animation + requestAnimationFrame(球体动画)
  28. ## 安装
  29. ```bash
  30. git clone https://github.com/kk43994/kkclaw.git
  31. cd kkclaw
  32. npm install
  33. npm start
  34. ```
  35. 或下载安装包:
  36. - **Windows:** https://github.com/kk43994/kkclaw/releases/download/v3.1.2/KKClaw-Desktop-Pet-3.1.2-Setup.exe
  37. - **macOS (Intel):** https://github.com/kk43994/kkclaw/releases/download/v3.1.2/KKClaw-Desktop-Pet-3.1.2-x64.dmg
  38. - **macOS (Apple Silicon):** https://github.com/kk43994/kkclaw/releases/download/v3.1.2/KKClaw-Desktop-Pet-3.1.2-arm64.dmg
  39. ## 配置
  40. 编辑 `pet-config.json` 自定义:
  41. - TTS 引擎和声音
  42. - 球体颜色和大小
  43. - OpenClaw Gateway 连接
  44. - 情绪映射规则
  45. - Setup Wizard 首次引导流程
  46. ## 目录结构
  47. ```
  48. kkclaw/
  49. ├── main.js # Electron 主进程
  50. ├── index.html # 球体渲染 UI
  51. ├── lyrics.html # 歌词字幕窗口
  52. ├── setup-wizard.html # Setup Wizard 界面
  53. ├── setup-wizard.js # Setup Wizard 逻辑
  54. ├── gateway-client.js # Gateway 通信客户端
  55. ├── smart-voice.js # 语音调度系统
  56. ├── templates/ # Agent 模板文件
  57. ├── voice/ # TTS 引擎模块
  58. ├── utils/ # 工具模块
  59. ├── scripts/ # 构建脚本
  60. └── docs-dev/ # 开发文档
  61. ```
  62. ## 链接
  63. - GitHub: https://github.com/kk43994/kkclaw
  64. - Landing Page: https://kk43994.github.io/kkclaw/
  65. - ClawHub: https://clawhub.ai/kk43994/desktop-pet
  66. - 版本: v3.1.2
README.md · README · 1,451 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # 🦞 KKClaw Desktop Pet
  2. **[English](#-english) | [中文](#-中文)**
  3. ---
  4. <a id="-中文"></a>
  5. ## 🇨🇳 中文
  6. **OpenClaw / Hermes 桌面可视化伴侣 — 流体玻璃球宠物、14情绪系统、声音克隆(MiniMax TTS)、Hermes 兼容模式、一键配置向导、Gateway 智能守护**
  7. <div align="center">
  8. ![Hero Banner](docs/images/hero-banner.png)
  9. *OpenClaw / Hermes + Desktop Embodiment = A living interface with emotion, voice, and presence*
  10. [![Version](https://img.shields.io/badge/version-3.7.1-FF6B4A?style=for-the-badge&logo=github)](https://github.com/kk43994/kkclaw/releases)
  11. [![Hermes Compatible](https://img.shields.io/badge/Hermes-Compatible-F7E7CE?style=for-the-badge)](https://github.com/NousResearch/hermes-agent)
  12. [![CI](https://img.shields.io/github/actions/workflow/status/kk43994/kkclaw/ci.yml?style=for-the-badge&logo=github-actions&logoColor=white&label=CI)](https://github.com/kk43994/kkclaw/actions/workflows/ci.yml)
  13. [![Stars](https://img.shields.io/github/stars/kk43994/kkclaw?style=for-the-badge&logo=github&color=FFD700)](https://github.com/kk43994/kkclaw/stargazers)
  14. [![Downloads](https://img.shields.io/github/downloads/kk43994/kkclaw/total?style=for-the-badge&logo=github&color=8B5CF6)](https://github.com/kk43994/kkclaw/releases)
  15. [![License](https://img.shields.io/badge/license-MIT-green?style=for-the-badge)](LICENSE)
  16. [![Platform](https://img.shields.io/badge/platform-Windows_|_macOS-0078D6?style=for-the-badge&logo=apple&logoColor=white)](https://github.com/kk43994/kkclaw)
  17. [![Electron](https://img.shields.io/badge/Electron-28.x-47848F?style=for-the-badge&logo=electron&logoColor=white)](https://www.electronjs.org/)
  18. [![Node](https://img.shields.io/badge/Node.js-18+-339933?style=for-the-badge&logo=node.js&logoColor=white)](https://nodejs.org/)
  19. [![Release](https://img.shields.io/github/v/release/kk43994/kkclaw?style=for-the-badge&color=34D399&logo=rocket&logoColor=white)](https://github.com/kk43994/kkclaw/releases/latest)
  20. [![Issues](https://img.shields.io/github/issues/kk43994/kkclaw?style=for-the-badge&logo=github&color=F97316)](https://github.com/kk43994/kkclaw/issues)
  21. [🎥 **在线演示**](https://kk43994.github.io/kkclaw/) | [📦 **下载最新版**](https://github.com/kk43994/kkclaw/releases) | [📖 **配置教程**](docs/CONFIGURATION-GUIDE.md) | [💬 **加入社群**](#-社群)
  22. </div>
  23. ---
  24. ## 🌟 项目亮点
  25. 给你的兼容后端 AI(OpenClaw / Hermes)一个**看得见、听得到**的桌面化身。
  26. ### 🦞 球体 & 动画
  27. | 功能 | 说明 |
  28. |------|------|
  29. | 🔮 **流体玻璃球** | 67px 琉璃质感球体,内部液体持续流动,宛如活物(3层流体动画 + 径向渐变 + 双重高光) |
  30. | 🌈 **14种心情变色** | 开心暖橙、伤心天蓝、生气火红……每种情绪对应独立颜色与光晕效果(14-emotion glow system) |
  31. | 👀 **38种待机微表情** | 待机时自动播放眨眼、歪头、偷瞄、打盹、星星眼、装死等表情,营造鲜活性格感(idle micro-expression engine) |
  32. | 🕐 **时间感知表情** | 早晨活力、午后困倦、深夜哈欠——自动感知当前时段并切换表情(时间场景感知:morning / noon / afternoon / evening / latenight) |
  33. | 🖱️ **鼠标跟踪眼神** | 球体眼睛跟随光标方向转动,增强互动感(mouse tracking) |
  34. | 💗 **害羞脸红** | 特定表情触发时,脸颊浮现粉色红晕(dynamic blush overlay) |
  35. | 🫧 **气泡装饰粒子** | 球体周围飘浮半透明气泡,增添灵动氛围(bubble particle decoration) |
  36. | ✨ **点击弹跳反馈** | 点击球体产生弹性压缩 + 颜色脉冲,操作有手感(squish animation + color pulse) |
  37. | 🎈 **悬浮呼吸效果** | 球体微幅上下浮动,如同水面漂浮(60fps float + breath scaling) |
  38. ### 🎙️ 声音 & 语音
  39. | 功能 | 说明 |
  40. |------|------|
  41. | 🎤 **一键声音克隆** | 上传30秒录音即可克隆声音,AI 用你自己的音色说话(MiniMax Voice Cloning API) |
  42. | 🎵 **8种预设音色** | 无需克隆,直接选择官方预设音色即可使用(8 preset voices) |
  43. | 🗣️ **14种情��语调** | 根据文本内容自动匹配情绪语气——欢快、低沉、激动等自然切换(emotion-aware TTS) |
  44. | 🔉 **智能降级链** | 主引擎故障自动切备用引擎,确保语音永不中断(MiniMax → Edge TTS 降级链) |
  45. | ⏸️ **自然停顿** | 在标点符号处自动添加语气停顿,告别机器人式朗读(TTS pause markers `<#0.5#>`) |
  46. | 📝 **桌面字幕同步** | 语音播报时同步显示逐字字幕,打字机效果呈现(typewriter lyrics overlay) |
  47. | 🔇 **消息排队播报** | 多条消息同时到达时自动排队,逐条播出不叠音(priority speech queue) |
  48. | 🚫 **重复消息过滤** | 相同内容自动去重,避免重复播报(whitespace-normalized dedup filter) |
  49. ### 🧠 人设 & 性格
  50. | 功能 | 说明 |
  51. |------|------|
  52. | 🎭 **5种性格预设** | 甜妹 / 专业 / 幽默 / 酷帅 / 自定义,一键切换说话风格(personality preset system) |
  53. | 📝 **人设文件自动生成** | 选定性格后一键生成 AI 人格档案,无需手写提示词(auto-generate AGENTS.md + SOUL.md + USER.md) |
  54. | 💬 **自定义称呼** | 自定义宠物名称和对你的称呼,如「小K叫你主人」(petName + userName 配置) |
  55. ### 🛡️ Gateway 智能守护
  56. | 功能 | 说明 |
  57. |------|------|
  58. | ⚡ **自动拉起** | 连续3次检测 Gateway 不在线后自动启动,无需手动干预(Guardian auto-start) |
  59. | 📊 **实时健康监控** | 后台持续采集 Gateway 运行指标,异常时第一时间告警(anomaly detection + health scoring) |
  60. | 🎙️ **语音状态播报** | 启动中 / 成功 / 失败均有语音通知,不必盯控制台(voice status announcement) |
  61. | 🔄 **崩溃自动重启** | Gateway 异常退出后自动拉起,每小时上限10次防止死循环(auto-restart with rate limiting) |
  62. | 🩺 **10项一键体检** | Gateway / TTS / 模型 / 端口 / 缓存 / 日志等10维一键诊断,附修复建议(Doctor self-check) |
  63. | 🔧 **双重确认防误判** | 重启前与 ServiceManager 交叉校验,避免误杀健康实例(cross-validation with ServiceManager) |
  64. | ⏳ **启动宽限期** | 首次启动60秒内不触发重启逻辑,给 Gateway 充足启动时间(startup grace period) |
  65. ### 🧙 新手引导向导
  66. | 功能 | 说明 |
  67. |------|------|
  68. | 🎮 **RPG 游戏风格** | 木质边框 + 羊皮纸纹理 + 龙虾向导 NPC + 打字机对白(RPG-style Setup Wizard) |
  69. | 📋 **7步全流程引导** | Gateway → 模型 → 消息渠道 → 语音引擎 → 播报设置 → 显示选项 → 全链路测试 |
  70. | ⚡ **缺失依赖一键安装** | 检测到缺失依赖后一键安装,实时显示安装进度(one-click dependency install + real-time progress) |
  71. | 🔍 **智能环境检测** | 自动探测 Node.js / Python / 兼容 CLI(OpenClaw)等环境状态及版本信息(smart environment detection) |
  72. | ✅ **全链路验证** | 7项端到端测试确保所有功能正常运行(end-to-end validation) |
  73. | 🐛 **错误可视化** | 向导异常时直接显示报错信息,不再白屏无提示(error visualization + crash recovery) |
  74. ### 🎨 终端 & 日志
  75. | 功能 | 说明 |
  76. |------|------|
  77. | 🌈 **彩色终端日志** | 12+ 模块统一彩色输出——模型名青色、URL绿色、错误红色,一目了然(ANSI colorized logging) |
  78. | 🔇 **日志自动去重** | 空白归一化后去重,消除控制台刷屏(whitespace-normalized dedup) |
  79. | 📁 **日志轮转归档** | 按天归档、超10MB自动压缩、保留7天历史(log rotation + gzip archiving) |
  80. | 📊 **性能实时监控** | 内存 / CPU / 帧率实时采集,超阈值自动告警(performance monitor + 24h sample history) |
  81. ### 🔁 模型切换
  82. | 功能 | 说明 |
  83. |------|------|
  84. | 🔄 **热切换** | Claude ↔ GPT ↔ Gemini ↔ DeepSeek 无需重启,3秒生效(hot model swap via CC-Switch) |
  85. | 📊 **延迟测速** | 一键对比各模型响应延迟,选择最优(latency benchmark) |
  86. | ➕ **自由添加模型** | 支持15+主流 AI 服务商,也可自定义 API 端点(custom provider + preset templates) |
  87. | 📜 **切换历史追溯** | 完整记录每次模型切换的时间与来源(switch history tracking) |
  88. | ↩️ **失败自动回滚** | 新模型5秒内无响应,自动回退到上一可用模型(optimistic update + 5s rollback) |
  89. ### 🔐 安全
  90. | 功能 | 说明 |
  91. |------|------|
  92. | 🔑 **密钥加密存储** | API Key 经 Electron safeStorage 加密后写盘,杜绝明文泄露 |
  93. | 🛡️ **IPC 权限沙箱** | 渲染进程无法直接调用系统 API,所有操作经白名单校验(IPC whitelist sandbox) |
  94. | 🧹 **日志自动脱敏** | 日志中自动遮蔽 API Key、Token 等敏感信息(log sanitizer) |
  95. | 🔒 **命令注入防护** | 所有外部命令使用参数数组传递,不拼接字符串(execFile/spawn with args array) |
  96. ### 🖥️ 桌面集成
  97. | 功能 | 说明 |
  98. |------|------|
  99. | 📌 **永远置顶** | 球体与字幕窗口始终位于最上层,不被其他窗口遮挡(always-on-top) |
  100. | 🖱️ **字幕穿透点击** | 歌词字幕窗口完全穿透鼠标事件,不影响底层操作(mouse-through transparent window) |
  101. | 🔗 **自动创建桌面快捷方式** | 首次启动自动生成桌面快捷方式,下次双击即用(auto .lnk / .app creation) |
  102. | 📸 **截图一键上传** | 工具栏一键截屏,自动上传至飞书(screenshot + Lark upload) |
  103. | 💬 **多平台消息同步** | Discord / Telegram / 飞书 / 企业微信消息统一同步并语音播报(multi-channel message sync) |
  104. | 🍎 **跨平台支持** | Windows 10/11 + macOS(Intel & Apple Silicon)双平台原生支持(cross-platform Electron) |
  105. | 📱 **托盘菜单** | 右键系统托盘即可切换模型、查看状态、启动诊断、管理会话(system tray context menu) |
  106. ### 🆕 v3.7.1 — Hermes 聊天可用性修复
  107. > 🩹 **补丁更新!** 修复 Hermes 兼容模式下两个容易误导用户的边界:没开 API server 时不再进入“能启动但不能聊”的半可用状态;只剩配置目录时也不再误判成“已安装 Hermes”。
  108. - 🔒 **聊天前置拦截** — Hermes 未启用 API server 时,Gateway 启动和桌面端发消息都会直接给出明确错误,不再继续走 `/v1/chat/completions`
  109. - ✅ **安装判定收紧** — 现在只有真正检测到 Hermes CLI 可执行文件,才会被标记为已安装
  110. - 🧪 **新增回归测试** — 增加 “残留 `~/.hermes` 目录但 CLI 缺失” 的假阳性回归测试,避免状态页再次误报
  111. ### 🆕 v3.7.0 — Hermes 兼容模式 + 多后端启动器
  112. > 🤝 **正式适配 Hermes!** `kkclaw gateway` 现在会按兼容后端模式工作:既能拉起 OpenClaw,也能驱动 Hermes,并在启动时提供 OpenClaw / Hermes / Auto 三种入口。
  113. <div align="center">
  114. <img src="docs/images/hermes-agent-banner.png" alt="Hermes Agent banner" width="100%">
  115. <p><sub>Hermes Agent banner adapted from <a href="https://github.com/NousResearch/hermes-agent">NousResearch/hermes-agent</a></sub></p>
  116. </div>
  117. - 🆕 **Hermes 兼容模式** — 支持 `KKCLAW_COMPAT_MODE=hermes`,也支持在 `pet-config.json` 中固定 `compatMode: "hermes" | "openclaw" | "auto"`
  118. - 🆕 **后端选择式启动** — `kkclaw gateway` / `npm start` 的终端入口现在会先让你选择兼容后端(OpenClaw / Hermes / Auto),并记住上次选择
  119. - 🆕 **Hermes Gateway 复用** — 如果 Hermes Gateway 已经在外部启动,KKClaw 会识别并复用,不再把它误判成端口冲突
  120. - 🔧 **诊断全面增强** — `kkclaw status` / `kkclaw doctor` / `kkclaw gateway status` 会显示当前兼容后端、CLI 路径、探活方式、日志路径、API Server 状态
  121. - 🎨 **后端感知终端外观** — 启动画面和 Ready Banner 会根据当前兼容后端切换主色和标签,终端体验更统一
  122. ### 🆕 v3.6.0 — 原生命令入口 + KKClaw Gateway CLI
  123. > 🦞 **命令体验升级!** `kkclaw gateway` 现在直接打开带开场动画的终端,并补齐 `doctor / status / logs / dashboard`
  124. - 🆕 **`kkclaw gateway` 主入口** — 直接打开现在 `npm start` 的动画终端体验,启动习惯更接近原生命令行工作流
  125. - 🆕 **`kkclaw doctor`** — 增加 KKClaw 风格体检,检查兼容 CLI、Gateway 连通性、Dashboard 地址和进程归属
  126. - 🆕 **`kkclaw gateway status / logs / open / restart / stop`** — 提供贴近兼容后端工作流的子命令
  127. - 🆕 **`kkclaw dashboard`** — 直接转发到底层 `openclaw dashboard`
  128. - 🔧 **状态可观测性增强** — `doctor` 会提示当前 Gateway 端口是否由 KKClaw 自身占用,帮助排查旧进程/端口冲突
  129. ### 🆕 v3.5.2 — Setup Wizard 修复 + 一键安装缺失依赖
  130. > ⚡ **体验优化!** Wizard 白屏修复 + 缺失依赖一键安装 + 跨平台支持
  131. - ⚡ **一键安装缺失依赖** — 环境检测页新增按钮,自动安装 edge-tts / sqlite3 / node_modules,实时进度反馈
  132. - 🔧 **跨平台安装** — Windows (winget/choco)、macOS (brew)、Linux (apt/yum)
  133. - 🐛 **Wizard 白屏修复** — 修复 3 处语法错误导致的向导空白页
  134. - 🐛 **Wizard 错误可视化** — 渲染出错时直接显示报错信息,方便用户排查
  135. - 📝 **sqlite3 依赖说明** — 标注用途 `(CC-Switch 同步)`,未安装时提示安装命令
  136. ### 🆕 v3.5.1 — 双声音修复 + 桌面快捷方式修复
  137. - 🔇 **双声音修复** — 所有 `new Notification()` 添加 `silent: true`,阻止 Windows 系统朗读
  138. - 🖥️ **快捷方式修复** — 指向 `start.cmd`,启动时显示 CMD 控制台 + Gateway 日志
  139. ### 🆕 v3.5.0 — 体验大升级:彩色终端 + 智能守护 + 桌面快捷方式
  140. > 🎨 **重大体验更新!** 全局彩色终端日志 + Gateway 智能自启动 + 日志去重降噪 + 首次启动自动创建桌面快捷方式
  141. #### 🎨 全局彩色终端日志系统
  142. - 🆕 **color-log.js 中心化模块** — 统一 ANSI 颜色常量 + 自动关键词高亮
  143. - ✨ **12+ 模块全覆盖** — main.js / service-manager / gateway-guardian / smart-voice / message-sync / pet-config / screenshot / log-rotation / performance-monitor / desktop-notifier 全部迁移
  144. - 🎯 **Gateway 日志高亮增强** — 模型名(cyan)、URL(green)、路径(dim)、渠道(magenta)、@botname(magenta)、key=value(yellow)、端口号(yellow)、协议(cyan)、错误(red)、成功(green)、警告(yellow)
  145. #### 🛡️ Gateway 智能自启动
  146. - 🆕 **首次启动主动拉起** — Guardian 不再永远等待,连续 3 次检测不到 Gateway 后自动执行 `startGateway()`
  147. - 🆕 **启动状态语音播报** — 启动中播报"等待Gateway启动中",成功/失败分别语音通知
  148. - 🔧 **二次确认防误判** — 与 ServiceManager 探活交叉校验,避免误触重启
  149. - 🔧 **启动期静默** — 首次启动阶段不发告警事件,避免噪音
  150. #### 🔇 日志去重降噪
  151. - 🔧 **修复 Gateway 日志重复** — 找到根因:`log()` 方法在 stdout handler 之后二次 `console.log()`,gateway-std* 服务跳过控制台输出
  152. - 🔧 **stderr 智能过滤** — 仅显示含 error/fatal/panic/exception 的真错误行
  153. - 🔧 **空白归一化去重** — `\s+` → `' '` 归一化后 Set 去重,彻底消除同内容重复
  154. #### 🖥️ 首次启动自动创建桌面快捷方式
  155. - 🆕 **自动创建 .lnk** — 首次启动自动在桌面创建"Claw 桌面宠物"快捷方式
  156. - 🔧 **PowerShell COM 对象** — 使用 WScript.Shell 创建快捷方式,设置图标和最小化启动
  157. - 🔧 **智能跳过** — 已存在快捷方式或非 Windows 平台自动跳过
  158. - 🎙️ **语音播报** — 创建成功后播报"桌面快捷方式已创建"
  159. #### 🔧 其他修复
  160. - 🐛 **修复语音双响** — 移除 messageSync 中重复的 `voiceSystem.speak()` 调用
  161. - 🐛 **修复通知日志重复** — desktop-notifier 只打印通知类型,不重复打印 payload
  162. - 🐛 **DashScope TTS 引擎移除** — 语音降级链简化为 MiniMax → Edge TTS
  163. ### 🆕 v3.1.2 — 安全加固 & 模型管理升级
  164. > 🔒 **安全重点更新!** 命令注入修复 + 动态 Token 管理 + 模型热切换状态机 + Gateway 智能监控
  165. #### 🧙 Setup Wizard 配置向导(全新)
  166. - 🎮 **RPG 游戏风格** — 木质边框 + 羊皮纸背景 + 龙虾向导角色
  167. - 📋 **7 步引导流程** — Gateway → 模型 → 渠道 → TTS → 语音播报 → 显示 → 测试
  168. - 🎤 **一键音色克隆** — 上传30秒录音,自动调 MiniMax/CosyVoice API 创建专属音色
  169. - 🎭 **人设定制系统** — 5种预设风格(甜妹/专业/幽默/酷帅/自定义)
  170. - 📝 **全套文件生成** — 一键生成 `AGENTS.md` + `SOUL.md` + `USER.md` + `HEARTBEAT.md` + `desktop-bridge.js`
  171. - 🔗 **完整 AGENTS.md 模板** — 对齐生产级配置(记忆系统 + 安全规则 + 群聊规则 + 心跳检查 + 语音播报)
  172. - 🔔 **播报机制说明** — AI 回复语音不是“只要配好 TTS 就会自动朗读”。真正生效依赖 3 层:TTS 服务可用、`desktop-bridge.js` 已生成且可执行、agent 按 `AGENTS.md` 在每次回复前主动调用 `node desktop-bridge.js agent-response "要播报的内容"`
  173. - 💡 **模型兼容性提示** — 推荐 Claude Sonnet 4+ 旗舰模型获得最佳播报体验
  174. - ✅ **7 项全链路测试** — Gateway / 模型 / TTS / 播报 / 歌词 / Agent文件 / 音色
  175. #### 🌈 情绪系统升级
  176. - 🌈 **7 → 14 种情绪** — 新增 sad、angry、fearful、calm、excited、love、focused
  177. - ✨ **动态外发光** — 每种情绪有专属 glow 光效
  178. - 🎭 **情绪文本检测** — `desktop-bridge.js` 自动分析内容情绪,10种匹配规则
  179. #### 🔐 安全与稳定性
  180. - 🔑 **API Key 加密存储** — `safeStorage` 加密,密钥不再明文写入磁盘
  181. - 🔒 **preload 安全沙箱** — 主窗口/歌词/诊断/模型设置全部走 IPC 白名单,渲染进程不再直接 require Node
  182. - 🎵 **歌词窗口 Ready 守卫** — `lyricsReady` 标志位,防止加载未完成时崩溃
  183. - 🔧 **sendLyric 封装** — 统一歌词推送,自动检查窗口状态
  184. - 📡 **端口持久化** — 通知端口写入配置,wizard/bridge 可动态获取
  185. - 📡 **渲染进程错误转发** — `preload-error` + `console-message` 转发到主进程日志,防止静默失败
  186. #### 🩺 诊断与运维
  187. - 🆕 **Doctor 自检系统** — 10 项全自动诊断(Gateway / 托盘 / TTS配置 / 模型 / 端口 / 健康度 / 缓存 / 歌词 / 日志),每项带修复建议
  188. - 🆕 **会话刷新** — 损坏会话一键清理重连(`doRefreshSession`)
  189. - 🔧 **诊断工具箱 UI 升级** — Doctor 面板新增 summary 统计 + 修复建议 + 分级状态(pass/warn/fail)
  190. #### 🎛️ 模型管理升级
  191. - 🆕 **延迟测速** — 单模型测速 + 全量批量测速(`speedTest` / `speedTestAll`)
  192. - 🆕 **Provider CRUD** — 新增/编辑/删除服务商,编辑 baseUrl 和 API Key
  193. - 🆕 **模型增删** — Provider 内添加/移除模型
  194. - 🆕 **预设快速添加** — 内置主流 Provider 预设模板,一键填入配置
  195. #### 🎙️ 语音系统增强
  196. - 🆕 **MiniMax Speech 2.8 HD** — 新增高清语音引擎选项
  197. - 🔄 **SmartVoice 配置统一** — 直接读 petConfig,不用重复读文件
  198. - 🎤 **完整版 desktop-bridge.js** — cleanForTTS + detectEmotion + addTTSPauseMarkers
  199. - 🎵 **歌词 TTS 标记过滤** — `<#0.3#>` 停顿标记不显示在字幕中,只给语音引擎用
  200. #### 📖 文档
  201. - 🆕 **完整配置教程** — [CONFIGURATION-GUIDE.md](docs/CONFIGURATION-GUIDE.md)(863行),从零开始手把手教学
  202. ### v2.2.1 特性
  203. - 🔧 **诊断工具箱** — 全新独立窗口,一键查看 Gateway 状态、日志、连接信息
  204. - 🔇 **CMD 屏闪修复** — 全面添加 `windowsHide: true`,彻底消除 Windows 命令行窗口闪烁
  205. ### v2.2.0 特性
  206. - 🛡️ **Gateway 错误诊断链路** — 捕获 stdout/stderr,桌面通知显示具体崩溃原因
  207. - 🔄 **安全模型切换 + 自动回滚** — 切换失败 5 秒内自动恢复上一个模型
  208. - 📊 **会话管理托盘菜单** — 查看上下文使用率、token 估算、一键清理会话
  209. - 📡 **请求追踪系统** — 序列 ID + 计时 + 错误历史(50条) + 30s 超时诊断
  210. - ⏳ **启动宽限期** — 60s 冷启动保护,防止误判重启循环
  211. - 🧠 **上下文感知** — 中英文 token 估算,接近限制时智能警告
  212. ---
  213. ## 🎬 演示视频
  214. <div align="center">
  215. ### 直接点击播放 ▶️
  216. <video width="100%" controls style="max-width: 800px; border-radius: 12px; box-shadow: 0 10px 30px rgba(0,0,0,0.2);">
  217. <source src="videos/demo.mp4" type="video/mp4">
  218. 您的浏览器不支持视频播放。<a href="https://b23.tv/85bz09G">点击查看B站版本</a>
  219. </video>
  220. **居然让 OpenClaw 给自己做了个身体!**
  221. [📱 B站视频](https://b23.tv/85bz09G) | [📱 抖音视频](https://v.douyin.com/9wKpkB8z4ew/)
  222. </div>
  223. ---
  224. ## 📦 下载安装
  225. ### 最新版本:v3.7.1
  226. <div align="center">
  227. | 平台 | 架构 | 下载链接 | 大小 |
  228. |------|------|----------|------|
  229. | 🪟 **Windows** | x64 | [KKClaw-Desktop-Pet-3.7.1-Setup.exe](https://github.com/kk43994/kkclaw/releases/download/v3.7.1/KKClaw-Desktop-Pet-3.7.1-Setup.exe) | ~150MB |
  230. | 🍎 **macOS** | Intel | [KKClaw-Desktop-Pet-3.7.1-x64.dmg](https://github.com/kk43994/kkclaw/releases/download/v3.7.1/KKClaw-Desktop-Pet-3.7.1-x64.dmg) | ~160MB |
  231. | 🍎 **macOS** | Apple Silicon | [KKClaw-Desktop-Pet-3.7.1-arm64.dmg](https://github.com/kk43994/kkclaw/releases/download/v3.7.1/KKClaw-Desktop-Pet-3.7.1-arm64.dmg) | ~160MB |
  232. [📦 查看所有版本](https://github.com/kk43994/kkclaw/releases) | [🎥 在线演示](https://kk43994.github.io/kkclaw/)
  233. </div>
  234. ### ⚠️ 推荐使用方式:克隆仓库
  235. > **建议有一定技术基础的用户直接克隆仓库运行,而非下载发行版。**
  236. >
  237. > 发行版为打包封装版本,存在以下限制:
  238. > - 部分配置已硬编码在包内,自定义修改需要解包,不适合新手
  239. > - 小版本的 bug 修复和功能更新不会单独推发行版,克隆仓库后 `git pull` 即可同步最新改动
  240. >
  241. > ```bash
  242. > git clone https://github.com/kk43994/kkclaw.git
  243. > cd kkclaw
  244. > npm install
  245. > npm start
  246. > ```
  247. >
  248. > 发行版适合只想快速体验的用户,长期使用推荐源码运行。
  249. ### 命令行入口(推荐)
  250. ```bash
  251. npm link
  252. kkclaw gateway # 打开带兼容后端选择器的 KKClaw Gateway 终端(OpenClaw / Hermes / Auto)
  253. kkclaw gateway status # 查看网关状态 / 端口 / 当前兼容后端
  254. kkclaw gateway logs # 查看 Gateway 日志
  255. kkclaw doctor # 做一轮 KKClaw 体检
  256. kkclaw dashboard # 打开当前兼容后端的 Dashboard / API 面板
  257. ```
  258. ### 安装说明
  259. #### Windows
  260. 1. 下载 `.exe` 安装程序
  261. 2. 双击运行(可能需要允许"未知发布者")
  262. 3. 按提示完成安装
  263. #### macOS
  264. 1. 下载对应架构的 `.dmg` 文件
  265. 2. 打开 DMG,拖动应用到 Applications 文件夹
  266. 3. 首次运行需要在"系统偏好设置 → 安全性与隐私"中允许
  267. > **注意**:macOS 版本未签名,首次运行需要右键点击 → "打开"
  268. ---
  269. ## 📸 预览
  270. <div align="center">
  271. ### 🎨 14种情绪色系
  272. ![Mood System](docs/images/mood-system.png)
  273. **丰富的情绪状态** — 14种颜色 × 38种表情 = 超自然的情感表达
  274. ---
  275. ### 🔧 精灵窗口 + 工具栏
  276. <table>
  277. <tr>
  278. <td width="50%">
  279. ![Pet Closeup](docs/images/pet-closeup.png)
  280. **67px 琉璃球体**
  281. - 3层流体动画
  282. - 双重高光系统
  283. - 胶囊形发光眼睛
  284. </td>
  285. <td width="50%">
  286. ![Toolbar](docs/images/toolbar.png)
  287. **SVG图标工具栏**
  288. - 💬 聊天对话
  289. - 📸 截图上传
  290. - 🎤 语音切换
  291. - ⚙️ 设置面板
  292. </td>
  293. </tr>
  294. </table>
  295. ---
  296. ### 💬 聊天交互演示
  297. ![Chat Demo](docs/images/chat-demo.png)
  298. **智能对话 + 文件操作** — 可以与桌面图标、文件进行自然语言交互
  299. *示例:KK要复制图标文件,直接用红框标记图标,用飞书语音创建快捷方式*
  300. </div>
  301. ---
  302. ## ✨ 核心功能
  303. ### 🎨 空气感双窗口设计
  304. > **设计理念**:像桌面歌词一样,不妨碍操作,却始终陪伴。
  305. #### 精灵窗口 (200×220px)
  306. - **67px 流体玻璃球** — 3层径向渐变 + 双重高光 + 内外发光
  307. - **胶囊形眼睛** (11×19px) — 15+种表情,SVG矢量
  308. - **SVG图标工具栏** — 💬聊天 / 📸截图 / 🎤语音,hover展开
  309. #### 歌词窗口 (400×100px)
  310. - **完全鼠标穿透** — `setIgnoreMouseEvents`,不挡操作
  311. - **白字描边** — `text-shadow` 8重叠加,任何背景可见
  312. - **打字机效果** — 逐字出现,支持emoji,自动换行
  313. #### 拖动同步
  314. - 拖动精灵窗口 → 歌词窗口自动跟随
  315. - IPC事件 `drag-pet` 双窗口实时同步
  316. ---
  317. ### 🎙️ 智能语音系统(三级降级)
  318. #### **主引擎:MiniMax Speech 2.5 Turbo**
  319. - **克隆音色** — 小团团导航音(`xiaotuantuan_minimax`)
  320. - **7种情感** — happy, sad, angry, fearful, disgusted, surprised, calm
  321. - **停顿控制** — `<#0.5#>` 在文本中插入自然停顿
  322. - **费用** — 2元/万字符,克隆费9.9元/音色(一次性)
  323. **自动情感识别**:
  324. ```javascript
  325. // smart-voice.js 根据文本内容自动选择emotion
  326. "太棒了!" → happy
  327. "失败了..." → sad
  328. "什么!?" → surprised
  329. ```
  330. #### **降级链**:
  331. 1. MiniMax → 2元/万字符,高质量
  332. 2. CosyVoice → DashScope API,中等质量
  333. 3. Edge TTS → 免费本地,基础质量
  334. ---
  335. ### 🔁 KKClaw Switch 模型热切换
  336. > **3秒切换AI模型,零重启,零中断**
  337. #### 工作原理
  338. ```
  339. ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
  340. │ KKClaw Switch │ → │ Auto Monitor │ → │ Compatible CLI │
  341. │ (点击切换) │ │ (每2秒检测) │ │ (自动重启) │
  342. └─────────────────┘ └─────────────────┘ └─────────────────┘
  343. ↓ ↓ ↓
  344. 切换Provider 读取DB变化 同步config → restart
  345. ```
  346. #### 功能特性
  347. ✅ **自动同步监听器** — 集成到桌面宠物生命周期
  348. - 启动时自动开启 `kkclaw-auto-sync.js`
  349. - 关闭时自动停止
  350. - 每2秒检测 `~/.cc-switch/cc-switch.db`
  351. ✅ **手动同步** (可选)
  352. ```bash
  353. node kkclaw-hotswitch.js # 同步当前provider
  354. node kkclaw-hotswitch.js --restart # 同步 + 重启Gateway
  355. ```
  356. ✅ **无缝切换**
  357. - Claude Opus 4 ↔ GPT-5.3 ↔ Gemini Pro
  358. - 3秒内生效
  359. - 不中断对话上下文
  360. ---
  361. ### 👁️ 眼睛表情系统
  362. #### 15+种基础表情
  363. | 表情 | 参数 | 效果 |
  364. |------|------|------|
  365. | **normal** | 11×19px | 正常状态 |
  366. | **blink** | 12×3px | 眨眼 |
  367. | **happy** | 13×7px, br:7px 7px 3px 3px | 开心弯眼 |
  368. | **surprised** | 13×21px | 惊讶瞪大 |
  369. | **thinking** | 10×17px, ty:-3px | 思考眯眼 |
  370. | **sleepy** | 12×4px, ty:2px | 困了半闭 |
  371. | **sparkle** | 12×12px, rot:45deg | 星星眼 |
  372. | **wink** | 左13×7px, 右11×19px | 单眼眨 |
  373. | **love** | 14×13px, br:7px 1px, rot:45deg | 爱心眼 |
  374. | **angry** | 12×14px, rot:±12deg | 生气皱眉 |
  375. | **dizzy** | 10×10px, rot:±25deg | 头晕旋转 |
  376. | **cross** | 10×3px, rot:±30deg | X眼(装死) |
  377. #### 38个待机动作序列
  378. **类型分布**:
  379. - 👀 **眼睛动画** (14个) — 左右看、上下看、眨眼、歪头
  380. - 😊 **表情组合** (12个) — 开心→惊讶、思考→闪亮、困→惊醒
  381. - 💕 **情感表达** (6个) — 害羞脸红、爱心眼、生气跺脚
  382. - 🎭 **复杂序列** (6个) — 环顾四周、开心蹦跶、装死复活
  383. **触发机制**:
  384. ```javascript
  385. setInterval(() => {
  386. if (currentMood === 'idle' && Math.random() < 0.3) {
  387. // 30%概率触发
  388. idleActs[Math.floor(Math.random() * 38)]();
  389. }
  390. }, 4000); // 每4秒检查一次
  391. ```
  392. ---
  393. ### 🎨 琉璃质感球体
  394. #### 视觉分层(由内到外)
  395. ```
  396. ┌─ 1. 内部流体层 ────────────────┐
  397. │ - blob1: 20×20px 圆形 │
  398. │ - blob2: 30×30px 椭圆 │
  399. │ - 不同速度动画(20s / 25s) │
  400. └──────────────────────────────┘
  401. ↓
  402. ┌─ 2. 玻璃外壳 ──────────────────┐
  403. │ - 3层径向渐变 │
  404. │ - 主高光 (35% 18%) │
  405. │ - 副高光 (20% 12%) │
  406. │ - 1.5px border 半透明 │
  407. └──────────────────────────────┘
  408. ↓
  409. ┌─ 3. 外部发光 ──────────────────┐
  410. │ - box-shadow 内外双层 │
  411. │ - 根据mood颜色动态变化 │
  412. └──────────────────────────────┘
  413. ```
  414. #### 颜色过渡动画
  415. **1秒平滑渐变** — 动态 `@keyframes` 生成
  416. ```javascript
  417. // 每次切换mood时动态创建过渡动画
  418. function createColorTransition(fromColor, toColor) {
  419. const keyframes = `
  420. @keyframes colorShift-${Date.now()} {
  421. from { background: ${fromColor}; }
  422. to { background: ${toColor}; }
  423. }
  424. `;
  425. // 三层独立动画:0.8s / 1.0s / 1.2s
  426. }
  427. ```
  428. ---
  429. ### 🛡️ 7×24 稳定性保障
  430. #### 自动重启机制
  431. - **Electron进程崩溃** → 5秒后自动重启
  432. - **兼容后端 Gateway 挂掉** → 30秒后自动重启
  433. - **系统资源耗尽** → 内存清理 + 重启
  434. #### 日志轮转
  435. - **每日轮转** — 保留最近7天日志
  436. - **大小限制** — 单文件10MB,超过自动归档
  437. - **分级记录** — INFO / WARN / ERROR
  438. #### 缓存管理
  439. - **自动清理** — 每24小时清理临时文件
  440. - **智能压缩** — 旧日志自动压缩为 `.gz`
  441. #### 性能监控
  442. - **CPU使用率** — 超过80%告警
  443. - **内存使用** — 超过500MB告警
  444. - **FPS监控** — 低于30fps告警
  445. ---
  446. ## 🚀 快速开始
  447. > 📖 **完整配置教程请看 → [CONFIGURATION-GUIDE.md](docs/CONFIGURATION-GUIDE.md)**
  448. >
  449. > 从环境准备到语音配置到飞书接入,一步步手把手教学,小白也能看懂!
  450. ### 前置要求
  451. - **Node.js** ≥ 18.x ([下载](https://nodejs.org))
  452. - **Windows** 10/11 或 **macOS** 10.15+
  453. - **兼容后端**:**OpenClaw** ≥ 2026.x 或 **Hermes Agent**(建议最新版本)([OpenClaw](https://openclaw.ai) | [Hermes](https://github.com/NousResearch/hermes-agent))
  454. ### 安装
  455. #### 方式一:ClawHub(推荐)
  456. ```bash
  457. npx clawhub@latest install kk43994/desktop-pet
  458. ```
  459. #### 方式二:GitHub
  460. ```bash
  461. git clone https://github.com/kk43994/kkclaw.git
  462. cd kkclaw
  463. npm install
  464. npm start
  465. ```
  466. ### 配置
  467. > 🧙 **v3.0 新增 Setup Wizard!** 首次启动会自动弹出配置向导,跟着引导走即可完成全部设置。
  468. >
  469. > 如需手动配置,参考以下步骤:
  470. 1. **复制配置模板**
  471. ```bash
  472. cp pet-config.example.json pet-config.json
  473. ```
  474. 2. **编辑 `pet-config.json`**
  475. ```json
  476. {
  477. "openclaw": {
  478. "gateway": "http://localhost:3000"
  479. },
  480. "voice": {
  481. "engine": "minimax",
  482. "minimax": {
  483. "apiKey": "sk-api--你的密钥",
  484. "groupId": "你的GroupID",
  485. "voiceId": "xiaotuantuan_minimax"
  486. }
  487. }
  488. }
  489. ```
  490. 3. **启动应用**
  491. ```bash
  492. npm start
  493. ```
  494. ---
  495. ## 📖 文档
  496. ### 项目文档
  497. - [📖 **完整配置教程**](docs/CONFIGURATION-GUIDE.md) — ⭐ 新手必看!从零开始配置
  498. - [📂 项目结构](PROJECT-STRUCTURE.md) — 目录组织、命名规范
  499. - [🎙️ 智能语音系统](docs-dev/SMART-VOICE.md) — 三级降级、情感识别
  500. - [🔁 KKClaw Switch](docs-dev/SYNC-GUIDE.md) — 模型热切换配置
  501. - [📸 截图功能](docs-dev/SCREENSHOT-FEATURE.md) — 快捷键、自动上传
  502. - [🔧 开发指南](docs-dev/SETUP-GUIDE.md) — 开发环境、调试
  503. ### 在线资源
  504. - [🎥 **在线演示**](https://kk43994.github.io/kkclaw/) — 可交互的球体demo
  505. - [📦 **ClawHub主页**](https://clawhub.ai/kk43994/desktop-pet) — 国际社区
  506. - [📦 **OpenClaw-CN**](https://clawd.org.cn) — 中文社区技能市场
  507. ---
  508. ## 🔧 配置详解
  509. ### 基础配置
  510. ```json
  511. {
  512. "openclaw": {
  513. "gateway": "http://localhost:3000",
  514. "sessionKey": "main",
  515. "checkInterval": 2000
  516. },
  517. "window": {
  518. "position": { "x": 100, "y": 100 },
  519. "alwaysOnTop": true,
  520. "opacity": 1.0
  521. }
  522. }
  523. ```
  524. ### 语音配置
  525. #### MiniMax配置
  526. ```json
  527. {
  528. "voice": {
  529. "engine": "minimax",
  530. "minimax": {
  531. "apiKey": "sk-api--xxxxx",
  532. "groupId": "2020139946483921771",
  533. "voiceId": "xiaotuantuan_minimax",
  534. "model": "speech-2.5-turbo-preview",
  535. "speed": 1.1,
  536. "vol": 3.0,
  537. "emotion": "happy"
  538. }
  539. }
  540. }
  541. ```
  542. #### DashScope(CosyVoice)配置
  543. ```json
  544. {
  545. "voice": {
  546. "engine": "dashscope",
  547. "dashscope": {
  548. "apiKey": "sk-xxxxxxxxxx",
  549. "model": "cosyvoice-v3-plus",
  550. "voice": "cosyvoice-v3-plus-tuantuan-xxx"
  551. }
  552. }
  553. }
  554. ```
  555. #### 语音播报的最小链路
  556. 上面这一步只是把 TTS 服务配置好,它并不等于 AI 回复时一定会自动播报。真正能听到声音,还要同时满足下面 3 层:
  557. - TTS 服务本身可用
  558. - `desktop-bridge.js` 已生成,并且能在当前 workspace 正常执行
  559. - 当前 agent / 模型真的遵循 `AGENTS.md`,在每次回复前主动执行:`node desktop-bridge.js agent-response "要播报的内容"`
  560. 如果你已经配好了 TTS,但 AI 回复还是完全没有声音,优先怀疑的就不只是配置问题,也可能是当前 agent 根本没有触发 bridge。
  561. ### KKClaw Switch配置
  562. 桌面宠物会自动集成,无需额外配置。
  563. 如需手动同步:
  564. ```bash
  565. # 同步当前 provider 到兼容后端配置
  566. node kkclaw-hotswitch.js
  567. # 同步并重启Gateway
  568. node kkclaw-hotswitch.js --restart
  569. ```
  570. ---
  571. ## 🛠️ 开发
  572. ### 目录结构
  573. ```
  574. desktop-pet/
  575. ├── main.js # Electron主进程
  576. ├── index.html # 精灵窗口UI
  577. ├── lyrics.html # 歌词窗口UI
  578. ├── setup-wizard.html # 🧙 Setup Wizard UI(RPG风格)
  579. ├── setup-wizard.js # 🧙 Setup Wizard 后端逻辑
  580. ├── setup-preload.js # 🧙 Wizard IPC 安全桥接
  581. ├── smart-voice.js # 智能语音调度
  582. ├── pet-config.js # 🔐 配置管理(含 safeStorage 加密)
  583. ├── voice/ # TTS引擎目录
  584. │ ├── minimax-tts.js
  585. │ ├── dashscope-tts.js
  586. │ └── cosyvoice-tts.py
  587. ├── templates/ # 🧙 向导模板文件
  588. │ └── desktop-bridge.js # 语音播报桥接模板
  589. ├── utils/ # 辅助工具目录
  590. ├── scripts/ # 工具脚本
  591. ├── tests/ # 测试文件
  592. ├── docs-dev/ # 开发文档
  593. └── archive/ # 归档旧版本
  594. ```
  595. ### 开发命令
  596. ```bash
  597. npm start # 启动应用
  598. npm run dev # 开发模式(热重载)
  599. npm run console # 打开系统终端并运行 npm start
  600. npm test # 运行测试
  601. npm run build # 构建发布版
  602. ```
  603. ### 调试
  604. 1. **开启Electron DevTools**
  605. - 主窗口:`Ctrl + Shift + I`
  606. - 或修改 `main.js` 添加 `mainWindow.webContents.openDevTools()`
  607. 2. **查看日志**
  608. ```bash
  609. # 实时日志
  610. tail -f logs/app.log
  611. # 错误日志
  612. tail -f logs/error.log
  613. ```
  614. ---
  615. ## 🤝 贡献
  616. 欢迎贡献代码、报告Bug、提出建议!
  617. ### 贡献方式
  618. 1. **Fork** 本仓库
  619. 2. 创建分支 `git checkout -b feature/新功能`
  620. 3. 提交更改 `git commit -m 'Add: 新功能描述'`
  621. 4. 推送分支 `git push origin feature/新功能`
  622. 5. 提交 **Pull Request**
  623. ### 代码规范
  624. - 使用 **kebab-case** 命名文件
  625. - 添加 **详细注释**
  626. - 遵循 **ESLint** 规则
  627. - 测试覆盖 **核心功能**
  628. ---
  629. ## 🐛 故障排查
  630. ### 常见问题
  631. #### 1. 球体不显示
  632. **原因**:窗口位置超出屏幕
  633. **解决**:删除 `pet-config.json` 中的 `window.position`,重启应用
  634. #### 2. 语音不播报
  635. **可能原因**:
  636. - API密钥无效或配置错误
  637. - `desktop-bridge.js` 没生成、路径不对,或者当前 workspace 下不可执行
  638. - 当前 agent / 模型没有遵循 `AGENTS.md`,根本没有在回复前触发 `desktop-bridge.js`
  639. **解决**:
  640. ```bash
  641. # 检查配置
  642. node -e "console.log(require('./pet-config.json').voice)"
  643. # 测试MiniMax API
  644. node voice/minimax-tts.js
  645. # 手动测试 bridge -> 桌面端播报链路
  646. node desktop-bridge.js agent-response "这是一次 README 排障测试播报"
  647. ```
  648. **排障判断技巧**:
  649. - 如果手动执行 `desktop-bridge.js` 能播报,说明 TTS / bridge 基本正常,问题更可能出在 agent 没有执行播报命令
  650. - 如果手动执行也没有声音,再优先排查 TTS 配置、bridge 文件位置和运行环境
  651. #### 3. 兼容后端连接失败
  652. **原因**:Gateway 未启动、后端未运行或端口错误
  653. **解决**:
  654. ```bash
  655. # 检查兼容 CLI / 后端状态
  656. openclaw status
  657. # 启动Gateway
  658. openclaw gateway start
  659. ```
  660. #### 4. KKClaw Switch不同步
  661. **原因**:
  662. - `~/.cc-switch/cc-switch.db` 不存在
  663. - 自动监听器未启动
  664. **解决**:
  665. ```bash
  666. # 检查DB文件
  667. ls ~/.cc-switch/cc-switch.db
  668. # 手动同步
  669. node kkclaw-hotswitch.js --restart
  670. ```
  671. ---
  672. ## 📊 性能指标
  673. | 指标 | 目标 | 实测 |
  674. |------|------|------|
  675. | **启动时间** | <3秒 | 2.1秒 |
  676. | **内存占用** | <200MB | 147MB |
  677. | **CPU占用** | <5% | 2.8% |
  678. | **帧率** | ≥60fps | 60fps |
  679. | **语音延迟** | <500ms | 320ms |
  680. *测试环境:Windows 11, i7-12700K, 32GB RAM*
  681. ---
  682. ## 📝 更新日志
  683. ### [3.7.1] - 2026-04-14
  684. #### 🩹 Hermes 兼容补丁
  685. - Hermes 未启用 API server 时,Gateway 启动和桌面端聊天现在会直接阻断,并明确提示开启 `API_SERVER_ENABLED=true`
  686. - Hermes 已安装判定从“配置目录存在”收紧为“CLI 可执行文件存在”,避免假阳性
  687. - 新增 “残留 `~/.hermes` 目录但 Hermes CLI 缺失” 的回归测试
  688. ### [3.7.0] - 2026-04-11
  689. #### 🤝 Hermes 兼容模式
  690. - 新增 Hermes 兼容后端,支持 `KKCLAW_COMPAT_MODE` 环境变量和 `pet-config.json.compatMode` 配置
  691. - `kkclaw gateway` / `npm start` 新增兼容后端(OpenClaw / Hermes / Auto)选择式启动,并记住上次选择
  692. - 如果 Hermes Gateway 已在外部运行,KKClaw 会识别并复用,不再误报端口冲突
  693. #### 🔍 诊断与启动体验
  694. - `kkclaw status` / `kkclaw doctor` / `kkclaw gateway status` 现在会显示当前兼容后端、CLI 路径、探活方式、日志路径、API Server 状态
  695. - 启动 Banner 和 Ready Banner 改为后端感知:OpenClaw 为红色主题,Hermes 为香槟金主题
  696. - `kkclaw dashboard` 与主进程网关配置会自动切换到当前兼容后端
  697. #### 🧪 测试与文档
  698. - 新增后端选择启动器、Hermes 兼容模式、外部 Hermes Service 复用相关测试
  699. - README 和语音开发文档补充了 AI 回复语音播报的真实触发链路说明
  700. ### [3.6.0] - 2026-04-02
  701. #### 🦞 KKClaw CLI
  702. - 新增 `kkclaw` 命令入口,支持 `kkclaw gateway`
  703. - `kkclaw gateway` / `kkclaw gateway start` 直接打开带开场动画的终端(当前 `npm start` 体验)
  704. - 新增 `kkclaw gateway status / logs / open / restart / stop`
  705. - 新增 `kkclaw doctor` 和顶层 `kkclaw status`
  706. #### 🔍 诊断与可观测性
  707. - `kkclaw doctor` 增加 Gateway ownership 检查,能发现端口被旧进程或外部实例占用
  708. - `kkclaw gateway status` 增加 Dashboard 地址、日志路径、兼容 CLI(OpenClaw)版本和进程摘要
  709. - `kkclaw gateway logs` 支持查看标准日志 / 错误日志并设置 tail 行数
  710. ### [3.5.2] - 2026-03-12
  711. #### ⚡ 一键安装缺失依赖
  712. - ⚡ **环境检测页新增按钮** — 自动安装 edge-tts / sqlite3 / node_modules,实时进度反馈
  713. - 🔧 **跨平台安装** — Windows (winget/choco)、macOS (brew)、Linux (apt/yum)
  714. #### 🐛 修复
  715. - 修复 Setup Wizard 白屏 — 3 处函数声明缺失导致 SyntaxError
  716. - Wizard 错误可视化 — 渲染出错时显示具体报错
  717. - sqlite3 依赖说明优化 — 标注 `(CC-Switch 同步)` 用途
  718. ### [3.5.1] - 2026-03-12
  719. #### 🐛 修复
  720. - 修复双声音问题 — 所有 `new Notification()` 添加 `silent: true`
  721. - 修复桌面快捷方式不显示 CMD — 指向 `start.cmd`,WindowStyle 1
  722. - 移除 `speak()` 临时调试日志
  723. ### [3.5.0] - 2026-03-12
  724. #### 🎨 全局彩色终端日志
  725. - 🆕 **color-log.js** — 中心化 ANSI 颜色模块,统一颜色常量 + 自动高亮函数
  726. - ✨ **全面迁移** — 12+ 模块启动日志迁移到 `colorLog()` / `kvLog()` / `tagLog()`
  727. - ✨ **Gateway 日志高亮增强** — 模型名、URL、路径、渠道、@botname、key=value、端口号、协议、错误/成功/警告 全彩高亮
  728. #### 🛡️ Gateway 智能自启动
  729. - 🆕 **首次启动主动拉起** — 连续 3 次检测不到 Gateway 后自动 `startGateway()`,不再永远等待
  730. - 🆕 **启动状态语音播报** — 启动中/成功/失败 分别语音通知
  731. - 🔧 **二次确认防误判** — 与 ServiceManager 交叉校验
  732. #### 🔇 日志去重降噪
  733. - 🔧 **修复 Gateway 日志重复** — 根因:`log()` 二次打印;gateway-std* 跳过控制台输出
  734. - 🔧 **stderr 智能过滤** — 仅显示 error/fatal/panic/exception
  735. - 🔧 **空白归一化去重** — `\s+` → `' '` 归一化后 Set 去重
  736. #### 🖥️ 首次启动自动创建桌面快捷方式
  737. - 🆕 **自动创建 .lnk** — 首次启动自动在桌面创建"Claw 桌面宠物"快捷方式
  738. - 🔧 **PowerShell COM** — WScript.Shell 创建快捷方式
  739. - 🎙️ **语音播报** — 创建成功后播报
  740. #### 🐛 修复
  741. - 修复语音双响(移除 messageSync 重复 speak)
  742. - 修复通知日志重复(desktop-notifier 只打印类型)
  743. - DashScope TTS 引擎移除,降级链简化为 MiniMax → Edge TTS
  744. ### [3.1.2] - 2026-03-11
  745. #### 🔒 安全加固
  746. - 🔧 **命令注入修复** — `_playAudioFile()` / `_playAudio()` / `speakWithEdgeTTS()` 全部从 `exec()` shell 拼接改为 `execFile()` / `spawn()` + 参数数组
  747. - 🔧 **Edge TTS 文本注入修复** — 文本通过临时文件 `--text-file` 传入,不再 inline `--text` 拼接
  748. - 🔧 **stop() 真正停止播放** — 跟踪当前播放进程引用,`stop()` 时 `.kill()` 终止
  749. - ✨ **Token 动态读取** — `openclaw-client.js` 不再模块加载时缓存 token,改用 `SecureStorage` + `configManager` 动态获取
  750. - ✨ **IPC 校验模块** — 新增 `ipc-validator.js`,渠道白名单校验
  751. - ✨ **日志脱敏** — 新增 `log-sanitizer.js`,防止敏感信息写入日志
  752. #### 🎛️ 模型管理升级
  753. - ✨ **模型热切换状态机** — `model-switch-state-machine.js`,状态驱动的切换流程
  754. - ✨ **切换策略模式** — `model-switch-strategies.js`,可扩展的切换策略
  755. - ✨ **切换历史记录** — `switch-history.js`,追踪模型切换轨迹
  756. - ✨ **额度查询** — `quota-query.js`,查询 API 余额
  757. - ✨ **CC Switch 同步** — `cc-switch-sync.js`,Claude Code 模型同步切换
  758. #### 🛡️ Gateway 智能监控
  759. - ✨ **异常检测器** — `gateway-anomaly-detector.js`,自动识别异常模式
  760. - ✨ **健康评分** — `gateway-health-scorer.js`,多维度健康度量化
  761. - ✨ **指标采集器** — `gateway-metrics-collector.js`,实时采集 Gateway 指标
  762. - ✨ **智能检测器** — `gateway-smart-detector.js`,智能故障诊断
  763. #### 🏗️ 架构优化
  764. - ✨ **路径解析器** — `openclaw-path-resolver.js`,消除硬编码路径
  765. - ✨ **安全配置加载** — `safe-config-loader.js`,带校验的配置读取
  766. - ✨ **安全存储** — `secure-storage.js`,token 安全管理
  767. - ✨ **会话锁管理器** — `session-lock-manager.js`,并发安全的会话操作
  768. - ✨ **配置管理器** — `config-manager.js` + `config-writer.js`,统一配置读写
  769. - ✨ **Setup Wizard 独立 preload** — `setup-preload.js`,最小化权限暴露
  770. - ✨ **Model Settings 分离** — CSS/JS 从 HTML 中独立为 `model-settings.css` + `model-settings.js`
  771. ### [3.0.0] - 2026-02-22
  772. #### 🧙 Setup Wizard — 一键配置向导(全新)
  773. - ✨ **RPG 游戏风格引导界面** — 木质边框 + 羊皮纸背景 + 龙虾向导 + 打字机文字效果
  774. - ✨ **7 步引导流程** — Gateway 连接 → AI 模型 → 消息渠道 → TTS 引擎 → Agent 语音 → 显示 → 全链路测试
  775. - ✨ **一键音色克隆** — 拖拽上传录音文件,自动调用 MiniMax / CosyVoice API 克隆音色
  776. - ✨ **人设定制系统** — 宠物昵称 + 用户称呼 + 5 种说话风格预设(甜妹/专业/幽默/酷帅/自定义)
  777. - ✨ **全套 Agent 配置文件自动生成**:
  778. - `AGENTS.md` — 完整工作手册(记忆系统 + 安全规则 + 群聊规则 + 心跳检查 + 语音播报规则)
  779. - `SOUL.md` — Agent 人设文件(根据选择的风格自动生成)
  780. - `USER.md` — 用户信息框架
  781. - `HEARTBEAT.md` — 心跳检查配置
  782. - `desktop-bridge.js` — 语音播报桥接脚本(完整版,含 cleanForTTS + detectEmotion + addTTSPauseMarkers)
  783. - ✨ **语音播报是如何触发的?**
  784. - 第 1 层:TTS 引擎本身要可用(MiniMax / Edge TTS / 其他降级链正常)
  785. - 第 2 层:`desktop-bridge.js` 要已经生成,并且在当前 workspace 里可执行
  786. - 第 3 层:agent / 模型必须真的遵循 `AGENTS.md`,在每次回复前主动执行:`node desktop-bridge.js agent-response "要播报的内容"`
  787. - **少了第 3 层时,哪怕 TTS 配置完全正确,也可能一声不响。**
  788. - ✨ **7 项全链路测试** — Gateway / AI模型 / TTS引擎 / 语音播报 / 桌面歌词 / Agent配置文件 / 自定义音色
  789. - ✨ **模型兼容性提示** — 注明不同模型的指令遵循度差异,推荐 Claude Sonnet 4+
  790. - ✨ **preload 安全白名单** — 所有 IPC 通道经白名单校验,防止恶意调用
  791. #### 🌈 情绪系统大升级
  792. - ✨ **14 种情绪色系** — 原有 7 种 + 新增 sad(天蓝)、angry(烈焰红)、fearful(紫罗兰)、calm(薄荷青)、excited(热粉)、love(珊瑚)、focused(青蓝)
  793. - ✨ **动态外发光 (glow)** — 每种情绪有专属外发光效果
  794. - ✨ **10 种文本情绪检测规则** — 自动分析内容情绪:thinking → surprised → fearful → sad → angry → calm → excited → happy
  795. #### 🔐 安全与稳定性
  796. - ✨ **API Key 加密存储** — 使用 Electron `safeStorage` 加密 MiniMax/DashScope 密钥,磁盘上不再明文
  797. - ✨ **preload 安全沙箱** — 新增 `preload.js`,主窗口/歌词/诊断/模型设置全部走 IPC 白名单校验
  798. - ✨ **歌词窗口 Ready 守卫** — `lyricsReady` 标志位,歌词窗口未加载完不发消息,防崩溃
  799. - ✨ **sendLyric() 封装** — 统一歌词推送逻辑,自动检查窗口是否已销毁
  800. - ✨ **通知端口持久化** — 实际端口写入 petConfig,wizard / bridge 可动态读取
  801. - ✨ **渲染进程错误转发** — `preload-error` + `console-message` 事件转发到主进程日志
  802. #### 🩺 诊断与运维
  803. - ✨ **Doctor 自检系统** — `diag-doctor` IPC,10 项全自动诊断(Gateway / 系统托盘 / TTS 配置 / API Key / 模型配置 / 端口占用 / 健康评分 / 缓存大小 / 歌词窗口 / 日志目录),每项带修复建议
  804. - ✨ **会话刷新** — `doRefreshSession()` 一键清理损坏会话并重连
  805. - ✨ **诊断工具箱 UI 升级** — Doctor 面板新增 summary 统计条 + 修复建议 + pass/warn/fail 分级显示
  806. #### 🎛️ 模型管理升级
  807. - ✨ **延迟测速** — 单模型测速 `speedTest()` + 全量批量测速 `speedTestAll()`
  808. - ✨ **Provider CRUD** — 新增/编辑/删除服务商(`model-update-provider` / `model-remove-provider`)
  809. - ✨ **模型增删** — Provider 内添加/移除模型(`model-add-model` / `model-remove-model`)
  810. - ✨ **预设快速添加** — 内置主流 Provider 预设模板(`model-presets`),一键填入配置
  811. #### 🎙️ 语音系统增强
  812. - ✨ **MiniMax Speech 2.8 HD 引擎** — 新增高清语音选项
  813. - 🔧 **SmartVoiceSystem 配置统一** — 接受 petConfig 参数,直接读内存配置,不再重复读文件
  814. - 🔧 **desktop-bridge.js 完整版** — TTS 停顿标记、文本清理、情绪检测三合一
  815. - 🔧 **歌词 TTS 标记过滤** — `<#0.3#>` 停顿标记不显示在字幕中,只给语音引擎用
  816. #### 📖 文档
  817. - ✨ **完整配置教程** — 新增 [CONFIGURATION-GUIDE.md](docs/CONFIGURATION-GUIDE.md)(863行),从环境准备到语音配置到飞书接入,手把手教学
  818. #### 🔧 修复
  819. - 🐛 修复 `_testAgentVoice` 协议不匹配(`{action,text}` → `{type,payload:{content}}`)
  820. - 🐛 修复 `wizard-clone-voice` 未加入 preload 白名单导致克隆报错
  821. - 🐛 修复 Step 6 Agent 文件检测路径错误(`~/.openclaw` → 实际工作目录)
  822. - 🐛 修复 Footer 初始文本 `Step 1/6` → `Step 1/7`
  823. - 🐛 修复 `desktop-bridge.js` 模板字符串嵌套导致正则表达式转义错误(改为读取 `templates/` 文件)
  824. ### [2.2.1] - 2026-02-19
  825. #### 新增
  826. - 🔧 **诊断工具箱** — 独立窗口,一键查看 Gateway 状态、日志、连接诊断
  827. - 🔇 **CMD 屏闪彻底修复** — 全部 exec/spawn 调用添加 `windowsHide: true` + `shell: false`
  828. #### 优化
  829. - 🎤 smart-voice 所有 PowerShell 播放命令静默化
  830. - 🔄 openclaw-updater 全流程(版本检查/安装/doctor)静默执行
  831. - 📸 截图系统进程隐藏
  832. - 🔔 auto-notify 桌面通知静默化
  833. - 🛡️ service-manager Gateway 进程管理改用 `shell: false`
  834. ---
  835. ### [2.1.0] - 2026-02-13
  836. #### 🎉 重大更新
  837. - ✨ **完整 macOS 支持** — Intel 和 Apple Silicon 双架构
  838. - 🤖 **GitHub Actions 自动化** — 推送 tag 自动构建发布
  839. - 📦 **跨平台打包** — DMG 安装器 + ZIP 便携版
  840. - 🔄 **自动发布流程** — electron-builder 直接发布到 GitHub Release
  841. #### 技术改进
  842. - 🔧 跳过代码签名配置(Windows + macOS)
  843. - 📦 升级 GitHub Actions artifacts 到 v4
  844. - 🔐 配置完整的 GitHub Actions 权限
  845. - 🎨 生成 macOS 专用 .icns 图标文件
  846. #### 文档更新
  847. - 📖 README 增加下载安装章节
  848. - 🌐 GitHub Pages 更新双平台支持
  849. - 📋 完善跨平台安装说明
  850. ---
  851. ### [2.0.4] - 2026-02-10
  852. #### 新增
  853. - ✨ KKClaw Switch自动同步集成
  854. - ✨ 7种情绪色系完整实现
  855. - ✨ 38个待机表情动画
  856. - ✨ 琉璃质感球体升级(3层高光)
  857. - ✨ 粉红龙虾球图标 + 桌面快捷方式
  858. #### 优化
  859. - 🎨 颜色过渡动画(1秒平滑)
  860. - 🎙️ MiniMax TTS情感自动识别
  861. - 🗂️ 项目目录重构(140→31个根文件)
  862. - 📖 README全面改版 + 实际截图展示
  863. #### 修复
  864. - 🐛 多余closing div标签(GitHub Pages)
  865. - 🐛 lark-uploader引用路径
  866. - 🐛 语音播放重复问题
  867. [查看完整更新日志](CHANGELOG.md)
  868. ---
  869. ## 💬 社群
  870. ### 加入我们
  871. <div align="center">
  872. | 平台 | 链接 | 说明 |
  873. |------|------|------|
  874. | 💬 **AI Coding 交流群** | [扫码加入](docs/images/ai-coding-qr.jpg) | 微信群(7天有效) |
  875. | 🐦 **Discord** | [Friends of the Crustacean](https://discord.com/invite/clawd) | OpenClaw国际社区 |
  876. | 🇨🇳 **OpenClaw-CN** | [clawd.org.cn](https://clawd.org.cn) | 中文论坛 |
  877. | 📦 **ClawHub** | [clawhub.ai](https://clawhub.ai/kk43994/desktop-pet) | 技能市场 |
  878. | 💡 **GitHub Discussions** | [讨论区](https://github.com/kk43994/kkclaw/discussions) | 提问、分享 |
  879. </div>
  880. ### 支持项目
  881. 如果这个项目帮助了你,欢迎:
  882. - ⭐ **Star** 本仓库
  883. - 🐛 **报告Bug** 或提需求
  884. - 📢 **分享**给朋友
  885. - ☕ [**赞赏支持**](docs/images/support-qr.jpg)
  886. ---
  887. ## 📜 开源协议
  888. [MIT License](LICENSE) © 2024-2026 KK
  889. ---
  890. <a id="-english"></a>
  891. ## 🇬🇧 English
  892. **Desktop visualization companion for OpenClaw / Hermes — Fluid glass orb pet, 14-emotion system, voice cloning (MiniMax TTS), Hermes compatibility mode, Setup Wizard, and Smart Gateway Guardian**
  893. <div align="center">
  894. ![Hero Banner](docs/images/hero-banner.png)
  895. [![Version](https://img.shields.io/badge/version-3.7.1-FF6B4A?style=for-the-badge&logo=github)](https://github.com/kk43994/kkclaw/releases)
  896. [![Hermes Compatible](https://img.shields.io/badge/Hermes-Compatible-F7E7CE?style=for-the-badge)](https://github.com/NousResearch/hermes-agent)
  897. [![License](https://img.shields.io/badge/license-MIT-green?style=for-the-badge)](LICENSE)
  898. [![Platform](https://img.shields.io/badge/platform-Windows_|_macOS-0078D6?style=for-the-badge&logo=apple&logoColor=white)](https://github.com/kk43994/kkclaw)
  899. [🎥 **Live Demo**](https://kk43994.github.io/kkclaw/) | [📦 **Download**](https://github.com/kk43994/kkclaw/releases) | [📖 **Docs**](docs/CONFIGURATION-GUIDE.md) | [💬 **Community**](#-社群)
  900. </div>
  901. ### ✨ Highlights
  902. Give your compatible-backend AI (OpenClaw / Hermes) a **visible, audible** desktop embodiment.
  903. #### 🦞 Orb & Animation
  904. | Feature | Description |
  905. |---------|-------------|
  906. | 🔮 **Living Glass Orb** | 67px glass sphere with fluid constantly flowing inside, looks alive (3-layer fluid animation + radial gradient + dual highlights) |
  907. | 🌈 **14 Mood Colors** | Happy = warm orange, sad = sky blue, angry = fire red… auto-switches color and glow per mood (14-emotion glow system) |
  908. | 👀 **38 Micro-Expressions** | Blinks, tilts, peeks, dozes, sparkle eyes, plays dead while idle… like it has a personality (idle micro-expression engine) |
  909. | 🕐 **Time-Aware Expressions** | Energetic in morning, sleepy in afternoon, yawning late at night — it knows what time it is (time scene awareness: morning / noon / afternoon / evening / latenight) |
  910. | 🖱️ **Eye Tracking** | Eyes follow your cursor direction as you move the mouse (mouse tracking) |
  911. | 💗 **Blushing** | Certain expressions trigger pink blush on both cheeks (dynamic blush overlay) |
  912. | 🫧 **Floating Bubbles** | Semi-transparent bubbles floating around the orb for extra liveliness (bubble particle decoration) |
  913. | ✨ **Bounce on Click** | Click the orb and it squishes + flashes color, satisfying feedback (squish animation + color pulse) |
  914. | 🎈 **Breathing Float** | Orb gently bobs up and down, like floating on water (60fps float + breath scaling) |
  915. #### 🎙️ Voice & Audio
  916. | Feature | Description |
  917. |---------|-------------|
  918. | 🎤 **30s Voice Cloning** | Upload a 30-second recording, AI speaks in your voice (MiniMax Voice Cloning API) |
  919. | 🗣️ **14 Auto Tone Shifts** | Happy news = cheerful voice, sad news = subdued voice, auto-detected (emotion-aware TTS) |
  920. | 🔉 **Never Goes Silent** | Primary engine down → auto-switches to backup → then free fallback, always has a voice (MiniMax → Edge TTS fallback chain) |
  921. | ⏸️ **Natural Pauses** | Pauses at commas and periods, not robotic read-aloud (TTS pause markers `<#0.5#>`) |
  922. | 📝 **Desktop Subtitles** | Words pop up on screen in sync with speech, like karaoke (typewriter lyrics overlay) |
  923. | 🔇 **No Overlapping Speech** | Multiple messages arrive at once? Queued and spoken one by one (priority speech queue) |
  924. Voice playback is bridge-triggered, not purely automatic. In practice, you need all three layers to be healthy:
  925. 1. TTS is available
  926. 2. `desktop-bridge.js` exists and can run
  927. 3. The active agent actually follows `AGENTS.md` and calls `node desktop-bridge.js agent-response "..."` before replying
  928. If layer 3 is missing, the desktop pet may stay silent even though your TTS setup looks correct.
  929. #### 🧠 Persona & Personality
  930. | Feature | Description |
  931. |---------|-------------|
  932. | 🎭 **5 Personality Presets** | Sweet / Professional / Humorous / Cool / Custom — pick one and it talks that way (personality preset system) |
  933. | 📝 **Auto-Generated Persona Files** | One click generates the AI's "character sheet", no manual prompt writing (auto-generate AGENTS.md + SOUL.md + USER.md) |
  934. | 💬 **Name Your Pet** | Give it a name and set what it calls you, e.g. "Kiki calls you Boss" (petName + userName config) |
  935. #### 🛡️ Gateway Guardian
  936. | Feature | Description |
  937. |---------|-------------|
  938. | ⚡ **Auto-Restart on Crash** | Detects Gateway not running and auto-starts it for you (Guardian auto-start, triggers after 3 consecutive detection failures) |
  939. | 📊 **Live Health Monitoring** | Continuously monitors Gateway health, alerts you at first sign of trouble (anomaly detection + health scoring) |
  940. | 🎙️ **Voice Status Reports** | "Starting…", "Success!", "Failed!" — spoken aloud so you don't have to watch the console (voice status announcement) |
  941. | 🔄 **Crash Auto-Recovery** | Auto-restarts after crash, max 10 times per hour to prevent infinite loops (auto-restart with rate limiting) |
  942. | 🩺 **10-Point Health Check** | Gateway / TTS / Model / Port / Cache / Logs — one-click diagnosis with fix suggestions (Doctor self-check) |
  943. | 🔧 **Safe Guard** | Double-confirms before restart to avoid killing a healthy Gateway (cross-validation with ServiceManager) |
  944. #### 🧙 Setup Wizard
  945. | Feature | Description |
  946. |---------|-------------|
  947. | 🎮 **RPG-Style UI** | Wood frames + parchment background + lobster guide + typewriter dialogue, feels like an RPG game (RPG-style Setup Wizard) |
  948. | 📋 **7 Steps, Fully Configured** | Gateway → Model → Channels → TTS Engine → Voice Settings → Display → End-to-End Test |
  949. | ⚡ **One-Click Install Missing Deps** | Missing something? One button auto-installs with live progress bar (one-click dependency install + real-time progress) |
  950. | 🔍 **Auto Environment Detection** | Auto-finds Node.js, Python, the compatibility CLI (OpenClaw), etc. — installed or not, version at a glance (smart environment detection) |
  951. | ✅ **Full Validation at the End** | 7 checks ensure everything works before you start, no hidden issues (end-to-end validation) |
  952. #### 🎨 Terminal & Logs
  953. | Feature | Description |
  954. |---------|-------------|
  955. | 🌈 **Colorized Console** | Different info in different colors: model names blue, URLs green, errors red — easy to scan (ANSI colorized logging, 12+ modules) |
  956. | 🔇 **Auto Log Dedup** | Same message won't spam your console, keeps output clean (whitespace-normalized dedup) |
  957. | 📁 **Auto Log Archiving** | Old logs archived daily, compressed over 10MB, kept for 7 days (log rotation + gzip archiving) |
  958. | 📊 **Real-Time Perf Monitoring** | Memory, CPU, FPS at your fingertips, auto-alerts when thresholds exceeded (performance monitor + 24h sample history) |
  959. #### 🔁 Model Switching
  960. | Feature | Description |
  961. |---------|-------------|
  962. | 🔄 **One-Click AI Brain Swap** | Claude ↔ GPT ↔ Gemini ↔ DeepSeek, no restart needed, 3 seconds (hot model swap via CC-Switch) |
  963. | 📊 **AI Speed Test** | One-click latency benchmark for each model, pick the fastest (latency benchmark) |
  964. | ➕ **Add Your Own Models** | 15+ mainstream AI providers supported, or enter your own API endpoint (custom provider + preset templates) |
  965. | 📜 **Switch History** | Records every model switch — what, when, fully traceable (switch history tracking) |
  966. #### 🔐 Security
  967. | Feature | Description |
  968. |---------|-------------|
  969. | 🔑 **Encrypted Key Storage** | API keys encrypted before writing to disk, never plaintext (Electron safeStorage encryption) |
  970. | 🛡️ **Permission Control** | Pages can't directly call system functions, all operations go through whitelist (IPC whitelist sandbox) |
  971. | 🧹 **Auto Log Sanitization** | API keys, tokens auto-hidden from logs (log sanitizer) |
  972. #### 🖥️ Desktop Integration
  973. | Feature | Description |
  974. |---------|-------------|
  975. | 📌 **Always on Top** | Orb and subtitles stay on top of all windows, never hidden (always-on-top) |
  976. | 🖱️ **Click-Through Subtitles** | Lyric subtitles are fully click-through, never block what's underneath (mouse-through transparent window) |
  977. | 🔗 **Auto Desktop Shortcut** | First launch auto-creates desktop shortcut, double-click to start next time (auto .lnk / .app creation) |
  978. | 📸 **One-Click Screenshot Upload** | Toolbar screenshot button, auto-captures and uploads to Lark (screenshot + Lark upload) |
  979. | 💬 **Multi-Platform Message Sync** | Discord / Telegram / Lark / WeCom messages all synced for voice readout (multi-channel message sync) |
  980. | 🍎 **Win + Mac Support** | Windows 10/11 and macOS (Intel & Apple Silicon) both supported (cross-platform Electron) |
  981. | 📱 **Tray Menu Control Center** | Right-click tray icon to switch models, check status, run diagnostics, manage sessions (system tray context menu) |
  982. ### 🆕 What's New in v3.7.1
  983. > 🩹 **Patch release!** Tightens Hermes compatibility so KKClaw no longer reports a half-working chat setup when the Hermes API server is off, and no longer treats a leftover `~/.hermes` directory as a valid install.
  984. - 🔒 **Chat readiness guard** — KKClaw now blocks Gateway startup and desktop chat sends when Hermes API server support is disabled
  985. - ✅ **Stricter install detection** — Hermes is only considered installed when the CLI executable is actually present
  986. - 🧪 **Regression coverage** — Added a test for the “leftover config directory but missing CLI” false-positive case
  987. ### 🆕 What's New in v3.7.0
  988. > 🤝 **Official Hermes compatibility!** `kkclaw gateway` now works in a compatibility-backend mode, so it can drive OpenClaw or Hermes with a launch-time selector for OpenClaw / Hermes / Auto.
  989. <div align="center">
  990. <img src="docs/images/hermes-agent-banner.png" alt="Hermes Agent banner" width="100%">
  991. <p><sub>Hermes Agent banner adapted from <a href="https://github.com/NousResearch/hermes-agent">NousResearch/hermes-agent</a></sub></p>
  992. </div>
  993. - 🆕 **Hermes compatibility mode** — Supports `KKCLAW_COMPAT_MODE=hermes` plus a persistent `compatMode` setting in `pet-config.json`
  994. - 🆕 **Backend-aware launcher** — `kkclaw gateway` / `npm start` now lets you choose a compatible backend (OpenClaw / Hermes / Auto) and remembers the last backend you launched
  995. - 🆕 **External Hermes reuse** — If Hermes Gateway is already running, KKClaw recognizes and reuses it instead of flagging a false ownership conflict
  996. - 🔧 **Deeper diagnostics** — `kkclaw status` / `kkclaw doctor` / `kkclaw gateway status` now surface backend, CLI path, probe source, log paths, and Hermes API server readiness
  997. - 🎨 **Backend-themed console banners** — Startup and ready banners switch labels and accent colors for the active compatible backend
  998. ### 🆕 What's New in v3.6.0
  999. > 🦞 **Native command workflow!** `kkclaw gateway` now opens the same animated console as `npm start`, with companion commands for status, logs, doctor, and dashboard access
  1000. - 🆕 **`kkclaw gateway` entrypoint** — Opens the animated KKClaw terminal and makes startup feel closer to a native CLI workflow
  1001. - 🆕 **`kkclaw doctor`** — Adds a KKClaw-oriented health check for the compatibility CLI, Gateway reachability, Dashboard URL, and process ownership
  1002. - 🆕 **Gateway subcommands** — `status / logs / open / restart / stop` bring a more familiar command surface
  1003. - 🔧 **Gateway ownership diagnostics** — Detects when the Gateway port is alive but owned by an older or external process
  1004. ### 🆕 What's New in v3.5.2
  1005. > ⚡ **UX polish!** Wizard blank page fix + One-click missing dependency installer + Cross-platform support
  1006. - ⚡ **One-click Install Missing Deps** — Auto-install edge-tts / sqlite3 / node_modules with real-time progress
  1007. - 🔧 **Cross-platform Install** — Windows (winget/choco), macOS (brew), Linux (apt/yum)
  1008. - 🐛 **Wizard Blank Page Fix** — Fixed 3 syntax errors causing empty wizard content
  1009. - 🐛 **Wizard Error Visualization** — Shows error details instead of blank page for easier debugging
  1010. - 🔇 **Dual Audio Fix** (v3.5.1) — All `new Notification()` use `silent: true` to prevent Windows narration
  1011. - 🖥️ **Shortcut Fix** (v3.5.1) — Desktop shortcut now targets `start.cmd` to show CMD console
  1012. > 🎨 **Major UX update!** Global colorized terminal logs + Smart Gateway auto-start + Log dedup & noise reduction + Auto desktop shortcut on first launch
  1013. #### 🎨 Global Colorized Terminal Logs
  1014. - 🆕 **color-log.js** — Centralized ANSI color module with auto-keyword highlighting
  1015. - ✨ **12+ modules migrated** — All startup logs use `colorLog()` / `kvLog()` / `tagLog()`
  1016. - 🎯 **Enhanced Gateway log highlighting** — Models(cyan), URLs(green), paths(dim), channels(magenta), @botname(magenta), key=value(yellow), ports(yellow), protocols(cyan), errors(red), success(green), warnings(yellow)
  1017. #### 🛡️ Smart Gateway Auto-Start
  1018. - 🆕 **Proactive first launch** — Guardian auto-starts Gateway after 3 consecutive failures instead of waiting forever
  1019. - 🆕 **Voice status announcements** — "Waiting for Gateway" / success / failure spoken aloud
  1020. - 🔧 **Cross-validation** — Double-checks with ServiceManager to prevent false restarts
  1021. #### 🔇 Log Dedup & Noise Reduction
  1022. - 🔧 **Fixed Gateway log duplication** — Root cause: `log()` method double-printing; gateway-std* services skip console output
  1023. - 🔧 **Smart stderr filtering** — Only show lines with error/fatal/panic/exception
  1024. - 🔧 **Whitespace-normalized dedup** — `\s+` → `' '` normalization before Set dedup
  1025. #### 🖥️ Auto Desktop Shortcut
  1026. - 🆕 **Auto-create .lnk on first launch** — Creates "Claw 桌面宠物" shortcut on desktop
  1027. - 🔧 **PowerShell COM** — WScript.Shell shortcut creation with icon and minimized start
  1028. - 🎙️ **Voice announcement** — "Desktop shortcut created" on success
  1029. #### 🐛 Fixes
  1030. - Fixed dual audio playback (removed duplicate `voiceSystem.speak()` from messageSync)
  1031. - Fixed duplicate notification logs (desktop-notifier only logs type)
  1032. - Removed DashScope TTS engine, simplified fallback: MiniMax → Edge TTS
  1033. ### 🚀 Quick Start
  1034. #### Prerequisites
  1035. - **Node.js** ≥ 18.x ([Download](https://nodejs.org))
  1036. - **Windows** 10/11 or **macOS** 10.15+
  1037. - **Compatible backend**: **OpenClaw** ≥ 2026.x or **Hermes Agent** (latest recommended) ([OpenClaw](https://openclaw.ai) | [Hermes](https://github.com/NousResearch/hermes-agent))
  1038. #### Install via ClawHub (Recommended)
  1039. ```bash
  1040. npx clawhub@latest install kk43994/desktop-pet
  1041. ```
  1042. #### Install from GitHub
  1043. ```bash
  1044. git clone https://github.com/kk43994/kkclaw.git
  1045. cd kkclaw
  1046. npm install
  1047. npm start
  1048. ```
  1049. > 🧙 **Setup Wizard** will launch automatically on first run — just follow the guide!
  1050. #### CLI Entry (Recommended)
  1051. ```bash
  1052. npm link
  1053. kkclaw gateway # Open the backend-aware KKClaw terminal with a compatible backend selector (OpenClaw / Hermes / Auto)
  1054. kkclaw gateway status # Show gateway state, port, and active compatible backend
  1055. kkclaw gateway logs # Tail gateway logs
  1056. kkclaw doctor # Run a KKClaw-oriented health check
  1057. kkclaw dashboard # Open the active backend dashboard / API surface
  1058. ```
  1059. ### 📦 Downloads
  1060. | Platform | Arch | Download | Size |
  1061. |----------|------|----------|------|
  1062. | 🪟 **Windows** | x64 | [Setup.exe](https://github.com/kk43994/kkclaw/releases/download/v3.7.1/KKClaw-Desktop-Pet-3.7.1-Setup.exe) | ~150MB |
  1063. | 🍎 **macOS** | Intel | [x64.dmg](https://github.com/kk43994/kkclaw/releases/download/v3.7.1/KKClaw-Desktop-Pet-3.7.1-x64.dmg) | ~160MB |
  1064. | 🍎 **macOS** | Apple Silicon | [arm64.dmg](https://github.com/kk43994/kkclaw/releases/download/v3.7.1/KKClaw-Desktop-Pet-3.7.1-arm64.dmg) | ~160MB |
  1065. [📦 All Releases](https://github.com/kk43994/kkclaw/releases)
  1066. ### 🤝 Contributing
  1067. 1. **Fork** this repo
  1068. 2. Create branch `git checkout -b feature/your-feature`
  1069. 3. Commit `git commit -m 'Add: feature description'`
  1070. 4. Push `git push origin feature/your-feature`
  1071. 5. Open a **Pull Request**
  1072. ### 📜 License
  1073. [MIT License](LICENSE) © 2024-2026 KK
  1074. ---
  1075. ## 🙏 致谢
  1076. - [OpenClaw](https://openclaw.ai) — 强大的AI助手框架
  1077. - [Electron](https://www.electronjs.org) — 跨平台桌面应用框架
  1078. - [MiniMax](https://www.minimaxi.com) — 高质量语音克隆API
  1079. - [Nomi](https://nomi.ai) & [AIBI](https://aibi.com) — UI设计灵感
  1080. - [Bunny Hole](https://bunnyhole.com) — 眼睛设计参考
  1081. ---
  1082. <div align="center">
  1083. **用❤️打造 by KK**
  1084. [🔝 回到顶部](#-kkclaw-desktop-pet)
  1085. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.