• TTS 引擎和声音
• 球体颜色和大小
• OpenClaw Gateway 连接
• 情绪映射规则
• Setup Wizard 首次引导流程

目录结构

kkclaw/
├── main.js              # Electron 主进程
├── index.html           # 球体渲染 UI
├── lyrics.html          # 歌词字幕窗口
├── setup-wizard.html    # Setup Wizard 界面
├── setup-wizard.js      # Setup Wizard 逻辑
├── gateway-client.js    # Gateway 通信客户端
├── smart-voice.js       # 语音调度系统
├── templates/           # Agent 模板文件
├── voice/               # TTS 引擎模块
├── utils/               # 工具模块
├── scripts/             # 构建脚本
└── docs-dev/            # 开发文档

链接

• GitHub: https://github.com/kk43994/kkclaw
• Landing Page: https://kk43994.github.io/kkclaw/
• ClawHub: https://clawhub.ai/kk43994/desktop-pet
• 版本: v3.1.2

🎥 在线演示 | 📦 下载最新版 | 📖 配置教程 | 💬 加入社群

🌟 项目亮点

给你的兼容后端 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 去重，彻底消除同内容重复

🖥️ 首次启动自动创建桌面快捷方式

• 🆕