🦞 KKClaw Desktop Pet
🇨🇳 中文
OpenClaw / Hermes 桌面可视化伴侣 — 流体玻璃球宠物、14情绪系统、声音克隆（MiniMax TTS）、Hermes 兼容模式、一键配置向导、Gateway 智能守护
OpenClaw / Hermes + Desktop Embodiment = A living interface with emotion, voice, and presence
🎥 在线演示 | 📦 下载最新版 | 📖 配置教程 | 💬 加入社群
🌟 项目亮点
给你的兼容后端 AI（OpenClaw / Hermes）一个看得见、听得到的桌面化身。
🦞 球体 & 动画
| 功能 | 说明 |
|---|---|
| 🔮 流体玻璃球 | 67px 琉璃质感球体，内部液体持续流动，宛如活物（3层流体动画 + 径向渐变 + 双重高光） |
| 🌈 14种心情变色 | 开心暖橙、伤心天蓝、生气火红……每种情绪对应独立颜色与光晕效果（14-emotion glow system） |
| 👀 38种待机微表情 | 待机时自动播放眨眼、歪头、偷瞄、打盹、星星眼、装死等表情，营造鲜活性格感（idle micro-expression engine） |
| 🕐 时间感知表情 | 早晨活力、午后困倦、深夜哈欠——自动感知当前时段并切换表情（时间场景感知：morning / noon / afternoon / evening / latenight） |
| 🖱️ 鼠标跟踪眼神 | 球体眼睛跟随光标方向转动，增强互动感（mouse tracking） |
| 💗 害羞脸红 | 特定表情触发时，脸颊浮现粉色红晕（dynamic blush overlay） |
| 🫧 气泡装饰粒子 | 球体周围飘浮半透明气泡，增添灵动氛围（bubble particle decoration） |
| ✨ 点击弹跳反馈 | 点击球体产生弹性压缩 + 颜色脉冲，操作有手感（squish animation + color pulse） |
| 🎈 悬浮呼吸效果 | 球体微幅上下浮动，如同水面漂浮（60fps float + breath scaling） |
🎙️ 声音 & 语音
| 功能 | 说明 |
|---|---|
| 🎤 一键声音克隆 | 上传30秒录音即可克隆声音，AI 用你自己的音色说话（MiniMax Voice Cloning API） |
| 🎵 8种预设音色 | 无需克隆，直接选择官方预设音色即可使用（8 preset voices） |
| 🗣️ 14种情��语调 | 根据文本内容自动匹配情绪语气——欢快、低沉、激动等自然切换（emotion-aware TTS） |
| 🔉 智能降级链 | 主引擎故障自动切备用引擎，确保语音永不中断（MiniMax → Edge TTS 降级链） |
| ⏸️ 自然停顿 | 在标点符号处自动添加语气停顿，告别机器人式朗读（TTS pause markers <#0.5#>） |
| 📝 桌面字幕同步 | 语音播报时同步显示逐字字幕，打字机效果呈现（typewriter lyrics overlay） |
| 🔇 消息排队播报 | 多条消息同时到达时自动排队，逐条播出不叠音（priority speech queue） |
| 🚫 重复消息过滤 | 相同内容自动去重，避免重复播报（whitespace-normalized dedup filter） |
🧠 人设 & 性格
| 功能 | 说明 |
|---|---|
| 🎭 5种性格预设 | 甜妹 / 专业 / 幽默 / 酷帅 / 自定义，一键切换说话风格（personality preset system） |
| 📝 人设文件自动生成 | 选定性格后一键生成 AI 人格档案，无需手写提示词（auto-generate AGENTS.md + SOUL.md + USER.md） |
| 💬 自定义称呼 | 自定义宠物名称和对你的称呼，如「小K叫你主人」（petName + userName 配置） |
🛡️ Gateway 智能守护
| 功能 | 说明 |
|---|---|
| ⚡ 自动拉起 | 连续3次检测 Gateway 不在线后自动启动，无需手动干预（Guardian auto-start） |
| 📊 实时健康监控 | 后台持续采集 Gateway 运行指标，异常时第一时间告警（anomaly detection + health scoring） |
| 🎙️ 语音状态播报 | 启动中 / 成功 / 失败均有语音通知，不必盯控制台（voice status announcement） |
| 🔄 崩溃自动重启 | Gateway 异常退出后自动拉起，每小时上限10次防止死循环（auto-restart with rate limiting） |
| 🩺 10项一键体检 | Gateway / TTS / 模型 / 端口 / 缓存 / 日志等10维一键诊断，附修复建议（Doctor self-check） |
| 🔧 双重确认防误判 | 重启前与 ServiceManager 交叉校验，避免误杀健康实例（cross-validation with ServiceManager） |
| ⏳ 启动宽限期 | 首次启动60秒内不触发重启逻辑，给 Gateway 充足启动时间（startup grace period） |
🧙 新手引导向导
| 功能 | 说明 |
|---|---|
| 🎮 RPG 游戏风格 | 木质边框 + 羊皮纸纹理 + 龙虾向导 NPC + 打字机对白（RPG-style Setup Wizard） |
| 📋 7步全流程引导 | Gateway → 模型 → 消息渠道 → 语音引擎 → 播报设置 → 显示选项 → 全链路测试 |
| ⚡ 缺失依赖一键安装 | 检测到缺失依赖后一键安装，实时显示安装进度（one-click dependency install + real-time progress） |
| 🔍 智能环境检测 | 自动探测 Node.js / Python / 兼容 CLI（OpenClaw）等环境状态及版本信息（smart environment detection） |
| ✅ 全链路验证 | 7项端到端测试确保所有功能正常运行（end-to-end validation） |
| 🐛 错误可视化 | 向导异常时直接显示报错信息，不再白屏无提示（error visualization + crash recovery） |
🎨 终端 & 日志
| 功能 | 说明 |
|---|---|
| 🌈 彩色终端日志 | 12+ 模块统一彩色输出——模型名青色、URL绿色、错误红色，一目了然（ANSI colorized logging） |
| 🔇 日志自动去重 | 空白归一化后去重，消除控制台刷屏（whitespace-normalized dedup） |
| 📁 日志轮转归档 | 按天归档、超10MB自动压缩、保留7天历史（log rotation + gzip archiving） |
| 📊 性能实时监控 | 内存 / CPU / 帧率实时采集，超阈值自动告警（performance monitor + 24h sample history） |
🔁 模型切换
| 功能 | 说明 |
|---|---|
| 🔄 热切换 | Claude ↔ GPT ↔ Gemini ↔ DeepSeek 无需重启，3秒生效（hot model swap via CC-Switch） |
| 📊 延迟测速 | 一键对比各模型响应延迟，选择最优（latency benchmark） |
| ➕ 自由添加模型 | 支持15+主流 AI 服务商，也可自定义 API 端点（custom provider + preset templates） |
| 📜 切换历史追溯 | 完整记录每次模型切换的时间与来源（switch history tracking） |
| ↩️ 失败自动回滚 | 新模型5秒内无响应，自动回退到上一可用模型（optimistic update + 5s rollback） |
🔐 安全
| 功能 | 说明 |
|---|---|
| 🔑 密钥加密存储 | API Key 经 Electron safeStorage 加密后写盘，杜绝明文泄露 |
| 🛡️ IPC 权限沙箱 | 渲染进程无法直接调用系统 API，所有操作经白名单校验（IPC whitelist sandbox） |
| 🧹 日志自动脱敏 | 日志中自动遮蔽 API Key、Token 等敏感信息（log sanitizer） |
| 🔒 命令注入防护 | 所有外部命令使用参数数组传递，不拼接字符串（execFile/spawn with args array） |
🖥️ 桌面集成
| 功能 | 说明 |
|---|---|
| 📌 永远置顶 | 球体与字幕窗口始终位于最上层，不被其他窗口遮挡（always-on-top） |
| 🖱️ 字幕穿透点击 | 歌词字幕窗口完全穿透鼠标事件，不影响底层操作（mouse-through transparent window） |
| 🔗 自动创建桌面快捷方式 | 首次启动自动生成桌面快捷方式，下次双击即用（auto .lnk / .app creation） |
| 📸 截图一键上传 | 工具栏一键截屏，自动上传至飞书（screenshot + Lark upload） |
| 💬 多平台消息同步 | Discord / Telegram / 飞书 / 企业微信消息统一同步并语音播报（multi-channel message sync） |
| 🍎 跨平台支持 | Windows 10/11 + macOS（Intel & Apple Silicon）双平台原生支持（cross-platform Electron） |
| 📱 托盘菜单 | 右键系统托盘即可切换模型、查看状态、启动诊断、管理会话（system tray context menu） |
🆕 v3.7.1 — Hermes 聊天可用性修复
🩹 补丁更新！ 修复 Hermes 兼容模式下两个容易误导用户的边界：没开 API server 时不再进入“能启动但不能聊”的半可用状态；只剩配置目录时也不再误判成“已安装 Hermes”。
- 🔒 聊天前置拦截 — Hermes 未启用 API server 时，Gateway 启动和桌面端发消息都会直接给出明确错误，不再继续走
/v1/chat/completions - ✅ 安装判定收紧 — 现在只有真正检测到 Hermes CLI 可执行文件，才会被标记为已安装
- 🧪 新增回归测试 — 增加 “残留
~/.hermes目录但 CLI 缺失” 的假阳性回归测试，避免状态页再次误报
🆕 v3.7.0 — Hermes 兼容模式 + 多后端启动器
🤝 正式适配 Hermes！
kkclaw gateway现在会按兼容后端模式工作：既能拉起 OpenClaw，也能驱动 Hermes，并在启动时提供 OpenClaw / Hermes / Auto 三种入口。
- 🆕 Hermes 兼容模式 — 支持
KKCLAW_COMPAT_MODE=hermes，也支持在pet-config.json中固定compatMode: "hermes" | "openclaw" | "auto" - 🆕 后端选择式启动 —
kkclaw gateway/npm start的终端入口现在会先让你选择兼容后端（OpenClaw / Hermes / Auto），并记住上次选择 - 🆕 Hermes Gateway 复用 — 如果 Hermes Gateway 已经在外部启动，KKClaw 会识别并复用，不再把它误判成端口冲突
- 🔧 诊断全面增强 —
kkclaw status/kkclaw doctor/kkclaw gateway status会显示当前兼容后端、CLI 路径、探活方式、日志路径、API Server 状态 - 🎨 后端感知终端外观 — 启动画面和 Ready Banner 会根据当前兼容后端切换主色和标签，终端体验更统一
🆕 v3.6.0 — 原生命令入口 + KKClaw Gateway CLI
🦞 命令体验升级！
kkclaw gateway现在直接打开带开场动画的终端，并补齐doctor / status / logs / dashboard
- 🆕
kkclaw gateway主入口 — 直接打开现在npm start的动画终端体验，启动习惯更接近原生命令行工作流 - 🆕
kkclaw doctor— 增加 KKClaw 风格体检，检查兼容 CLI、Gateway 连通性、Dashboard 地址和进程归属 - 🆕
kkclaw gateway status / logs / open / restart / stop— 提供贴近兼容后端工作流的子命令 - 🆕
kkclaw dashboard— 直接转发到底层openclaw dashboard - 🔧 状态可观测性增强 —
doctor会提示当前 Gateway 端口是否由 KKClaw 自身占用，帮助排查旧进程/端口冲突
🆕 v3.5.2 — Setup Wizard 修复 + 一键安装缺失依赖
⚡ 体验优化！ Wizard 白屏修复 + 缺失依赖一键安装 + 跨平台支持
- ⚡ 一键安装缺失依赖 — 环境检测页新增按钮，自动安装 edge-tts / sqlite3 / node_modules，实时进度反馈
- 🔧 跨平台安装 — Windows (winget/choco)、macOS (brew)、Linux (apt/yum)
- 🐛 Wizard 白屏修复 — 修复 3 处语法错误导致的向导空白页
- 🐛 Wizard 错误可视化 — 渲染出错时直接显示报错信息，方便用户排查
- 📝 sqlite3 依赖说明 — 标注用途
(CC-Switch 同步)，未安装时提示安装命令
🆕 v3.5.1 — 双声音修复 + 桌面快捷方式修复
- 🔇 双声音修复 — 所有
new Notification()添加silent: true，阻止 Windows 系统朗读 - 🖥️ 快捷方式修复 — 指向
start.cmd，启动时显示 CMD 控制台 + Gateway 日志
🆕 v3.5.0 — 体验大升级：彩色终端 + 智能守护 + 桌面快捷方式
🎨 重大体验更新！ 全局彩色终端日志 + Gateway 智能自启动 + 日志去重降噪 + 首次启动自动创建桌面快捷方式
🎨 全局彩色终端日志系统
- 🆕 color-log.js 中心化模块 — 统一 ANSI 颜色常量 + 自动关键词高亮
- ✨ 12+ 模块全覆盖 — main.js / service-manager / gateway-guardian / smart-voice / message-sync / pet-config / screenshot / log-rotation / performance-monitor / desktop-notifier 全部迁移
- 🎯 Gateway 日志高亮增强 — 模型名(cyan)、URL(green)、路径(dim)、渠道(magenta)、@botname(magenta)、key=value(yellow)、端口号(yellow)、协议(cyan)、错误(red)、成功(green)、警告(yellow)
🛡️ Gateway 智能自启动
- 🆕 首次启动主动拉起 — Guardian 不再永远等待，连续 3 次检测不到 Gateway 后自动执行
startGateway() - 🆕 启动状态语音播报 — 启动中播报"等待Gateway启动中"，成功/失败分别语音通知
- 🔧 二次确认防误判 — 与 ServiceManager 探活交叉校验，避免误触重启
- 🔧 启动期静默 — 首次启动阶段不发告警事件，避免噪音
🔇 日志去重降噪
- 🔧 修复 Gateway 日志重复 — 找到根因：
log()方法在 stdout handler 之后二次console.log()，gateway-std* 服务跳过控制台输出 - 🔧 stderr 智能过滤 — 仅显示含 error/fatal/panic/exception 的真错误行
- 🔧 空白归一化去重 —
\s+→' '归一化后 Set 去重，彻底消除同内容重复
🖥️ 首次启动自动创建桌面快捷方式
- 🆕