{"id":44496309,"url":"https://github.com/kk43994/kkclaw","last_synced_at":"2026-04-14T12:02:26.114Z","repository":{"id":336836295,"uuid":"1151333973","full_name":"kk43994/kkclaw","owner":"kk43994","description":"🦞 一个可爱的桌面龙虾AI助手 - Desktop lobster pet with OpenClaw AI, Edge TTS voice, and emotion animations","archived":false,"fork":false,"pushed_at":"2026-04-02T17:30:26.000Z","size":25228,"stargazers_count":149,"open_issues_count":5,"forks_count":29,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-04-03T02:56:37.493Z","etag":null,"topics":["ai-assistant","desktop-pet","electron","lobster","openclaw","tts","voice-clone"],"latest_commit_sha":null,"homepage":"https://kk43994.github.io/KKClaw-Desktop-Pet/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kk43994.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-06T10:36:49.000Z","updated_at":"2026-04-02T17:30:32.000Z","dependencies_parsed_at":null,"dependency_job_id":"7b9cc649-6ffe-4763-bbc2-f696140d7272","html_url":"https://github.com/kk43994/kkclaw","commit_stats":null,"previous_names":["kk43994/claw-desktop-pet","kk43994/kkclaw-desktop-pet","kk43994/kkclaw"],"tags_count":15,"template":true,"template_full_name":null,"purl":"pkg:github/kk43994/kkclaw","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kk43994%2Fkkclaw","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kk43994%2Fkkclaw/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kk43994%2Fkkclaw/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kk43994%2Fkkclaw/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kk43994","download_url":"https://codeload.github.com/kk43994/kkclaw/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kk43994%2Fkkclaw/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31795334,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-14T11:13:53.975Z","status":"ssl_error","status_checked_at":"2026-04-14T11:13:53.299Z","response_time":153,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-assistant","desktop-pet","electron","lobster","openclaw","tts","voice-clone"],"created_at":"2026-02-13T05:26:44.522Z","updated_at":"2026-04-14T12:02:26.101Z","avatar_url":"https://github.com/kk43994.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🦞 KKClaw Desktop Pet\n\n**[English](#-english) | [中文](#-中文)**\n\n---\n\n\u003ca id=\"-中文\"\u003e\u003c/a\u003e\n\n## 🇨🇳 中文\n\n**OpenClaw / Hermes 桌面可视化伴侣 — 流体玻璃球宠物、14情绪系统、声音克隆（MiniMax TTS）、Hermes 兼容模式、一键配置向导、Gateway 智能守护**\n\n\u003cdiv align=\"center\"\u003e\n\n![Hero Banner](docs/images/hero-banner.png)\n\n*OpenClaw / Hermes + Desktop Embodiment = A living interface with emotion, voice, and presence*\n\n[![Version](https://img.shields.io/badge/version-3.7.1-FF6B4A?style=for-the-badge\u0026logo=github)](https://github.com/kk43994/kkclaw/releases)\n[![Hermes Compatible](https://img.shields.io/badge/Hermes-Compatible-F7E7CE?style=for-the-badge)](https://github.com/NousResearch/hermes-agent)\n[![CI](https://img.shields.io/github/actions/workflow/status/kk43994/kkclaw/ci.yml?style=for-the-badge\u0026logo=github-actions\u0026logoColor=white\u0026label=CI)](https://github.com/kk43994/kkclaw/actions/workflows/ci.yml)\n[![Stars](https://img.shields.io/github/stars/kk43994/kkclaw?style=for-the-badge\u0026logo=github\u0026color=FFD700)](https://github.com/kk43994/kkclaw/stargazers)\n[![Downloads](https://img.shields.io/github/downloads/kk43994/kkclaw/total?style=for-the-badge\u0026logo=github\u0026color=8B5CF6)](https://github.com/kk43994/kkclaw/releases)\n[![License](https://img.shields.io/badge/license-MIT-green?style=for-the-badge)](LICENSE)\n[![Platform](https://img.shields.io/badge/platform-Windows_|_macOS-0078D6?style=for-the-badge\u0026logo=apple\u0026logoColor=white)](https://github.com/kk43994/kkclaw)\n[![Electron](https://img.shields.io/badge/Electron-28.x-47848F?style=for-the-badge\u0026logo=electron\u0026logoColor=white)](https://www.electronjs.org/)\n[![Node](https://img.shields.io/badge/Node.js-18+-339933?style=for-the-badge\u0026logo=node.js\u0026logoColor=white)](https://nodejs.org/)\n[![Release](https://img.shields.io/github/v/release/kk43994/kkclaw?style=for-the-badge\u0026color=34D399\u0026logo=rocket\u0026logoColor=white)](https://github.com/kk43994/kkclaw/releases/latest)\n[![Issues](https://img.shields.io/github/issues/kk43994/kkclaw?style=for-the-badge\u0026logo=github\u0026color=F97316)](https://github.com/kk43994/kkclaw/issues)\n\n[🎥 **在线演示**](https://kk43994.github.io/kkclaw/) | [📦 **下载最新版**](https://github.com/kk43994/kkclaw/releases) | [📖 **配置教程**](docs/CONFIGURATION-GUIDE.md) | [💬 **加入社群**](#-社群)\n\n\u003c/div\u003e\n\n---\n\n## 🌟 项目亮点\n\n给你的兼容后端 AI（OpenClaw / Hermes）一个**看得见、听得到**的桌面化身。\n\n### 🦞 球体 \u0026 动画\n\n| 功能 | 说明 |\n|------|------|\n| 🔮 **流体玻璃球** | 67px 琉璃质感球体，内部液体持续流动，宛如活物（3层流体动画 + 径向渐变 + 双重高光） |\n| 🌈 **14种心情变色** | 开心暖橙、伤心天蓝、生气火红……每种情绪对应独立颜色与光晕效果（14-emotion glow system） |\n| 👀 **38种待机微表情** | 待机时自动播放眨眼、歪头、偷瞄、打盹、星星眼、装死等表情，营造鲜活性格感（idle micro-expression engine） |\n| 🕐 **时间感知表情** | 早晨活力、午后困倦、深夜哈欠——自动感知当前时段并切换表情（时间场景感知：morning / noon / afternoon / evening / latenight） |\n| 🖱️ **鼠标跟踪眼神** | 球体眼睛跟随光标方向转动，增强互动感（mouse tracking） |\n| 💗 **害羞脸红** | 特定表情触发时，脸颊浮现粉色红晕（dynamic blush overlay） |\n| 🫧 **气泡装饰粒子** | 球体周围飘浮半透明气泡，增添灵动氛围（bubble particle decoration） |\n| ✨ **点击弹跳反馈** | 点击球体产生弹性压缩 + 颜色脉冲，操作有手感（squish animation + color pulse） |\n| 🎈 **悬浮呼吸效果** | 球体微幅上下浮动，如同水面漂浮（60fps float + breath scaling） |\n\n### 🎙️ 声音 \u0026 语音\n\n| 功能 | 说明 |\n|------|------|\n| 🎤 **一键声音克隆** | 上传30秒录音即可克隆声音，AI 用你自己的音色说话（MiniMax Voice Cloning API） |\n| 🎵 **8种预设音色** | 无需克隆，直接选择官方预设音色即可使用（8 preset voices） |\n| 🗣️ **14种情��语调** | 根据文本内容自动匹配情绪语气——欢快、低沉、激动等自然切换（emotion-aware TTS） |\n| 🔉 **智能降级链** | 主引擎故障自动切备用引擎，确保语音永不中断（MiniMax → Edge TTS 降级链） |\n| ⏸️ **自然停顿** | 在标点符号处自动添加语气停顿，告别机器人式朗读（TTS pause markers `\u003c#0.5#\u003e`） |\n| 📝 **桌面字幕同步** | 语音播报时同步显示逐字字幕，打字机效果呈现（typewriter lyrics overlay） |\n| 🔇 **消息排队播报** | 多条消息同时到达时自动排队，逐条播出不叠音（priority speech queue） |\n| 🚫 **重复消息过滤** | 相同内容自动去重，避免重复播报（whitespace-normalized dedup filter） |\n\n### 🧠 人设 \u0026 性格\n\n| 功能 | 说明 |\n|------|------|\n| 🎭 **5种性格预设** | 甜妹 / 专业 / 幽默 / 酷帅 / 自定义，一键切换说话风格（personality preset system） |\n| 📝 **人设文件自动生成** | 选定性格后一键生成 AI 人格档案，无需手写提示词（auto-generate AGENTS.md + SOUL.md + USER.md） |\n| 💬 **自定义称呼** | 自定义宠物名称和对你的称呼，如「小K叫你主人」（petName + userName 配置） |\n\n### 🛡️ Gateway 智能守护\n\n| 功能 | 说明 |\n|------|------|\n| ⚡ **自动拉起** | 连续3次检测 Gateway 不在线后自动启动，无需手动干预（Guardian auto-start） |\n| 📊 **实时健康监控** | 后台持续采集 Gateway 运行指标，异常时第一时间告警（anomaly detection + health scoring） |\n| 🎙️ **语音状态播报** | 启动中 / 成功 / 失败均有语音通知，不必盯控制台（voice status announcement） |\n| 🔄 **崩溃自动重启** | Gateway 异常退出后自动拉起，每小时上限10次防止死循环（auto-restart with rate limiting） |\n| 🩺 **10项一键体检** | Gateway / TTS / 模型 / 端口 / 缓存 / 日志等10维一键诊断，附修复建议（Doctor self-check） |\n| 🔧 **双重确认防误判** | 重启前与 ServiceManager 交叉校验，避免误杀健康实例（cross-validation with ServiceManager） |\n| ⏳ **启动宽限期** | 首次启动60秒内不触发重启逻辑，给 Gateway 充足启动时间（startup grace period） |\n\n### 🧙 新手引导向导\n\n| 功能 | 说明 |\n|------|------|\n| 🎮 **RPG 游戏风格** | 木质边框 + 羊皮纸纹理 + 龙虾向导 NPC + 打字机对白（RPG-style Setup Wizard） |\n| 📋 **7步全流程引导** | Gateway → 模型 → 消息渠道 → 语音引擎 → 播报设置 → 显示选项 → 全链路测试 |\n| ⚡ **缺失依赖一键安装** | 检测到缺失依赖后一键安装，实时显示安装进度（one-click dependency install + real-time progress） |\n| 🔍 **智能环境检测** | 自动探测 Node.js / Python / 兼容 CLI（OpenClaw）等环境状态及版本信息（smart environment detection） |\n| ✅ **全链路验证** | 7项端到端测试确保所有功能正常运行（end-to-end validation） |\n| 🐛 **错误可视化** | 向导异常时直接显示报错信息，不再白屏无提示（error visualization + crash recovery） |\n\n### 🎨 终端 \u0026 日志\n\n| 功能 | 说明 |\n|------|------|\n| 🌈 **彩色终端日志** | 12+ 模块统一彩色输出——模型名青色、URL绿色、错误红色，一目了然（ANSI colorized logging） |\n| 🔇 **日志自动去重** | 空白归一化后去重，消除控制台刷屏（whitespace-normalized dedup） |\n| 📁 **日志轮转归档** | 按天归档、超10MB自动压缩、保留7天历史（log rotation + gzip archiving） |\n| 📊 **性能实时监控** | 内存 / CPU / 帧率实时采集，超阈值自动告警（performance monitor + 24h sample history） |\n\n### 🔁 模型切换\n\n| 功能 | 说明 |\n|------|------|\n| 🔄 **热切换** | Claude ↔ GPT ↔ Gemini ↔ DeepSeek 无需重启，3秒生效（hot model swap via CC-Switch） |\n| 📊 **延迟测速** | 一键对比各模型响应延迟，选择最优（latency benchmark） |\n| ➕ **自由添加模型** | 支持15+主流 AI 服务商，也可自定义 API 端点（custom provider + preset templates） |\n| 📜 **切换历史追溯** | 完整记录每次模型切换的时间与来源（switch history tracking） |\n| ↩️ **失败自动回滚** | 新模型5秒内无响应，自动回退到上一可用模型（optimistic update + 5s rollback） |\n\n### 🔐 安全\n\n| 功能 | 说明 |\n|------|------|\n| 🔑 **密钥加密存储** | API Key 经 Electron safeStorage 加密后写盘，杜绝明文泄露 |\n| 🛡️ **IPC 权限沙箱** | 渲染进程无法直接调用系统 API，所有操作经白名单校验（IPC whitelist sandbox） |\n| 🧹 **日志自动脱敏** | 日志中自动遮蔽 API Key、Token 等敏感信息（log sanitizer） |\n| 🔒 **命令注入防护** | 所有外部命令使用参数数组传递，不拼接字符串（execFile/spawn with args array） |\n\n### 🖥️ 桌面集成\n\n| 功能 | 说明 |\n|------|------|\n| 📌 **永远置顶** | 球体与字幕窗口始终位于最上层，不被其他窗口遮挡（always-on-top） |\n| 🖱️ **字幕穿透点击** | 歌词字幕窗口完全穿透鼠标事件，不影响底层操作（mouse-through transparent window） |\n| 🔗 **自动创建桌面快捷方式** | 首次启动自动生成桌面快捷方式，下次双击即用（auto .lnk / .app creation） |\n| 📸 **截图一键上传** | 工具栏一键截屏，自动上传至飞书（screenshot + Lark upload） |\n| 💬 **多平台消息同步** | Discord / Telegram / 飞书 / 企业微信消息统一同步并语音播报（multi-channel message sync） |\n| 🍎 **跨平台支持** | Windows 10/11 + macOS（Intel \u0026 Apple Silicon）双平台原生支持（cross-platform Electron） |\n| 📱 **托盘菜单** | 右键系统托盘即可切换模型、查看状态、启动诊断、管理会话（system tray context menu） |\n\n### 🆕 v3.7.1 — Hermes 聊天可用性修复\n\n\u003e 🩹 **补丁更新！** 修复 Hermes 兼容模式下两个容易误导用户的边界：没开 API server 时不再进入“能启动但不能聊”的半可用状态；只剩配置目录时也不再误判成“已安装 Hermes”。\n\n- 🔒 **聊天前置拦截** — Hermes 未启用 API server 时，Gateway 启动和桌面端发消息都会直接给出明确错误，不再继续走 `/v1/chat/completions`\n- ✅ **安装判定收紧** — 现在只有真正检测到 Hermes CLI 可执行文件，才会被标记为已安装\n- 🧪 **新增回归测试** — 增加 “残留 `~/.hermes` 目录但 CLI 缺失” 的假阳性回归测试，避免状态页再次误报\n\n### 🆕 v3.7.0 — Hermes 兼容模式 + 多后端启动器\n\n\u003e 🤝 **正式适配 Hermes！** `kkclaw gateway` 现在会按兼容后端模式工作：既能拉起 OpenClaw，也能驱动 Hermes，并在启动时提供 OpenClaw / Hermes / Auto 三种入口。\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"docs/images/hermes-agent-banner.png\" alt=\"Hermes Agent banner\" width=\"100%\"\u003e\n  \u003cp\u003e\u003csub\u003eHermes Agent banner adapted from \u003ca href=\"https://github.com/NousResearch/hermes-agent\"\u003eNousResearch/hermes-agent\u003c/a\u003e\u003c/sub\u003e\u003c/p\u003e\n\u003c/div\u003e\n\n- 🆕 **Hermes 兼容模式** — 支持 `KKCLAW_COMPAT_MODE=hermes`，也支持在 `pet-config.json` 中固定 `compatMode: \"hermes\" | \"openclaw\" | \"auto\"`\n- 🆕 **后端选择式启动** — `kkclaw gateway` / `npm start` 的终端入口现在会先让你选择兼容后端（OpenClaw / Hermes / Auto），并记住上次选择\n- 🆕 **Hermes Gateway 复用** — 如果 Hermes Gateway 已经在外部启动，KKClaw 会识别并复用，不再把它误判成端口冲突\n- 🔧 **诊断全面增强** — `kkclaw status` / `kkclaw doctor` / `kkclaw gateway status` 会显示当前兼容后端、CLI 路径、探活方式、日志路径、API Server 状态\n- 🎨 **后端感知终端外观** — 启动画面和 Ready Banner 会根据当前兼容后端切换主色和标签，终端体验更统一\n\n### 🆕 v3.6.0 — 原生命令入口 + KKClaw Gateway CLI\n\n\u003e 🦞 **命令体验升级！** `kkclaw gateway` 现在直接打开带开场动画的终端，并补齐 `doctor / status / logs / dashboard`\n\n- 🆕 **`kkclaw gateway` 主入口** — 直接打开现在 `npm start` 的动画终端体验，启动习惯更接近原生命令行工作流\n- 🆕 **`kkclaw doctor`** — 增加 KKClaw 风格体检，检查兼容 CLI、Gateway 连通性、Dashboard 地址和进程归属\n- 🆕 **`kkclaw gateway status / logs / open / restart / stop`** — 提供贴近兼容后端工作流的子命令\n- 🆕 **`kkclaw dashboard`** — 直接转发到底层 `openclaw dashboard`\n- 🔧 **状态可观测性增强** — `doctor` 会提示当前 Gateway 端口是否由 KKClaw 自身占用，帮助排查旧进程/端口冲突\n\n### 🆕 v3.5.2 — Setup Wizard 修复 + 一键安装缺失依赖\n\n\u003e ⚡ **体验优化！** Wizard 白屏修复 + 缺失依赖一键安装 + 跨平台支持\n\n- ⚡ **一键安装缺失依赖** — 环境检测页新增按钮，自动安装 edge-tts / sqlite3 / node_modules，实时进度反馈\n- 🔧 **跨平台安装** — Windows (winget/choco)、macOS (brew)、Linux (apt/yum)\n- 🐛 **Wizard 白屏修复** — 修复 3 处语法错误导致的向导空白页\n- 🐛 **Wizard 错误可视化** — 渲染出错时直接显示报错信息，方便用户排查\n- 📝 **sqlite3 依赖说明** — 标注用途 `(CC-Switch 同步)`，未安装时提示安装命令\n\n### 🆕 v3.5.1 — 双声音修复 + 桌面快捷方式修复\n\n- 🔇 **双声音修复** — 所有 `new Notification()` 添加 `silent: true`，阻止 Windows 系统朗读\n- 🖥️ **快捷方式修复** — 指向 `start.cmd`，启动时显示 CMD 控制台 + Gateway 日志\n\n### 🆕 v3.5.0 — 体验大升级：彩色终端 + 智能守护 + 桌面快捷方式\n\n\u003e 🎨 **重大体验更新！** 全局彩色终端日志 + Gateway 智能自启动 + 日志去重降噪 + 首次启动自动创建桌面快捷方式\n\n#### 🎨 全局彩色终端日志系统\n- 🆕 **color-log.js 中心化模块** — 统一 ANSI 颜色常量 + 自动关键词高亮\n- ✨ **12+ 模块全覆盖** — main.js / service-manager / gateway-guardian / smart-voice / message-sync / pet-config / screenshot / log-rotation / performance-monitor / desktop-notifier 全部迁移\n- 🎯 **Gateway 日志高亮增强** — 模型名(cyan)、URL(green)、路径(dim)、渠道(magenta)、@botname(magenta)、key=value(yellow)、端口号(yellow)、协议(cyan)、错误(red)、成功(green)、警告(yellow)\n\n#### 🛡️ Gateway 智能自启动\n- 🆕 **首次启动主动拉起** — Guardian 不再永远等待，连续 3 次检测不到 Gateway 后自动执行 `startGateway()`\n- 🆕 **启动状态语音播报** — 启动中播报\"等待Gateway启动中\"，成功/失败分别语音通知\n- 🔧 **二次确认防误判** — 与 ServiceManager 探活交叉校验，避免误触重启\n- 🔧 **启动期静默** — 首次启动阶段不发告警事件，避免噪音\n\n#### 🔇 日志去重降噪\n- 🔧 **修复 Gateway 日志重复** — 找到根因：`log()` 方法在 stdout handler 之后二次 `console.log()`，gateway-std* 服务跳过控制台输出\n- 🔧 **stderr 智能过滤** — 仅显示含 error/fatal/panic/exception 的真错误行\n- 🔧 **空白归一化去重** — `\\s+` → `' '` 归一化后 Set 去重，彻底消除同内容重复\n\n#### 🖥️ 首次启动自动创建桌面快捷方式\n- 🆕 **自动创建 .lnk** — 首次启动自动在桌面创建\"Claw 桌面宠物\"快捷方式\n- 🔧 **PowerShell COM 对象** — 使用 WScript.Shell 创建快捷方式，设置图标和最小化启动\n- 🔧 **智能跳过** — 已存在快捷方式或非 Windows 平台自动跳过\n- 🎙️ **语音播报** — 创建成功后播报\"桌面快捷方式已创建\"\n\n#### 🔧 其他修复\n- 🐛 **修复语音双响** — 移除 messageSync 中重复的 `voiceSystem.speak()` 调用\n- 🐛 **修复通知日志重复** — desktop-notifier 只打印通知类型，不重复打印 payload\n- 🐛 **DashScope TTS 引擎移除** — 语音降级链简化为 MiniMax → Edge TTS\n\n### 🆕 v3.1.2 — 安全加固 \u0026 模型管理升级\n\n\u003e 🔒 **安全重点更新！** 命令注入修复 + 动态 Token 管理 + 模型热切换状态机 + Gateway 智能监控\n\n#### 🧙 Setup Wizard 配置向导（全新）\n- 🎮 **RPG 游戏风格** — 木质边框 + 羊皮纸背景 + 龙虾向导角色\n- 📋 **7 步引导流程** — Gateway → 模型 → 渠道 → TTS → 语音播报 → 显示 → 测试\n- 🎤 **一键音色克隆** — 上传30秒录音，自动调 MiniMax/CosyVoice API 创建专属音色\n- 🎭 **人设定制系统** — 5种预设风格（甜妹/专业/幽默/酷帅/自定义）\n- 📝 **全套文件生成** — 一键生成 `AGENTS.md` + `SOUL.md` + `USER.md` + `HEARTBEAT.md` + `desktop-bridge.js`\n- 🔗 **完整 AGENTS.md 模板** — 对齐生产级配置（记忆系统 + 安全规则 + 群聊规则 + 心跳检查 + 语音播报）\n- 🔔 **播报机制说明** — AI 回复语音不是“只要配好 TTS 就会自动朗读”。真正生效依赖 3 层：TTS 服务可用、`desktop-bridge.js` 已生成且可执行、agent 按 `AGENTS.md` 在每次回复前主动调用 `node desktop-bridge.js agent-response \"要播报的内容\"`\n- 💡 **模型兼容性提示** — 推荐 Claude Sonnet 4+ 旗舰模型获得最佳播报体验\n- ✅ **7 项全链路测试** — Gateway / 模型 / TTS / 播报 / 歌词 / Agent文件 / 音色\n\n#### 🌈 情绪系统升级\n- 🌈 **7 → 14 种情绪** — 新增 sad、angry、fearful、calm、excited、love、focused\n- ✨ **动态外发光** — 每种情绪有专属 glow 光效\n- 🎭 **情绪文本检测** — `desktop-bridge.js` 自动分析内容情绪，10种匹配规则\n\n#### 🔐 安全与稳定性\n- 🔑 **API Key 加密存储** — `safeStorage` 加密，密钥不再明文写入磁盘\n- 🔒 **preload 安全沙箱** — 主窗口/歌词/诊断/模型设置全部走 IPC 白名单，渲染进程不再直接 require Node\n- 🎵 **歌词窗口 Ready 守卫** — `lyricsReady` 标志位，防止加载未完成时崩溃\n- 🔧 **sendLyric 封装** — 统一歌词推送，自动检查窗口状态\n- 📡 **端口持久化** — 通知端口写入配置，wizard/bridge 可动态获取\n- 📡 **渲染进程错误转发** — `preload-error` + `console-message` 转发到主进程日志，防止静默失败\n\n#### 🩺 诊断与运维\n- 🆕 **Doctor 自检系统** — 10 项全自动诊断（Gateway / 托盘 / TTS配置 / 模型 / 端口 / 健康度 / 缓存 / 歌词 / 日志），每项带修复建议\n- 🆕 **会话刷新** — 损坏会话一键清理重连（`doRefreshSession`）\n- 🔧 **诊断工具箱 UI 升级** — Doctor 面板新增 summary 统计 + 修复建议 + 分级状态（pass/warn/fail）\n\n#### 🎛️ 模型管理升级\n- 🆕 **延迟测速** — 单模型测速 + 全量批量测速（`speedTest` / `speedTestAll`）\n- 🆕 **Provider CRUD** — 新增/编辑/删除服务商，编辑 baseUrl 和 API Key\n- 🆕 **模型增删** — Provider 内添加/移除模型\n- 🆕 **预设快速添加** — 内置主流 Provider 预设模板，一键填入配置\n\n#### 🎙️ 语音系统增强\n- 🆕 **MiniMax Speech 2.8 HD** — 新增高清语音引擎选项\n- 🔄 **SmartVoice 配置统一** — 直接读 petConfig，不用重复读文件\n- 🎤 **完整版 desktop-bridge.js** — cleanForTTS + detectEmotion + addTTSPauseMarkers\n- 🎵 **歌词 TTS 标记过滤** — `\u003c#0.3#\u003e` 停顿标记不显示在字幕中，只给语音引擎用\n\n#### 📖 文档\n- 🆕 **完整配置教程** — [CONFIGURATION-GUIDE.md](docs/CONFIGURATION-GUIDE.md)（863行），从零开始手把手教学\n\n### v2.2.1 特性\n\n- 🔧 **诊断工具箱** — 全新独立窗口，一键查看 Gateway 状态、日志、连接信息\n- 🔇 **CMD 屏闪修复** — 全面添加 `windowsHide: true`，彻底消除 Windows 命令行窗口闪烁\n\n### v2.2.0 特性\n\n- 🛡️ **Gateway 错误诊断链路** — 捕获 stdout/stderr，桌面通知显示具体崩溃原因\n- 🔄 **安全模型切换 + 自动回滚** — 切换失败 5 秒内自动恢复上一个模型\n- 📊 **会话管理托盘菜单** — 查看上下文使用率、token 估算、一键清理会话\n- 📡 **请求追踪系统** — 序列 ID + 计时 + 错误历史(50条) + 30s 超时诊断\n- ⏳ **启动宽限期** — 60s 冷启动保护，防止误判重启循环\n- 🧠 **上下文感知** — 中英文 token 估算，接近限制时智能警告\n\n---\n\n## 🎬 演示视频\n\n\u003cdiv align=\"center\"\u003e\n\n### 直接点击播放 ▶️\n\n\u003cvideo width=\"100%\" controls style=\"max-width: 800px; border-radius: 12px; box-shadow: 0 10px 30px rgba(0,0,0,0.2);\"\u003e\n  \u003csource src=\"videos/demo.mp4\" type=\"video/mp4\"\u003e\n  您的浏览器不支持视频播放。\u003ca href=\"https://b23.tv/85bz09G\"\u003e点击查看B站版本\u003c/a\u003e\n\u003c/video\u003e\n\n**居然让 OpenClaw 给自己做了个身体！**\n\n[📱 B站视频](https://b23.tv/85bz09G) | [📱 抖音视频](https://v.douyin.com/9wKpkB8z4ew/)\n\n\u003c/div\u003e\n\n---\n\n## 📦 下载安装\n\n### 最新版本：v3.7.1\n\n\u003cdiv align=\"center\"\u003e\n\n| 平台 | 架构 | 下载链接 | 大小 |\n|------|------|----------|------|\n| 🪟 **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 |\n| 🍎 **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 |\n| 🍎 **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 |\n\n[📦 查看所有版本](https://github.com/kk43994/kkclaw/releases) | [🎥 在线演示](https://kk43994.github.io/kkclaw/)\n\n\u003c/div\u003e\n\n### ⚠️ 推荐使用方式：克隆仓库\n\n\u003e **建议有一定技术基础的用户直接克隆仓库运行，而非下载发行版。**\n\u003e\n\u003e 发行版为打包封装版本，存在以下限制：\n\u003e - 部分配置已硬编码在包内，自定义修改需要解包，不适合新手\n\u003e - 小版本的 bug 修复和功能更新不会单独推发行版，克隆仓库后 `git pull` 即可同步最新改动\n\u003e\n\u003e ```bash\n\u003e git clone https://github.com/kk43994/kkclaw.git\n\u003e cd kkclaw\n\u003e npm install\n\u003e npm start\n\u003e ```\n\u003e\n\u003e 发行版适合只想快速体验的用户，长期使用推荐源码运行。\n\n### 命令行入口（推荐）\n\n```bash\nnpm link\n\nkkclaw gateway          # 打开带兼容后端选择器的 KKClaw Gateway 终端（OpenClaw / Hermes / Auto）\nkkclaw gateway status   # 查看网关状态 / 端口 / 当前兼容后端\nkkclaw gateway logs     # 查看 Gateway 日志\nkkclaw doctor           # 做一轮 KKClaw 体检\nkkclaw dashboard        # 打开当前兼容后端的 Dashboard / API 面板\n```\n\n### 安装说明\n\n#### Windows\n1. 下载 `.exe` 安装程序\n2. 双击运行（可能需要允许\"未知发布者\"）\n3. 按提示完成安装\n\n#### macOS\n1. 下载对应架构的 `.dmg` 文件\n2. 打开 DMG，拖动应用到 Applications 文件夹\n3. 首次运行需要在\"系统偏好设置 → 安全性与隐私\"中允许\n\n\u003e **注意**：macOS 版本未签名，首次运行需要右键点击 → \"打开\"\n\n---\n\n## 📸 预览\n\n\u003cdiv align=\"center\"\u003e\n\n### 🎨 14种情绪色系\n\n![Mood System](docs/images/mood-system.png)\n\n**丰富的情绪状态** — 14种颜色 × 38种表情 = 超自然的情感表达\n\n---\n\n### 🔧 精灵窗口 + 工具栏\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\"\u003e\n\n![Pet Closeup](docs/images/pet-closeup.png)\n\n**67px 琉璃球体**\n- 3层流体动画\n- 双重高光系统\n- 胶囊形发光眼睛\n\n\u003c/td\u003e\n\u003ctd width=\"50%\"\u003e\n\n![Toolbar](docs/images/toolbar.png)\n\n**SVG图标工具栏**\n- 💬 聊天对话\n- 📸 截图上传\n- 🎤 语音切换\n- ⚙️ 设置面板\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n---\n\n### 💬 聊天交互演示\n\n![Chat Demo](docs/images/chat-demo.png)\n\n**智能对话 + 文件操作** — 可以与桌面图标、文件进行自然语言交互\n\n*示例：KK要复制图标文件，直接用红框标记图标，用飞书语音创建快捷方式*\n\n\u003c/div\u003e\n\n---\n\n## ✨ 核心功能\n\n### 🎨 空气感双窗口设计\n\n\u003e **设计理念**：像桌面歌词一样，不妨碍操作，却始终陪伴。\n\n#### 精灵窗口 (200×220px)\n- **67px 流体玻璃球** — 3层径向渐变 + 双重高光 + 内外发光\n- **胶囊形眼睛** (11×19px) — 15+种表情，SVG矢量\n- **SVG图标工具栏** — 💬聊天 / 📸截图 / 🎤语音，hover展开\n\n#### 歌词窗口 (400×100px)\n- **完全鼠标穿透** — `setIgnoreMouseEvents`，不挡操作\n- **白字描边** — `text-shadow` 8重叠加，任何背景可见\n- **打字机效果** — 逐字出现，支持emoji，自动换行\n\n#### 拖动同步\n- 拖动精灵窗口 → 歌词窗口自动跟随\n- IPC事件 `drag-pet` 双窗口实时同步\n\n---\n\n### 🎙️ 智能语音系统（三级降级）\n\n#### **主引擎：MiniMax Speech 2.5 Turbo**\n- **克隆音色** — 小团团导航音（`xiaotuantuan_minimax`）\n- **7种情感** — happy, sad, angry, fearful, disgusted, surprised, calm\n- **停顿控制** — `\u003c#0.5#\u003e` 在文本中插入自然停顿\n- **费用** — 2元/万字符，克隆费9.9元/音色（一次性）\n\n**自动情感识别**：\n```javascript\n// smart-voice.js 根据文本内容自动选择emotion\n\"太棒了！\" → happy\n\"失败了...\" → sad\n\"什么！？\" → surprised\n```\n\n#### **降级链**：\n1. MiniMax → 2元/万字符，高质量\n2. CosyVoice → DashScope API，中等质量\n3. Edge TTS → 免费本地，基础质量\n\n---\n\n### 🔁 KKClaw Switch 模型热切换\n\n\u003e **3秒切换AI模型，零重启，零中断**\n\n#### 工作原理\n\n```\n┌─────────────────┐       ┌─────────────────┐       ┌─────────────────┐\n│  KKClaw Switch  │  →    │  Auto Monitor   │  →    │ Compatible CLI  │\n│  (点击切换)      │       │  (每2秒检测)     │       │  (自动重启)      │\n└─────────────────┘       └─────────────────┘       └─────────────────┘\n        ↓                         ↓                         ↓\n    切换Provider           读取DB变化               同步config → restart\n```\n\n#### 功能特性\n\n✅ **自动同步监听器** — 集成到桌面宠物生命周期\n- 启动时自动开启 `kkclaw-auto-sync.js`\n- 关闭时自动停止\n- 每2秒检测 `~/.cc-switch/cc-switch.db`\n\n✅ **手动同步** （可选）\n```bash\nnode kkclaw-hotswitch.js              # 同步当前provider\nnode kkclaw-hotswitch.js --restart    # 同步 + 重启Gateway\n```\n\n✅ **无缝切换**\n- Claude Opus 4 ↔ GPT-5.3 ↔ Gemini Pro\n- 3秒内生效\n- 不中断对话上下文\n\n---\n\n### 👁️ 眼睛表情系统\n\n#### 15+种基础表情\n\n| 表情 | 参数 | 效果 |\n|------|------|------|\n| **normal** | 11×19px | 正常状态 |\n| **blink** | 12×3px | 眨眼 |\n| **happy** | 13×7px, br:7px 7px 3px 3px | 开心弯眼 |\n| **surprised** | 13×21px | 惊讶瞪大 |\n| **thinking** | 10×17px, ty:-3px | 思考眯眼 |\n| **sleepy** | 12×4px, ty:2px | 困了半闭 |\n| **sparkle** | 12×12px, rot:45deg | 星星眼 |\n| **wink** | 左13×7px, 右11×19px | 单眼眨 |\n| **love** | 14×13px, br:7px 1px, rot:45deg | 爱心眼 |\n| **angry** | 12×14px, rot:±12deg | 生气皱眉 |\n| **dizzy** | 10×10px, rot:±25deg | 头晕旋转 |\n| **cross** | 10×3px, rot:±30deg | X眼（装死） |\n\n#### 38个待机动作序列\n\n**类型分布**：\n- 👀 **眼睛动画** (14个) — 左右看、上下看、眨眼、歪头\n- 😊 **表情组合** (12个) — 开心→惊讶、思考→闪亮、困→惊醒\n- 💕 **情感表达** (6个) — 害羞脸红、爱心眼、生气跺脚\n- 🎭 **复杂序列** (6个) — 环顾四周、开心蹦跶、装死复活\n\n**触发机制**：\n```javascript\nsetInterval(() =\u003e {\n    if (currentMood === 'idle' \u0026\u0026 Math.random() \u003c 0.3) {\n        // 30%概率触发\n        idleActs[Math.floor(Math.random() * 38)]();\n    }\n}, 4000); // 每4秒检查一次\n```\n\n---\n\n### 🎨 琉璃质感球体\n\n#### 视觉分层（由内到外）\n\n```\n┌─ 1. 内部流体层 ────────────────┐\n│   - blob1: 20×20px 圆形       │\n│   - blob2: 30×30px 椭圆       │\n│   - 不同速度动画（20s / 25s）  │\n└──────────────────────────────┘\n        ↓\n┌─ 2. 玻璃外壳 ──────────────────┐\n│   - 3层径向渐变               │\n│   - 主高光 (35% 18%)          │\n│   - 副高光 (20% 12%)          │\n│   - 1.5px border 半透明       │\n└──────────────────────────────┘\n        ↓\n┌─ 3. 外部发光 ──────────────────┐\n│   - box-shadow 内外双层       │\n│   - 根据mood颜色动态变化      │\n└──────────────────────────────┘\n```\n\n#### 颜色过渡动画\n\n**1秒平滑渐变** — 动态 `@keyframes` 生成\n\n```javascript\n// 每次切换mood时动态创建过渡动画\nfunction createColorTransition(fromColor, toColor) {\n    const keyframes = `\n        @keyframes colorShift-${Date.now()} {\n            from { background: ${fromColor}; }\n            to { background: ${toColor}; }\n        }\n    `;\n    // 三层独立动画：0.8s / 1.0s / 1.2s\n}\n```\n\n---\n\n### 🛡️ 7×24 稳定性保障\n\n#### 自动重启机制\n- **Electron进程崩溃** → 5秒后自动重启\n- **兼容后端 Gateway 挂掉** → 30秒后自动重启\n- **系统资源耗尽** → 内存清理 + 重启\n\n#### 日志轮转\n- **每日轮转** — 保留最近7天日志\n- **大小限制** — 单文件10MB，超过自动归档\n- **分级记录** — INFO / WARN / ERROR\n\n#### 缓存管理\n- **自动清理** — 每24小时清理临时文件\n- **智能压缩** — 旧日志自动压缩为 `.gz`\n\n#### 性能监控\n- **CPU使用率** — 超过80%告警\n- **内存使用** — 超过500MB告警\n- **FPS监控** — 低于30fps告警\n\n---\n\n## 🚀 快速开始\n\n\u003e 📖 **完整配置教程请看 → [CONFIGURATION-GUIDE.md](docs/CONFIGURATION-GUIDE.md)**\n\u003e \n\u003e 从环境准备到语音配置到飞书接入，一步步手把手教学，小白也能看懂！\n\n### 前置要求\n\n- **Node.js** ≥ 18.x ([下载](https://nodejs.org))\n- **Windows** 10/11 或 **macOS** 10.15+\n- **兼容后端**：**OpenClaw** ≥ 2026.x 或 **Hermes Agent**（建议最新版本）([OpenClaw](https://openclaw.ai) | [Hermes](https://github.com/NousResearch/hermes-agent))\n\n### 安装\n\n#### 方式一：ClawHub（推荐）\n\n```bash\nnpx clawhub@latest install kk43994/desktop-pet\n```\n\n#### 方式二：GitHub\n\n```bash\ngit clone https://github.com/kk43994/kkclaw.git\ncd kkclaw\nnpm install\nnpm start\n```\n\n### 配置\n\n\u003e 🧙 **v3.0 新增 Setup Wizard！** 首次启动会自动弹出配置向导，跟着引导走即可完成全部设置。\n\u003e \n\u003e 如需手动配置，参考以下步骤：\n\n1. **复制配置模板**\n   ```bash\n   cp pet-config.example.json pet-config.json\n   ```\n\n2. **编辑 `pet-config.json`**\n   ```json\n   {\n     \"openclaw\": {\n       \"gateway\": \"http://localhost:3000\"\n     },\n     \"voice\": {\n       \"engine\": \"minimax\",\n       \"minimax\": {\n         \"apiKey\": \"sk-api--你的密钥\",\n         \"groupId\": \"你的GroupID\",\n         \"voiceId\": \"xiaotuantuan_minimax\"\n       }\n     }\n   }\n   ```\n\n3. **启动应用**\n   ```bash\n   npm start\n   ```\n\n---\n\n## 📖 文档\n\n### 项目文档\n\n- [📖 **完整配置教程**](docs/CONFIGURATION-GUIDE.md) — ⭐ 新手必看！从零开始配置\n- [📂 项目结构](PROJECT-STRUCTURE.md) — 目录组织、命名规范\n- [🎙️ 智能语音系统](docs-dev/SMART-VOICE.md) — 三级降级、情感识别\n- [🔁 KKClaw Switch](docs-dev/SYNC-GUIDE.md) — 模型热切换配置\n- [📸 截图功能](docs-dev/SCREENSHOT-FEATURE.md) — 快捷键、自动上传\n- [🔧 开发指南](docs-dev/SETUP-GUIDE.md) — 开发环境、调试\n\n### 在线资源\n\n- [🎥 **在线演示**](https://kk43994.github.io/kkclaw/) — 可交互的球体demo\n- [📦 **ClawHub主页**](https://clawhub.ai/kk43994/desktop-pet) — 国际社区\n- [📦 **OpenClaw-CN**](https://clawd.org.cn) — 中文社区技能市场\n\n---\n\n## 🔧 配置详解\n\n### 基础配置\n\n```json\n{\n  \"openclaw\": {\n    \"gateway\": \"http://localhost:3000\",\n    \"sessionKey\": \"main\",\n    \"checkInterval\": 2000\n  },\n  \"window\": {\n    \"position\": { \"x\": 100, \"y\": 100 },\n    \"alwaysOnTop\": true,\n    \"opacity\": 1.0\n  }\n}\n```\n\n### 语音配置\n\n#### MiniMax配置\n```json\n{\n  \"voice\": {\n    \"engine\": \"minimax\",\n    \"minimax\": {\n      \"apiKey\": \"sk-api--xxxxx\",\n      \"groupId\": \"2020139946483921771\",\n      \"voiceId\": \"xiaotuantuan_minimax\",\n      \"model\": \"speech-2.5-turbo-preview\",\n      \"speed\": 1.1,\n      \"vol\": 3.0,\n      \"emotion\": \"happy\"\n    }\n  }\n}\n```\n\n#### DashScope（CosyVoice）配置\n```json\n{\n  \"voice\": {\n    \"engine\": \"dashscope\",\n    \"dashscope\": {\n      \"apiKey\": \"sk-xxxxxxxxxx\",\n      \"model\": \"cosyvoice-v3-plus\",\n      \"voice\": \"cosyvoice-v3-plus-tuantuan-xxx\"\n    }\n  }\n}\n```\n\n#### 语音播报的最小链路\n\n上面这一步只是把 TTS 服务配置好，它并不等于 AI 回复时一定会自动播报。真正能听到声音，还要同时满足下面 3 层：\n\n- TTS 服务本身可用\n- `desktop-bridge.js` 已生成，并且能在当前 workspace 正常执行\n- 当前 agent / 模型真的遵循 `AGENTS.md`，在每次回复前主动执行：`node desktop-bridge.js agent-response \"要播报的内容\"`\n\n如果你已经配好了 TTS，但 AI 回复还是完全没有声音，优先怀疑的就不只是配置问题，也可能是当前 agent 根本没有触发 bridge。\n\n### KKClaw Switch配置\n\n桌面宠物会自动集成，无需额外配置。\n\n如需手动同步：\n```bash\n# 同步当前 provider 到兼容后端配置\nnode kkclaw-hotswitch.js\n\n# 同步并重启Gateway\nnode kkclaw-hotswitch.js --restart\n```\n\n---\n\n## 🛠️ 开发\n\n### 目录结构\n\n```\ndesktop-pet/\n├── main.js                  # Electron主进程\n├── index.html              # 精灵窗口UI\n├── lyrics.html             # 歌词窗口UI\n├── setup-wizard.html       # 🧙 Setup Wizard UI（RPG风格）\n├── setup-wizard.js         # 🧙 Setup Wizard 后端逻辑\n├── setup-preload.js        # 🧙 Wizard IPC 安全桥接\n├── smart-voice.js          # 智能语音调度\n├── pet-config.js           # 🔐 配置管理（含 safeStorage 加密）\n├── voice/                  # TTS引擎目录\n│   ├── minimax-tts.js\n│   ├── dashscope-tts.js\n│   └── cosyvoice-tts.py\n├── templates/              # 🧙 向导模板文件\n│   └── desktop-bridge.js   # 语音播报桥接模板\n├── utils/                  # 辅助工具目录\n├── scripts/                # 工具脚本\n├── tests/                  # 测试文件\n├── docs-dev/               # 开发文档\n└── archive/                # 归档旧版本\n```\n\n### 开发命令\n\n```bash\nnpm start              # 启动应用\nnpm run dev            # 开发模式（热重载）\nnpm run console        # 打开系统终端并运行 npm start\nnpm test               # 运行测试\nnpm run build          # 构建发布版\n```\n\n### 调试\n\n1. **开启Electron DevTools**\n   - 主窗口：`Ctrl + Shift + I`\n   - 或修改 `main.js` 添加 `mainWindow.webContents.openDevTools()`\n\n2. **查看日志**\n   ```bash\n   # 实时日志\n   tail -f logs/app.log\n\n   # 错误日志\n   tail -f logs/error.log\n   ```\n\n---\n\n## 🤝 贡献\n\n欢迎贡献代码、报告Bug、提出建议！\n\n### 贡献方式\n\n1. **Fork** 本仓库\n2. 创建分支 `git checkout -b feature/新功能`\n3. 提交更改 `git commit -m 'Add: 新功能描述'`\n4. 推送分支 `git push origin feature/新功能`\n5. 提交 **Pull Request**\n\n### 代码规范\n\n- 使用 **kebab-case** 命名文件\n- 添加 **详细注释**\n- 遵循 **ESLint** 规则\n- 测试覆盖 **核心功能**\n\n---\n\n## 🐛 故障排查\n\n### 常见问题\n\n#### 1. 球体不显示\n\n**原因**：窗口位置超出屏幕\n**解决**：删除 `pet-config.json` 中的 `window.position`，重启应用\n\n#### 2. 语音不播报\n\n**可能原因**：\n- API密钥无效或配置错误\n- `desktop-bridge.js` 没生成、路径不对，或者当前 workspace 下不可执行\n- 当前 agent / 模型没有遵循 `AGENTS.md`，根本没有在回复前触发 `desktop-bridge.js`\n\n**解决**：\n```bash\n# 检查配置\nnode -e \"console.log(require('./pet-config.json').voice)\"\n\n# 测试MiniMax API\nnode voice/minimax-tts.js\n\n# 手动测试 bridge -\u003e 桌面端播报链路\nnode desktop-bridge.js agent-response \"这是一次 README 排障测试播报\"\n```\n\n**排障判断技巧**：\n- 如果手动执行 `desktop-bridge.js` 能播报，说明 TTS / bridge 基本正常，问题更可能出在 agent 没有执行播报命令\n- 如果手动执行也没有声音，再优先排查 TTS 配置、bridge 文件位置和运行环境\n\n#### 3. 兼容后端连接失败\n\n**原因**：Gateway 未启动、后端未运行或端口错误\n**解决**：\n```bash\n# 检查兼容 CLI / 后端状态\nopenclaw status\n\n# 启动Gateway\nopenclaw gateway start\n```\n\n#### 4. KKClaw Switch不同步\n\n**原因**：\n- `~/.cc-switch/cc-switch.db` 不存在\n- 自动监听器未启动\n\n**解决**：\n```bash\n# 检查DB文件\nls ~/.cc-switch/cc-switch.db\n\n# 手动同步\nnode kkclaw-hotswitch.js --restart\n```\n\n---\n\n## 📊 性能指标\n\n| 指标 | 目标 | 实测 |\n|------|------|------|\n| **启动时间** | \u003c3秒 | 2.1秒 |\n| **内存占用** | \u003c200MB | 147MB |\n| **CPU占用** | \u003c5% | 2.8% |\n| **帧率** | ≥60fps | 60fps |\n| **语音延迟** | \u003c500ms | 320ms |\n\n*测试环境：Windows 11, i7-12700K, 32GB RAM*\n\n---\n\n## 📝 更新日志\n\n### [3.7.1] - 2026-04-14\n\n#### 🩹 Hermes 兼容补丁\n- Hermes 未启用 API server 时，Gateway 启动和桌面端聊天现在会直接阻断，并明确提示开启 `API_SERVER_ENABLED=true`\n- Hermes 已安装判定从“配置目录存在”收紧为“CLI 可执行文件存在”，避免假阳性\n- 新增 “残留 `~/.hermes` 目录但 Hermes CLI 缺失” 的回归测试\n\n### [3.7.0] - 2026-04-11\n\n#### 🤝 Hermes 兼容模式\n- 新增 Hermes 兼容后端，支持 `KKCLAW_COMPAT_MODE` 环境变量和 `pet-config.json.compatMode` 配置\n- `kkclaw gateway` / `npm start` 新增兼容后端（OpenClaw / Hermes / Auto）选择式启动，并记住上次选择\n- 如果 Hermes Gateway 已在外部运行，KKClaw 会识别并复用，不再误报端口冲突\n\n#### 🔍 诊断与启动体验\n- `kkclaw status` / `kkclaw doctor` / `kkclaw gateway status` 现在会显示当前兼容后端、CLI 路径、探活方式、日志路径、API Server 状态\n- 启动 Banner 和 Ready Banner 改为后端感知：OpenClaw 为红色主题，Hermes 为香槟金主题\n- `kkclaw dashboard` 与主进程网关配置会自动切换到当前兼容后端\n\n#### 🧪 测试与文档\n- 新增后端选择启动器、Hermes 兼容模式、外部 Hermes Service 复用相关测试\n- README 和语音开发文档补充了 AI 回复语音播报的真实触发链路说明\n\n### [3.6.0] - 2026-04-02\n\n#### 🦞 KKClaw CLI\n- 新增 `kkclaw` 命令入口，支持 `kkclaw gateway`\n- `kkclaw gateway` / `kkclaw gateway start` 直接打开带开场动画的终端（当前 `npm start` 体验）\n- 新增 `kkclaw gateway status / logs / open / restart / stop`\n- 新增 `kkclaw doctor` 和顶层 `kkclaw status`\n\n#### 🔍 诊断与可观测性\n- `kkclaw doctor` 增加 Gateway ownership 检查，能发现端口被旧进程或外部实例占用\n- `kkclaw gateway status` 增加 Dashboard 地址、日志路径、兼容 CLI（OpenClaw）版本和进程摘要\n- `kkclaw gateway logs` 支持查看标准日志 / 错误日志并设置 tail 行数\n\n### [3.5.2] - 2026-03-12\n\n#### ⚡ 一键安装缺失依赖\n- ⚡ **环境检测页新增按钮** — 自动安装 edge-tts / sqlite3 / node_modules，实时进度反馈\n- 🔧 **跨平台安装** — Windows (winget/choco)、macOS (brew)、Linux (apt/yum)\n\n#### 🐛 修复\n- 修复 Setup Wizard 白屏 — 3 处函数声明缺失导致 SyntaxError\n- Wizard 错误可视化 — 渲染出错时显示具体报错\n- sqlite3 依赖说明优化 — 标注 `(CC-Switch 同步)` 用途\n\n### [3.5.1] - 2026-03-12\n\n#### 🐛 修复\n- 修复双声音问题 — 所有 `new Notification()` 添加 `silent: true`\n- 修复桌面快捷方式不显示 CMD — 指向 `start.cmd`，WindowStyle 1\n- 移除 `speak()` 临时调试日志\n\n### [3.5.0] - 2026-03-12\n\n#### 🎨 全局彩色终端日志\n- 🆕 **color-log.js** — 中心化 ANSI 颜色模块，统一颜色常量 + 自动高亮函数\n- ✨ **全面迁移** — 12+ 模块启动日志迁移到 `colorLog()` / `kvLog()` / `tagLog()`\n- ✨ **Gateway 日志高亮增强** — 模型名、URL、路径、渠道、@botname、key=value、端口号、协议、错误/成功/警告 全彩高亮\n\n#### 🛡️ Gateway 智能自启动\n- 🆕 **首次启动主动拉起** — 连续 3 次检测不到 Gateway 后自动 `startGateway()`，不再永远等待\n- 🆕 **启动状态语音播报** — 启动中/成功/失败 分别语音通知\n- 🔧 **二次确认防误判** — 与 ServiceManager 交叉校验\n\n#### 🔇 日志去重降噪\n- 🔧 **修复 Gateway 日志重复** — 根因：`log()` 二次打印；gateway-std* 跳过控制台输出\n- 🔧 **stderr 智能过滤** — 仅显示 error/fatal/panic/exception\n- 🔧 **空白归一化去重** — `\\s+` → `' '` 归一化后 Set 去重\n\n#### 🖥️ 首次启动自动创建桌面快捷方式\n- 🆕 **自动创建 .lnk** — 首次启动自动在桌面创建\"Claw 桌面宠物\"快捷方式\n- 🔧 **PowerShell COM** — WScript.Shell 创建快捷方式\n- 🎙️ **语音播报** — 创建成功后播报\n\n#### 🐛 修复\n- 修复语音双响（移除 messageSync 重复 speak）\n- 修复通知日志重复（desktop-notifier 只打印类型）\n- DashScope TTS 引擎移除，降级链简化为 MiniMax → Edge TTS\n\n### [3.1.2] - 2026-03-11\n\n#### 🔒 安全加固\n- 🔧 **命令注入修复** — `_playAudioFile()` / `_playAudio()` / `speakWithEdgeTTS()` 全部从 `exec()` shell 拼接改为 `execFile()` / `spawn()` + 参数数组\n- 🔧 **Edge TTS 文本注入修复** — 文本通过临时文件 `--text-file` 传入，不再 inline `--text` 拼接\n- 🔧 **stop() 真正停止播放** — 跟踪当前播放进程引用，`stop()` 时 `.kill()` 终止\n- ✨ **Token 动态读取** — `openclaw-client.js` 不再模块加载时缓存 token，改用 `SecureStorage` + `configManager` 动态获取\n- ✨ **IPC 校验模块** — 新增 `ipc-validator.js`，渠道白名单校验\n- ✨ **日志脱敏** — 新增 `log-sanitizer.js`，防止敏感信息写入日志\n\n#### 🎛️ 模型管理升级\n- ✨ **模型热切换状态机** — `model-switch-state-machine.js`，状态驱动的切换流程\n- ✨ **切换策略模式** — `model-switch-strategies.js`，可扩展的切换策略\n- ✨ **切换历史记录** — `switch-history.js`，追踪模型切换轨迹\n- ✨ **额度查询** — `quota-query.js`，查询 API 余额\n- ✨ **CC Switch 同步** — `cc-switch-sync.js`，Claude Code 模型同步切换\n\n#### 🛡️ Gateway 智能监控\n- ✨ **异常检测器** — `gateway-anomaly-detector.js`，自动识别异常模式\n- ✨ **健康评分** — `gateway-health-scorer.js`，多维度健康度量化\n- ✨ **指标采集器** — `gateway-metrics-collector.js`，实时采集 Gateway 指标\n- ✨ **智能检测器** — `gateway-smart-detector.js`，智能故障诊断\n\n#### 🏗️ 架构优化\n- ✨ **路径解析器** — `openclaw-path-resolver.js`，消除硬编码路径\n- ✨ **安全配置加载** — `safe-config-loader.js`，带校验的配置读取\n- ✨ **安全存储** — `secure-storage.js`，token 安全管理\n- ✨ **会话锁管理器** — `session-lock-manager.js`，并发安全的会话操作\n- ✨ **配置管理器** — `config-manager.js` + `config-writer.js`，统一配置读写\n- ✨ **Setup Wizard 独立 preload** — `setup-preload.js`，最小化权限暴露\n- ✨ **Model Settings 分离** — CSS/JS 从 HTML 中独立为 `model-settings.css` + `model-settings.js`\n\n### [3.0.0] - 2026-02-22\n\n#### 🧙 Setup Wizard — 一键配置向导（全新）\n- ✨ **RPG 游戏风格引导界面** — 木质边框 + 羊皮纸背景 + 龙虾向导 + 打字机文字效果\n- ✨ **7 步引导流程** — Gateway 连接 → AI 模型 → 消息渠道 → TTS 引擎 → Agent 语音 → 显示 → 全链路测试\n- ✨ **一键音色克隆** — 拖拽上传录音文件，自动调用 MiniMax / CosyVoice API 克隆音色\n- ✨ **人设定制系统** — 宠物昵称 + 用户称呼 + 5 种说话风格预设（甜妹/专业/幽默/酷帅/自定义）\n- ✨ **全套 Agent 配置文件自动生成**：\n  - `AGENTS.md` — 完整工作手册（记忆系统 + 安全规则 + 群聊规则 + 心跳检查 + 语音播报规则）\n  - `SOUL.md` — Agent 人设文件（根据选择的风格自动生成）\n  - `USER.md` — 用户信息框架\n  - `HEARTBEAT.md` — 心跳检查配置\n  - `desktop-bridge.js` — 语音播报桥接脚本（完整版，含 cleanForTTS + detectEmotion + addTTSPauseMarkers）\n- ✨ **语音播报是如何触发的？**\n  - 第 1 层：TTS 引擎本身要可用（MiniMax / Edge TTS / 其他降级链正常）\n  - 第 2 层：`desktop-bridge.js` 要已经生成，并且在当前 workspace 里可执行\n  - 第 3 层：agent / 模型必须真的遵循 `AGENTS.md`，在每次回复前主动执行：`node desktop-bridge.js agent-response \"要播报的内容\"`\n  - **少了第 3 层时，哪怕 TTS 配置完全正确，也可能一声不响。**\n- ✨ **7 项全链路测试** — Gateway / AI模型 / TTS引擎 / 语音播报 / 桌面歌词 / Agent配置文件 / 自定义音色\n- ✨ **模型兼容性提示** — 注明不同模型的指令遵循度差异，推荐 Claude Sonnet 4+\n- ✨ **preload 安全白名单** — 所有 IPC 通道经白名单校验，防止恶意调用\n\n#### 🌈 情绪系统大升级\n- ✨ **14 种情绪色系** — 原有 7 种 + 新增 sad(天蓝)、angry(烈焰红)、fearful(紫罗兰)、calm(薄荷青)、excited(热粉)、love(珊瑚)、focused(青蓝)\n- ✨ **动态外发光 (glow)** — 每种情绪有专属外发光效果\n- ✨ **10 种文本情绪检测规则** — 自动分析内容情绪：thinking → surprised → fearful → sad → angry → calm → excited → happy\n\n#### 🔐 安全与稳定性\n- ✨ **API Key 加密存储** — 使用 Electron `safeStorage` 加密 MiniMax/DashScope 密钥，磁盘上不再明文\n- ✨ **preload 安全沙箱** — 新增 `preload.js`，主窗口/歌词/诊断/模型设置全部走 IPC 白名单校验\n- ✨ **歌词窗口 Ready 守卫** — `lyricsReady` 标志位，歌词窗口未加载完不发消息，防崩溃\n- ✨ **sendLyric() 封装** — 统一歌词推送逻辑，自动检查窗口是否已销毁\n- ✨ **通知端口持久化** — 实际端口写入 petConfig，wizard / bridge 可动态读取\n- ✨ **渲染进程错误转发** — `preload-error` + `console-message` 事件转发到主进程日志\n\n#### 🩺 诊断与运维\n- ✨ **Doctor 自检系统** — `diag-doctor` IPC，10 项全自动诊断（Gateway / 系统托盘 / TTS 配置 / API Key / 模型配置 / 端口占用 / 健康评分 / 缓存大小 / 歌词窗口 / 日志目录），每项带修复建议\n- ✨ **会话刷新** — `doRefreshSession()` 一键清理损坏会话并重连\n- ✨ **诊断工具箱 UI 升级** — Doctor 面板新增 summary 统计条 + 修复建议 + pass/warn/fail 分级显示\n\n#### 🎛️ 模型管理升级\n- ✨ **延迟测速** — 单模型测速 `speedTest()` + 全量批量测速 `speedTestAll()`\n- ✨ **Provider CRUD** — 新增/编辑/删除服务商（`model-update-provider` / `model-remove-provider`）\n- ✨ **模型增删** — Provider 内添加/移除模型（`model-add-model` / `model-remove-model`）\n- ✨ **预设快速添加** — 内置主流 Provider 预设模板（`model-presets`），一键填入配置\n\n#### 🎙️ 语音系统增强\n- ✨ **MiniMax Speech 2.8 HD 引擎** — 新增高清语音选项\n- 🔧 **SmartVoiceSystem 配置统一** — 接受 petConfig 参数，直接读内存配置，不再重复读文件\n- 🔧 **desktop-bridge.js 完整版** — TTS 停顿标记、文本清理、情绪检测三合一\n- 🔧 **歌词 TTS 标记过滤** — `\u003c#0.3#\u003e` 停顿标记不显示在字幕中，只给语音引擎用\n\n#### 📖 文档\n- ✨ **完整配置教程** — 新增 [CONFIGURATION-GUIDE.md](docs/CONFIGURATION-GUIDE.md)（863行），从环境准备到语音配置到飞书接入，手把手教学\n\n#### 🔧 修复\n- 🐛 修复 `_testAgentVoice` 协议不匹配（`{action,text}` → `{type,payload:{content}}`）\n- 🐛 修复 `wizard-clone-voice` 未加入 preload 白名单导致克隆报错\n- 🐛 修复 Step 6 Agent 文件检测路径错误（`~/.openclaw` → 实际工作目录）\n- 🐛 修复 Footer 初始文本 `Step 1/6` → `Step 1/7`\n- 🐛 修复 `desktop-bridge.js` 模板字符串嵌套导致正则表达式转义错误（改为读取 `templates/` 文件）\n\n### [2.2.1] - 2026-02-19\n\n#### 新增\n- 🔧 **诊断工具箱** — 独立窗口，一键查看 Gateway 状态、日志、连接诊断\n- 🔇 **CMD 屏闪彻底修复** — 全部 exec/spawn 调用添加 `windowsHide: true` + `shell: false`\n\n#### 优化\n- 🎤 smart-voice 所有 PowerShell 播放命令静默化\n- 🔄 openclaw-updater 全流程（版本检查/安装/doctor）静默执行\n- 📸 截图系统进程隐藏\n- 🔔 auto-notify 桌面通知静默化\n- 🛡️ service-manager Gateway 进程管理改用 `shell: false`\n\n---\n\n### [2.1.0] - 2026-02-13\n\n#### 🎉 重大更新\n- ✨ **完整 macOS 支持** — Intel 和 Apple Silicon 双架构\n- 🤖 **GitHub Actions 自动化** — 推送 tag 自动构建发布\n- 📦 **跨平台打包** — DMG 安装器 + ZIP 便携版\n- 🔄 **自动发布流程** — electron-builder 直接发布到 GitHub Release\n\n#### 技术改进\n- 🔧 跳过代码签名配置（Windows + macOS）\n- 📦 升级 GitHub Actions artifacts 到 v4\n- 🔐 配置完整的 GitHub Actions 权限\n- 🎨 生成 macOS 专用 .icns 图标文件\n\n#### 文档更新\n- 📖 README 增加下载安装章节\n- 🌐 GitHub Pages 更新双平台支持\n- 📋 完善跨平台安装说明\n\n---\n\n### [2.0.4] - 2026-02-10\n\n#### 新增\n- ✨ KKClaw Switch自动同步集成\n- ✨ 7种情绪色系完整实现\n- ✨ 38个待机表情动画\n- ✨ 琉璃质感球体升级（3层高光）\n- ✨ 粉红龙虾球图标 + 桌面快捷方式\n\n#### 优化\n- 🎨 颜色过渡动画（1秒平滑）\n- 🎙️ MiniMax TTS情感自动识别\n- 🗂️ 项目目录重构（140→31个根文件）\n- 📖 README全面改版 + 实际截图展示\n\n#### 修复\n- 🐛 多余closing div标签（GitHub Pages）\n- 🐛 lark-uploader引用路径\n- 🐛 语音播放重复问题\n\n[查看完整更新日志](CHANGELOG.md)\n\n---\n\n## 💬 社群\n\n### 加入我们\n\n\u003cdiv align=\"center\"\u003e\n\n| 平台 | 链接 | 说明 |\n|------|------|------|\n| 💬 **AI Coding 交流群** | [扫码加入](docs/images/ai-coding-qr.jpg) | 微信群（7天有效） |\n| 🐦 **Discord** | [Friends of the Crustacean](https://discord.com/invite/clawd) | OpenClaw国际社区 |\n| 🇨🇳 **OpenClaw-CN** | [clawd.org.cn](https://clawd.org.cn) | 中文论坛 |\n| 📦 **ClawHub** | [clawhub.ai](https://clawhub.ai/kk43994/desktop-pet) | 技能市场 |\n| 💡 **GitHub Discussions** | [讨论区](https://github.com/kk43994/kkclaw/discussions) | 提问、分享 |\n\n\u003c/div\u003e\n\n### 支持项目\n\n如果这个项目帮助了你，欢迎：\n- ⭐ **Star** 本仓库\n- 🐛 **报告Bug** 或提需求\n- 📢 **分享**给朋友\n- ☕ [**赞赏支持**](docs/images/support-qr.jpg)\n\n---\n\n## 📜 开源协议\n\n[MIT License](LICENSE) © 2024-2026 KK\n\n---\n\n\u003ca id=\"-english\"\u003e\u003c/a\u003e\n\n## 🇬🇧 English\n\n**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**\n\n\u003cdiv align=\"center\"\u003e\n\n![Hero Banner](docs/images/hero-banner.png)\n\n[![Version](https://img.shields.io/badge/version-3.7.1-FF6B4A?style=for-the-badge\u0026logo=github)](https://github.com/kk43994/kkclaw/releases)\n[![Hermes Compatible](https://img.shields.io/badge/Hermes-Compatible-F7E7CE?style=for-the-badge)](https://github.com/NousResearch/hermes-agent)\n[![License](https://img.shields.io/badge/license-MIT-green?style=for-the-badge)](LICENSE)\n[![Platform](https://img.shields.io/badge/platform-Windows_|_macOS-0078D6?style=for-the-badge\u0026logo=apple\u0026logoColor=white)](https://github.com/kk43994/kkclaw)\n\n[🎥 **Live Demo**](https://kk43994.github.io/kkclaw/) | [📦 **Download**](https://github.com/kk43994/kkclaw/releases) | [📖 **Docs**](docs/CONFIGURATION-GUIDE.md) | [💬 **Community**](#-社群)\n\n\u003c/div\u003e\n\n### ✨ Highlights\n\nGive your compatible-backend AI (OpenClaw / Hermes) a **visible, audible** desktop embodiment.\n\n#### 🦞 Orb \u0026 Animation\n\n| Feature | Description |\n|---------|-------------|\n| 🔮 **Living Glass Orb** | 67px glass sphere with fluid constantly flowing inside, looks alive (3-layer fluid animation + radial gradient + dual highlights) |\n| 🌈 **14 Mood Colors** | Happy = warm orange, sad = sky blue, angry = fire red… auto-switches color and glow per mood (14-emotion glow system) |\n| 👀 **38 Micro-Expressions** | Blinks, tilts, peeks, dozes, sparkle eyes, plays dead while idle… like it has a personality (idle micro-expression engine) |\n| 🕐 **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) |\n| 🖱️ **Eye Tracking** | Eyes follow your cursor direction as you move the mouse (mouse tracking) |\n| 💗 **Blushing** | Certain expressions trigger pink blush on both cheeks (dynamic blush overlay) |\n| 🫧 **Floating Bubbles** | Semi-transparent bubbles floating around the orb for extra liveliness (bubble particle decoration) |\n| ✨ **Bounce on Click** | Click the orb and it squishes + flashes color, satisfying feedback (squish animation + color pulse) |\n| 🎈 **Breathing Float** | Orb gently bobs up and down, like floating on water (60fps float + breath scaling) |\n\n#### 🎙️ Voice \u0026 Audio\n\n| Feature | Description |\n|---------|-------------|\n| 🎤 **30s Voice Cloning** | Upload a 30-second recording, AI speaks in your voice (MiniMax Voice Cloning API) |\n| 🗣️ **14 Auto Tone Shifts** | Happy news = cheerful voice, sad news = subdued voice, auto-detected (emotion-aware TTS) |\n| 🔉 **Never Goes Silent** | Primary engine down → auto-switches to backup → then free fallback, always has a voice (MiniMax → Edge TTS fallback chain) |\n| ⏸️ **Natural Pauses** | Pauses at commas and periods, not robotic read-aloud (TTS pause markers `\u003c#0.5#\u003e`) |\n| 📝 **Desktop Subtitles** | Words pop up on screen in sync with speech, like karaoke (typewriter lyrics overlay) |\n| 🔇 **No Overlapping Speech** | Multiple messages arrive at once? Queued and spoken one by one (priority speech queue) |\n\nVoice playback is bridge-triggered, not purely automatic. In practice, you need all three layers to be healthy:\n\n1. TTS is available\n2. `desktop-bridge.js` exists and can run\n3. The active agent actually follows `AGENTS.md` and calls `node desktop-bridge.js agent-response \"...\"` before replying\n\nIf layer 3 is missing, the desktop pet may stay silent even though your TTS setup looks correct.\n\n#### 🧠 Persona \u0026 Personality\n\n| Feature | Description |\n|---------|-------------|\n| 🎭 **5 Personality Presets** | Sweet / Professional / Humorous / Cool / Custom — pick one and it talks that way (personality preset system) |\n| 📝 **Auto-Generated Persona Files** | One click generates the AI's \"character sheet\", no manual prompt writing (auto-generate AGENTS.md + SOUL.md + USER.md) |\n| 💬 **Name Your Pet** | Give it a name and set what it calls you, e.g. \"Kiki calls you Boss\" (petName + userName config) |\n\n#### 🛡️ Gateway Guardian\n\n| Feature | Description |\n|---------|-------------|\n| ⚡ **Auto-Restart on Crash** | Detects Gateway not running and auto-starts it for you (Guardian auto-start, triggers after 3 consecutive detection failures) |\n| 📊 **Live Health Monitoring** | Continuously monitors Gateway health, alerts you at first sign of trouble (anomaly detection + health scoring) |\n| 🎙️ **Voice Status Reports** | \"Starting…\", \"Success!\", \"Failed!\" — spoken aloud so you don't have to watch the console (voice status announcement) |\n| 🔄 **Crash Auto-Recovery** | Auto-restarts after crash, max 10 times per hour to prevent infinite loops (auto-restart with rate limiting) |\n| 🩺 **10-Point Health Check** | Gateway / TTS / Model / Port / Cache / Logs — one-click diagnosis with fix suggestions (Doctor self-check) |\n| 🔧 **Safe Guard** | Double-confirms before restart to avoid killing a healthy Gateway (cross-validation with ServiceManager) |\n\n#### 🧙 Setup Wizard\n\n| Feature | Description |\n|---------|-------------|\n| 🎮 **RPG-Style UI** | Wood frames + parchment background + lobster guide + typewriter dialogue, feels like an RPG game (RPG-style Setup Wizard) |\n| 📋 **7 Steps, Fully Configured** | Gateway → Model → Channels → TTS Engine → Voice Settings → Display → End-to-End Test |\n| ⚡ **One-Click Install Missing Deps** | Missing something? One button auto-installs with live progress bar (one-click dependency install + real-time progress) |\n| 🔍 **Auto Environment Detection** | Auto-finds Node.js, Python, the compatibility CLI (OpenClaw), etc. — installed or not, version at a glance (smart environment detection) |\n| ✅ **Full Validation at the End** | 7 checks ensure everything works before you start, no hidden issues (end-to-end validation) |\n\n#### 🎨 Terminal \u0026 Logs\n\n| Feature | Description |\n|---------|-------------|\n| 🌈 **Colorized Console** | Different info in different colors: model names blue, URLs green, errors red — easy to scan (ANSI colorized logging, 12+ modules) |\n| 🔇 **Auto Log Dedup** | Same message won't spam your console, keeps output clean (whitespace-normalized dedup) |\n| 📁 **Auto Log Archiving** | Old logs archived daily, compressed over 10MB, kept for 7 days (log rotation + gzip archiving) |\n| 📊 **Real-Time Perf Monitoring** | Memory, CPU, FPS at your fingertips, auto-alerts when thresholds exceeded (performance monitor + 24h sample history) |\n\n#### 🔁 Model Switching\n\n| Feature | Description |\n|---------|-------------|\n| 🔄 **One-Click AI Brain Swap** | Claude ↔ GPT ↔ Gemini ↔ DeepSeek, no restart needed, 3 seconds (hot model swap via CC-Switch) |\n| 📊 **AI Speed Test** | One-click latency benchmark for each model, pick the fastest (latency benchmark) |\n| ➕ **Add Your Own Models** | 15+ mainstream AI providers supported, or enter your own API endpoint (custom provider + preset templates) |\n| 📜 **Switch History** | Records every model switch — what, when, fully traceable (switch history tracking) |\n\n#### 🔐 Security\n\n| Feature | Description |\n|---------|-------------|\n| 🔑 **Encrypted Key Storage** | API keys encrypted before writing to disk, never plaintext (Electron safeStorage encryption) |\n| 🛡️ **Permission Control** | Pages can't directly call system functions, all operations go through whitelist (IPC whitelist sandbox) |\n| 🧹 **Auto Log Sanitization** | API keys, tokens auto-hidden from logs (log sanitizer) |\n\n#### 🖥️ Desktop Integration\n\n| Feature | Description |\n|---------|-------------|\n| 📌 **Always on Top** | Orb and subtitles stay on top of all windows, never hidden (always-on-top) |\n| 🖱️ **Click-Through Subtitles** | Lyric subtitles are fully click-through, never block what's underneath (mouse-through transparent window) |\n| 🔗 **Auto Desktop Shortcut** | First launch auto-creates desktop shortcut, double-click to start next time (auto .lnk / .app creation) |\n| 📸 **One-Click Screenshot Upload** | Toolbar screenshot button, auto-captures and uploads to Lark (screenshot + Lark upload) |\n| 💬 **Multi-Platform Message Sync** | Discord / Telegram / Lark / WeCom messages all synced for voice readout (multi-channel message sync) |\n| 🍎 **Win + Mac Support** | Windows 10/11 and macOS (Intel \u0026 Apple Silicon) both supported (cross-platform Electron) |\n| 📱 **Tray Menu Control Center** | Right-click tray icon to switch models, check status, run diagnostics, manage sessions (system tray context menu) |\n\n### 🆕 What's New in v3.7.1\n\n\u003e 🩹 **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.\n\n- 🔒 **Chat readiness guard** — KKClaw now blocks Gateway startup and desktop chat sends when Hermes API server support is disabled\n- ✅ **Stricter install detection** — Hermes is only considered installed when the CLI executable is actually present\n- 🧪 **Regression coverage** — Added a test for the “leftover config directory but missing CLI” false-positive case\n\n### 🆕 What's New in v3.7.0\n\n\u003e 🤝 **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.\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"docs/images/hermes-agent-banner.png\" alt=\"Hermes Agent banner\" width=\"100%\"\u003e\n  \u003cp\u003e\u003csub\u003eHermes Agent banner adapted from \u003ca href=\"https://github.com/NousResearch/hermes-agent\"\u003eNousResearch/hermes-agent\u003c/a\u003e\u003c/sub\u003e\u003c/p\u003e\n\u003c/div\u003e\n\n- 🆕 **Hermes compatibility mode** — Supports `KKCLAW_COMPAT_MODE=hermes` plus a persistent `compatMode` setting in `pet-config.json`\n- 🆕 **Backend-aware launcher** — `kkclaw gateway` / `npm start` now lets you choose a compatible backend (OpenClaw / Hermes / Auto) and remembers the last backend you launched\n- 🆕 **External Hermes reuse** — If Hermes Gateway is already running, KKClaw recognizes and reuses it instead of flagging a false ownership conflict\n- 🔧 **Deeper diagnostics** — `kkclaw status` / `kkclaw doctor` / `kkclaw gateway status` now surface backend, CLI path, probe source, log paths, and Hermes API server readiness\n- 🎨 **Backend-themed console banners** — Startup and ready banners switch labels and accent colors for the active compatible backend\n\n### 🆕 What's New in v3.6.0\n\n\u003e 🦞 **Native command workflow!** `kkclaw gateway` now opens the same animated console as `npm start`, with companion commands for status, logs, doctor, and dashboard access\n\n- 🆕 **`kkclaw gateway` entrypoint** — Opens the animated KKClaw terminal and makes startup feel closer to a native CLI workflow\n- 🆕 **`kkclaw doctor`** — Adds a KKClaw-oriented health check for the compatibility CLI, Gateway reachability, Dashboard URL, and process ownership\n- 🆕 **Gateway subcommands** — `status / logs / open / restart / stop` bring a more familiar command surface\n- 🔧 **Gateway ownership diagnostics** — Detects when the Gateway port is alive but owned by an older or external process\n\n### 🆕 What's New in v3.5.2\n\n\u003e ⚡ **UX polish!** Wizard blank page fix + One-click missing dependency installer + Cross-platform support\n\n- ⚡ **One-click Install Missing Deps** — Auto-install edge-tts / sqlite3 / node_modules with real-time progress\n- 🔧 **Cross-platform Install** — Windows (winget/choco), macOS (brew), Linux (apt/yum)\n- 🐛 **Wizard Blank Page Fix** — Fixed 3 syntax errors causing empty wizard content\n- 🐛 **Wizard Error Visualization** — Shows error details instead of blank page for easier debugging\n- 🔇 **Dual Audio Fix** (v3.5.1) — All `new Notification()` use `silent: true` to prevent Windows narration\n- 🖥️ **Shortcut Fix** (v3.5.1) — Desktop shortcut now targets `start.cmd` to show CMD console\n\n\u003e 🎨 **Major UX update!** Global colorized terminal logs + Smart Gateway auto-start + Log dedup \u0026 noise reduction + Auto desktop shortcut on first launch\n\n#### 🎨 Global Colorized Terminal Logs\n- 🆕 **color-log.js** — Centralized ANSI color module with auto-keyword highlighting\n- ✨ **12+ modules migrated** — All startup logs use `colorLog()` / `kvLog()` / `tagLog()`\n- 🎯 **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)\n\n#### 🛡️ Smart Gateway Auto-Start\n- 🆕 **Proactive first launch** — Guardian auto-starts Gateway after 3 consecutive failures instead of waiting forever\n- 🆕 **Voice status announcements** — \"Waiting for Gateway\" / success / failure spoken aloud\n- 🔧 **Cross-validation** — Double-checks with ServiceManager to prevent false restarts\n\n#### 🔇 Log Dedup \u0026 Noise Reduction\n- 🔧 **Fixed Gateway log duplication** — Root cause: `log()` method double-printing; gateway-std* services skip console output\n- 🔧 **Smart stderr filtering** — Only show lines with error/fatal/panic/exception\n- 🔧 **Whitespace-normalized dedup** — `\\s+` → `' '` normalization before Set dedup\n\n#### 🖥️ Auto Desktop Shortcut\n- 🆕 **Auto-create .lnk on first launch** — Creates \"Claw 桌面宠物\" shortcut on desktop\n- 🔧 **PowerShell COM** — WScript.Shell shortcut creation with icon and minimized start\n- 🎙️ **Voice announcement** — \"Desktop shortcut created\" on success\n\n#### 🐛 Fixes\n- Fixed dual audio playback (removed duplicate `voiceSystem.speak()` from messageSync)\n- Fixed duplicate notification logs (desktop-notifier only logs type)\n- Removed DashScope TTS engine, simplified fallback: MiniMax → Edge TTS\n\n### 🚀 Quick Start\n\n#### Prerequisites\n\n- **Node.js** ≥ 18.x ([Download](https://nodejs.org))\n- **Windows** 10/11 or **macOS** 10.15+\n- **Compatible backend**: **OpenClaw** ≥ 2026.x or **Hermes Agent** (latest recommended) ([OpenClaw](https://openclaw.ai) | [Hermes](https://github.com/NousResearch/hermes-agent))\n\n#### Install via ClawHub (Recommended)\n\n```bash\nnpx clawhub@latest install kk43994/desktop-pet\n```\n\n#### Install from GitHub\n\n```bash\ngit clone https://github.com/kk43994/kkclaw.git\ncd kkclaw\nnpm install\nnpm start\n```\n\n\u003e 🧙 **Setup Wizard** will launch automatically on first run — just follow the guide!\n\n#### CLI Entry (Recommended)\n\n```bash\nnpm link\n\nkkclaw gateway          # Open the backend-aware KKClaw terminal with a compatible backend selector (OpenClaw / Hermes / Auto)\nkkclaw gateway status   # Show gateway state, port, and active compatible backend\nkkclaw gateway logs     # Tail gateway logs\nkkclaw doctor           # Run a KKClaw-oriented health check\nkkclaw dashboard        # Open the active backend dashboard / API surface\n```\n\n### 📦 Downloads\n\n| Platform | Arch | Download | Size |\n|----------|------|----------|------|\n| 🪟 **Windows** | x64 | [Setup.exe](https://github.com/kk43994/kkclaw/releases/download/v3.7.1/KKClaw-Desktop-Pet-3.7.1-Setup.exe) | ~150MB |\n| 🍎 **macOS** | Intel | [x64.dmg](https://github.com/kk43994/kkclaw/releases/download/v3.7.1/KKClaw-Desktop-Pet-3.7.1-x64.dmg) | ~160MB |\n| 🍎 **macOS** | Apple Silicon | [arm64.dmg](https://github.com/kk43994/kkclaw/releases/download/v3.7.1/KKClaw-Desktop-Pet-3.7.1-arm64.dmg) | ~160MB |\n\n[📦 All Releases](https://github.com/kk43994/kkclaw/releases)\n\n### 🤝 Contributing\n\n1. **Fork** this repo\n2. Create branch `git checkout -b feature/your-feature`\n3. Commit `git commit -m 'Add: feature description'`\n4. Push `git push origin feature/your-feature`\n5. Open a **Pull Request**\n\n### 📜 License\n\n[MIT License](LICENSE) © 2024-2026 KK\n\n---\n\n## 🙏 致谢\n\n- [OpenClaw](https://openclaw.ai) — 强大的AI助手框架\n- [Electron](https://www.electronjs.org) — 跨平台桌面应用框架\n- [MiniMax](https://www.minimaxi.com) — 高质量语音克隆API\n- [Nomi](https://nomi.ai) \u0026 [AIBI](https://aibi.com) — UI设计灵感\n- [Bunny Hole](https://bunnyhole.com) — 眼睛设计参考\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**用❤️打造 by KK**\n\n[🔝 回到顶部](#-kkclaw-desktop-pet)\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkk43994%2Fkkclaw","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkk43994%2Fkkclaw","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkk43994%2Fkkclaw/lists"}