# 🦞 KKClaw Desktop Pet
**[English](#-english) | [中文](#-中文)**
---
*OpenClaw / Hermes + Desktop Embodiment = A living interface with emotion, voice, and presence*
[](https://github.com/kk43994/kkclaw/releases)
[](https://github.com/NousResearch/hermes-agent)
[](https://github.com/kk43994/kkclaw/actions/workflows/ci.yml)
[](https://github.com/kk43994/kkclaw/stargazers)
[](https://github.com/kk43994/kkclaw/releases)
[](LICENSE)
[](https://github.com/kk43994/kkclaw)
[](https://www.electronjs.org/)
[](https://nodejs.org/)
[](https://github.com/kk43994/kkclaw/releases/latest)
[](https://github.com/kk43994/kkclaw/issues)
[🎥 **在线演示**](https://kk43994.github.io/kkclaw/) | [📦 **下载最新版**](https://github.com/kk43994/kkclaw/releases) | [📖 **配置教程**](docs/CONFIGURATION-GUIDE.md) | [💬 **加入社群**](#-社群)
---
## 🌟 项目亮点
给你的兼容后端 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 去重，彻底消除同内容重复
#### 🖥️ 首次启动自动创建桌面快捷方式
- 🆕 **自动创建 .lnk** — 首次启动自动在桌面创建"Claw 桌面宠物"快捷方式
- 🔧 **PowerShell COM 对象** — 使用 WScript.Shell 创建快捷方式，设置图标和最小化启动
- 🔧 **智能跳过** — 已存在快捷方式或非 Windows 平台自动跳过
- 🎙️ **语音播报** — 创建成功后播报"桌面快捷方式已创建"
#### 🔧 其他修复
- 🐛 **修复语音双响** — 移除 messageSync 中重复的 `voiceSystem.speak()` 调用
- 🐛 **修复通知日志重复** — desktop-notifier 只打印通知类型，不重复打印 payload
- 🐛 **DashScope TTS 引擎移除** — 语音降级链简化为 MiniMax → Edge TTS
### 🆕 v3.1.2 — 安全加固 & 模型管理升级
> 🔒 **安全重点更新！** 命令注入修复 + 动态 Token 管理 + 模型热切换状态机 + Gateway 智能监控
#### 🧙 Setup Wizard 配置向导（全新）
- 🎮 **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文件 / 音色
#### 🌈 情绪系统升级
- 🌈 **7 → 14 种情绪** — 新增 sad、angry、fearful、calm、excited、love、focused
- ✨ **动态外发光** — 每种情绪有专属 glow 光效
- 🎭 **情绪文本检测** — `desktop-bridge.js` 自动分析内容情绪，10种匹配规则
#### 🔐 安全与稳定性
- 🔑 **API Key 加密存储** — `safeStorage` 加密，密钥不再明文写入磁盘
- 🔒 **preload 安全沙箱** — 主窗口/歌词/诊断/模型设置全部走 IPC 白名单，渲染进程不再直接 require Node
- 🎵 **歌词窗口 Ready 守卫** — `lyricsReady` 标志位，防止加载未完成时崩溃
- 🔧 **sendLyric 封装** — 统一歌词推送，自动检查窗口状态
- 📡 **端口持久化** — 通知端口写入配置，wizard/bridge 可动态获取
- 📡 **渲染进程错误转发** — `preload-error` + `console-message` 转发到主进程日志，防止静默失败
#### 🩺 诊断与运维
- 🆕 **Doctor 自检系统** — 10 项全自动诊断（Gateway / 托盘 / TTS配置 / 模型 / 端口 / 健康度 / 缓存 / 歌词 / 日志），每项带修复建议
- 🆕 **会话刷新** — 损坏会话一键清理重连（`doRefreshSession`）
- 🔧 **诊断工具箱 UI 升级** — Doctor 面板新增 summary 统计 + 修复建议 + 分级状态（pass/warn/fail）
#### 🎛️ 模型管理升级
- 🆕 **延迟测速** — 单模型测速 + 全量批量测速（`speedTest` / `speedTestAll`）
- 🆕 **Provider CRUD** — 新增/编辑/删除服务商，编辑 baseUrl 和 API Key
- 🆕 **模型增删** — Provider 内添加/移除模型
- 🆕 **预设快速添加** — 内置主流 Provider 预设模板，一键填入配置
#### 🎙️ 语音系统增强
- 🆕 **MiniMax Speech 2.8 HD** — 新增高清语音引擎选项
- 🔄 **SmartVoice 配置统一** — 直接读 petConfig，不用重复读文件
- 🎤 **完整版 desktop-bridge.js** — cleanForTTS + detectEmotion + addTTSPauseMarkers
- 🎵 **歌词 TTS 标记过滤** — `<#0.3#>` 停顿标记不显示在字幕中，只给语音引擎用
#### 📖 文档
- 🆕 **完整配置教程** — [CONFIGURATION-GUIDE.md](docs/CONFIGURATION-GUIDE.md)（863行），从零开始手把手教学
### v2.2.1 特性
- 🔧 **诊断工具箱** — 全新独立窗口，一键查看 Gateway 状态、日志、连接信息
- 🔇 **CMD 屏闪修复** — 全面添加 `windowsHide: true`，彻底消除 Windows 命令行窗口闪烁
### v2.2.0 特性
- 🛡️ **Gateway 错误诊断链路** — 捕获 stdout/stderr，桌面通知显示具体崩溃原因
- 🔄 **安全模型切换 + 自动回滚** — 切换失败 5 秒内自动恢复上一个模型
- 📊 **会话管理托盘菜单** — 查看上下文使用率、token 估算、一键清理会话
- 📡 **请求追踪系统** — 序列 ID + 计时 + 错误历史(50条) + 30s 超时诊断
- ⏳ **启动宽限期** — 60s 冷启动保护，防止误判重启循环
- 🧠 **上下文感知** — 中英文 token 估算，接近限制时智能警告
---
## 🎬 演示视频
### 直接点击播放 ▶️
您的浏览器不支持视频播放。点击查看B站版本
**居然让 OpenClaw 给自己做了个身体！**
[📱 B站视频](https://b23.tv/85bz09G) | [📱 抖音视频](https://v.douyin.com/9wKpkB8z4ew/)
| 平台 | 架构 | 下载链接 | 大小 |
|------|------|----------|------|
| 🪟 **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 |
| 🍎 **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 |
| 🍎 **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 |
[📦 查看所有版本](https://github.com/kk43994/kkclaw/releases) | [🎥 在线演示](https://kk43994.github.io/kkclaw/)
### ⚠️ 推荐使用方式：克隆仓库
> **建议有一定技术基础的用户直接克隆仓库运行，而非下载发行版。**
>
> 发行版为打包封装版本，存在以下限制：
> - 部分配置已硬编码在包内，自定义修改需要解包，不适合新手
> - 小版本的 bug 修复和功能更新不会单独推发行版，克隆仓库后 `git pull` 即可同步最新改动
>
> ```bash
> git clone https://github.com/kk43994/kkclaw.git
> cd kkclaw
> npm install
> npm start
> ```
>
> 发行版适合只想快速体验的用户，长期使用推荐源码运行。
### 命令行入口（推荐）
```bash
npm link
kkclaw gateway # 打开带兼容后端选择器的 KKClaw Gateway 终端（OpenClaw / Hermes / Auto）
kkclaw gateway status # 查看网关状态 / 端口 / 当前兼容后端
kkclaw gateway logs # 查看 Gateway 日志
kkclaw doctor # 做一轮 KKClaw 体检
kkclaw dashboard # 打开当前兼容后端的 Dashboard / API 面板
```
### 安装说明
#### Windows
1. 下载 `.exe` 安装程序
2. 双击运行（可能需要允许"未知发布者"）
3. 按提示完成安装
#### macOS
1. 下载对应架构的 `.dmg` 文件
2. 打开 DMG，拖动应用到 Applications 文件夹
3. 首次运行需要在"系统偏好设置 → 安全性与隐私"中允许
> **注意**：macOS 版本未签名，首次运行需要右键点击 → "打开"
---
## 📸 预览
### 🎨 14种情绪色系
**丰富的情绪状态** — 14种颜色 × 38种表情 = 超自然的情感表达
---
### 🔧 精灵窗口 + 工具栏
**67px 琉璃球体**
- 3层流体动画
- 双重高光系统
- 胶囊形发光眼睛
**SVG图标工具栏**
- 💬 聊天对话
- 📸 截图上传
- 🎤 语音切换
- ⚙️ 设置面板
---
### 💬 聊天交互演示
**智能对话 + 文件操作** — 可以与桌面图标、文件进行自然语言交互
*示例：KK要复制图标文件，直接用红框标记图标，用飞书语音创建快捷方式*
| 平台 | 链接 | 说明 |
|------|------|------|
| 💬 **AI Coding 交流群** | [扫码加入](docs/images/ai-coding-qr.jpg) | 微信群（7天有效） |
| 🐦 **Discord** | [Friends of the Crustacean](https://discord.com/invite/clawd) | OpenClaw国际社区 |
| 🇨🇳 **OpenClaw-CN** | [clawd.org.cn](https://clawd.org.cn) | 中文论坛 |
| 📦 **ClawHub** | [clawhub.ai](https://clawhub.ai/kk43994/desktop-pet) | 技能市场 |
| 💡 **GitHub Discussions** | [讨论区](https://github.com/kk43994/kkclaw/discussions) | 提问、分享 |
### 支持项目
如果这个项目帮助了你，欢迎：
- ⭐ **Star** 本仓库
- 🐛 **报告Bug** 或提需求
- 📢 **分享**给朋友
- ☕ [**赞赏支持**](docs/images/support-qr.jpg)
---
## 📜 开源协议
[MIT License](LICENSE) © 2024-2026 KK
---
[](https://github.com/kk43994/kkclaw/releases)
[](https://github.com/NousResearch/hermes-agent)
[](LICENSE)
[](https://github.com/kk43994/kkclaw)
[🎥 **Live Demo**](https://kk43994.github.io/kkclaw/) | [📦 **Download**](https://github.com/kk43994/kkclaw/releases) | [📖 **Docs**](docs/CONFIGURATION-GUIDE.md) | [💬 **Community**](#-社群)
### ✨ Highlights
Give your compatible-backend AI (OpenClaw / Hermes) a **visible, audible** desktop embodiment.
#### 🦞 Orb & Animation
| Feature | Description |
|---------|-------------|
| 🔮 **Living Glass Orb** | 67px glass sphere with fluid constantly flowing inside, looks alive (3-layer fluid animation + radial gradient + dual highlights) |
| 🌈 **14 Mood Colors** | Happy = warm orange, sad = sky blue, angry = fire red… auto-switches color and glow per mood (14-emotion glow system) |
| 👀 **38 Micro-Expressions** | Blinks, tilts, peeks, dozes, sparkle eyes, plays dead while idle… like it has a personality (idle micro-expression engine) |
| 🕐 **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) |
| 🖱️ **Eye Tracking** | Eyes follow your cursor direction as you move the mouse (mouse tracking) |
| 💗 **Blushing** | Certain expressions trigger pink blush on both cheeks (dynamic blush overlay) |
| 🫧 **Floating Bubbles** | Semi-transparent bubbles floating around the orb for extra liveliness (bubble particle decoration) |
| ✨ **Bounce on Click** | Click the orb and it squishes + flashes color, satisfying feedback (squish animation + color pulse) |
| 🎈 **Breathing Float** | Orb gently bobs up and down, like floating on water (60fps float + breath scaling) |
#### 🎙️ Voice & Audio
| Feature | Description |
|---------|-------------|
| 🎤 **30s Voice Cloning** | Upload a 30-second recording, AI speaks in your voice (MiniMax Voice Cloning API) |
| 🗣️ **14 Auto Tone Shifts** | Happy news = cheerful voice, sad news = subdued voice, auto-detected (emotion-aware TTS) |
| 🔉 **Never Goes Silent** | Primary engine down → auto-switches to backup → then free fallback, always has a voice (MiniMax → Edge TTS fallback chain) |
| ⏸️ **Natural Pauses** | Pauses at commas and periods, not robotic read-aloud (TTS pause markers `<#0.5#>`) |
| 📝 **Desktop Subtitles** | Words pop up on screen in sync with speech, like karaoke (typewriter lyrics overlay) |
| 🔇 **No Overlapping Speech** | Multiple messages arrive at once? Queued and spoken one by one (priority speech queue) |
Voice playback is bridge-triggered, not purely automatic. In practice, you need all three layers to be healthy:
1. TTS is available
2. `desktop-bridge.js` exists and can run
3. The active agent actually follows `AGENTS.md` and calls `node desktop-bridge.js agent-response "..."` before replying
If layer 3 is missing, the desktop pet may stay silent even though your TTS setup looks correct.
#### 🧠 Persona & Personality
| Feature | Description |
|---------|-------------|
| 🎭 **5 Personality Presets** | Sweet / Professional / Humorous / Cool / Custom — pick one and it talks that way (personality preset system) |
| 📝 **Auto-Generated Persona Files** | One click generates the AI's "character sheet", no manual prompt writing (auto-generate AGENTS.md + SOUL.md + USER.md) |
| 💬 **Name Your Pet** | Give it a name and set what it calls you, e.g. "Kiki calls you Boss" (petName + userName config) |
#### 🛡️ Gateway Guardian
| Feature | Description |
|---------|-------------|
| ⚡ **Auto-Restart on Crash** | Detects Gateway not running and auto-starts it for you (Guardian auto-start, triggers after 3 consecutive detection failures) |
| 📊 **Live Health Monitoring** | Continuously monitors Gateway health, alerts you at first sign of trouble (anomaly detection + health scoring) |
| 🎙️ **Voice Status Reports** | "Starting…", "Success!", "Failed!" — spoken aloud so you don't have to watch the console (voice status announcement) |
| 🔄 **Crash Auto-Recovery** | Auto-restarts after crash, max 10 times per hour to prevent infinite loops (auto-restart with rate limiting) |
| 🩺 **10-Point Health Check** | Gateway / TTS / Model / Port / Cache / Logs — one-click diagnosis with fix suggestions (Doctor self-check) |
| 🔧 **Safe Guard** | Double-confirms before restart to avoid killing a healthy Gateway (cross-validation with ServiceManager) |
#### 🧙 Setup Wizard
| Feature | Description |
|---------|-------------|
| 🎮 **RPG-Style UI** | Wood frames + parchment background + lobster guide + typewriter dialogue, feels like an RPG game (RPG-style Setup Wizard) |
| 📋 **7 Steps, Fully Configured** | Gateway → Model → Channels → TTS Engine → Voice Settings → Display → End-to-End Test |
| ⚡ **One-Click Install Missing Deps** | Missing something? One button auto-installs with live progress bar (one-click dependency install + real-time progress) |
| 🔍 **Auto Environment Detection** | Auto-finds Node.js, Python, the compatibility CLI (OpenClaw), etc. — installed or not, version at a glance (smart environment detection) |
| ✅ **Full Validation at the End** | 7 checks ensure everything works before you start, no hidden issues (end-to-end validation) |
#### 🎨 Terminal & Logs
| Feature | Description |
|---------|-------------|
| 🌈 **Colorized Console** | Different info in different colors: model names blue, URLs green, errors red — easy to scan (ANSI colorized logging, 12+ modules) |
| 🔇 **Auto Log Dedup** | Same message won't spam your console, keeps output clean (whitespace-normalized dedup) |
| 📁 **Auto Log Archiving** | Old logs archived daily, compressed over 10MB, kept for 7 days (log rotation + gzip archiving) |
| 📊 **Real-Time Perf Monitoring** | Memory, CPU, FPS at your fingertips, auto-alerts when thresholds exceeded (performance monitor + 24h sample history) |
#### 🔁 Model Switching
| Feature | Description |
|---------|-------------|
| 🔄 **One-Click AI Brain Swap** | Claude ↔ GPT ↔ Gemini ↔ DeepSeek, no restart needed, 3 seconds (hot model swap via CC-Switch) |
| 📊 **AI Speed Test** | One-click latency benchmark for each model, pick the fastest (latency benchmark) |
| ➕ **Add Your Own Models** | 15+ mainstream AI providers supported, or enter your own API endpoint (custom provider + preset templates) |
| 📜 **Switch History** | Records every model switch — what, when, fully traceable (switch history tracking) |
#### 🔐 Security
| Feature | Description |
|---------|-------------|
| 🔑 **Encrypted Key Storage** | API keys encrypted before writing to disk, never plaintext (Electron safeStorage encryption) |
| 🛡️ **Permission Control** | Pages can't directly call system functions, all operations go through whitelist (IPC whitelist sandbox) |
| 🧹 **Auto Log Sanitization** | API keys, tokens auto-hidden from logs (log sanitizer) |
#### 🖥️ Desktop Integration
| Feature | Description |
|---------|-------------|
| 📌 **Always on Top** | Orb and subtitles stay on top of all windows, never hidden (always-on-top) |
| 🖱️ **Click-Through Subtitles** | Lyric subtitles are fully click-through, never block what's underneath (mouse-through transparent window) |
| 🔗 **Auto Desktop Shortcut** | First launch auto-creates desktop shortcut, double-click to start next time (auto .lnk / .app creation) |
| 📸 **One-Click Screenshot Upload** | Toolbar screenshot button, auto-captures and uploads to Lark (screenshot + Lark upload) |
| 💬 **Multi-Platform Message Sync** | Discord / Telegram / Lark / WeCom messages all synced for voice readout (multi-channel message sync) |
| 🍎 **Win + Mac Support** | Windows 10/11 and macOS (Intel & Apple Silicon) both supported (cross-platform Electron) |
| 📱 **Tray Menu Control Center** | Right-click tray icon to switch models, check status, run diagnostics, manage sessions (system tray context menu) |
### 🆕 What's New in v3.7.1
> 🩹 **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.
- 🔒 **Chat readiness guard** — KKClaw now blocks Gateway startup and desktop chat sends when Hermes API server support is disabled
- ✅ **Stricter install detection** — Hermes is only considered installed when the CLI executable is actually present
- 🧪 **Regression coverage** — Added a test for the “leftover config directory but missing CLI” false-positive case
### 🆕 What's New in v3.7.0
> 🤝 **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.
- 🆕 **Hermes compatibility mode** — Supports `KKCLAW_COMPAT_MODE=hermes` plus a persistent `compatMode` setting in `pet-config.json`
- 🆕 **Backend-aware launcher** — `kkclaw gateway` / `npm start` now lets you choose a compatible backend (OpenClaw / Hermes / Auto) and remembers the last backend you launched
- 🆕 **External Hermes reuse** — If Hermes Gateway is already running, KKClaw recognizes and reuses it instead of flagging a false ownership conflict
- 🔧 **Deeper diagnostics** — `kkclaw status` / `kkclaw doctor` / `kkclaw gateway status` now surface backend, CLI path, probe source, log paths, and Hermes API server readiness
- 🎨 **Backend-themed console banners** — Startup and ready banners switch labels and accent colors for the active compatible backend
### 🆕 What's New in v3.6.0
> 🦞 **Native command workflow!** `kkclaw gateway` now opens the same animated console as `npm start`, with companion commands for status, logs, doctor, and dashboard access
- 🆕 **`kkclaw gateway` entrypoint** — Opens the animated KKClaw terminal and makes startup feel closer to a native CLI workflow
- 🆕 **`kkclaw doctor`** — Adds a KKClaw-oriented health check for the compatibility CLI, Gateway reachability, Dashboard URL, and process ownership
- 🆕 **Gateway subcommands** — `status / logs / open / restart / stop` bring a more familiar command surface
- 🔧 **Gateway ownership diagnostics** — Detects when the Gateway port is alive but owned by an older or external process
### 🆕 What's New in v3.5.2
> ⚡ **UX polish!** Wizard blank page fix + One-click missing dependency installer + Cross-platform support
- ⚡ **One-click Install Missing Deps** — Auto-install edge-tts / sqlite3 / node_modules with real-time progress
- 🔧 **Cross-platform Install** — Windows (winget/choco), macOS (brew), Linux (apt/yum)
- 🐛 **Wizard Blank Page Fix** — Fixed 3 syntax errors causing empty wizard content
- 🐛 **Wizard Error Visualization** — Shows error details instead of blank page for easier debugging
- 🔇 **Dual Audio Fix** (v3.5.1) — All `new Notification()` use `silent: true` to prevent Windows narration
- 🖥️ **Shortcut Fix** (v3.5.1) — Desktop shortcut now targets `start.cmd` to show CMD console
> 🎨 **Major UX update!** Global colorized terminal logs + Smart Gateway auto-start + Log dedup & noise reduction + Auto desktop shortcut on first launch
#### 🎨 Global Colorized Terminal Logs
- 🆕 **color-log.js** — Centralized ANSI color module with auto-keyword highlighting
- ✨ **12+ modules migrated** — All startup logs use `colorLog()` / `kvLog()` / `tagLog()`
- 🎯 **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)
#### 🛡️ Smart Gateway Auto-Start
- 🆕 **Proactive first launch** — Guardian auto-starts Gateway after 3 consecutive failures instead of waiting forever
- 🆕 **Voice status announcements** — "Waiting for Gateway" / success / failure spoken aloud
- 🔧 **Cross-validation** — Double-checks with ServiceManager to prevent false restarts
#### 🔇 Log Dedup & Noise Reduction
- 🔧 **Fixed Gateway log duplication** — Root cause: `log()` method double-printing; gateway-std* services skip console output
- 🔧 **Smart stderr filtering** — Only show lines with error/fatal/panic/exception
- 🔧 **Whitespace-normalized dedup** — `\s+` → `' '` normalization before Set dedup
#### 🖥️ Auto Desktop Shortcut
- 🆕 **Auto-create .lnk on first launch** — Creates "Claw 桌面宠物" shortcut on desktop
- 🔧 **PowerShell COM** — WScript.Shell shortcut creation with icon and minimized start
- 🎙️ **Voice announcement** — "Desktop shortcut created" on success
#### 🐛 Fixes
- Fixed dual audio playback (removed duplicate `voiceSystem.speak()` from messageSync)
- Fixed duplicate notification logs (desktop-notifier only logs type)
- Removed DashScope TTS engine, simplified fallback: MiniMax → Edge TTS
### 🚀 Quick Start
#### Prerequisites
- **Node.js** ≥ 18.x ([Download](https://nodejs.org))
- **Windows** 10/11 or **macOS** 10.15+
- **Compatible backend**: **OpenClaw** ≥ 2026.x or **Hermes Agent** (latest recommended) ([OpenClaw](https://openclaw.ai) | [Hermes](https://github.com/NousResearch/hermes-agent))
#### Install via ClawHub (Recommended)
```bash
npx clawhub@latest install kk43994/desktop-pet
```
#### Install from GitHub
```bash
git clone https://github.com/kk43994/kkclaw.git
cd kkclaw
npm install
npm start
```
> 🧙 **Setup Wizard** will launch automatically on first run — just follow the guide!
#### CLI Entry (Recommended)
```bash
npm link
kkclaw gateway # Open the backend-aware KKClaw terminal with a compatible backend selector (OpenClaw / Hermes / Auto)
kkclaw gateway status # Show gateway state, port, and active compatible backend
kkclaw gateway logs # Tail gateway logs
kkclaw doctor # Run a KKClaw-oriented health check
kkclaw dashboard # Open the active backend dashboard / API surface
```
### 📦 Downloads
| Platform | Arch | Download | Size |
|----------|------|----------|------|
| 🪟 **Windows** | x64 | [Setup.exe](https://github.com/kk43994/kkclaw/releases/download/v3.7.1/KKClaw-Desktop-Pet-3.7.1-Setup.exe) | ~150MB |
| 🍎 **macOS** | Intel | [x64.dmg](https://github.com/kk43994/kkclaw/releases/download/v3.7.1/KKClaw-Desktop-Pet-3.7.1-x64.dmg) | ~160MB |
| 🍎 **macOS** | Apple Silicon | [arm64.dmg](https://github.com/kk43994/kkclaw/releases/download/v3.7.1/KKClaw-Desktop-Pet-3.7.1-arm64.dmg) | ~160MB |
[📦 All Releases](https://github.com/kk43994/kkclaw/releases)
### 🤝 Contributing
1. **Fork** this repo
2. Create branch `git checkout -b feature/your-feature`
3. Commit `git commit -m 'Add: feature description'`
4. Push `git push origin feature/your-feature`
5. Open a **Pull Request**
### 📜 License
[MIT License](LICENSE) © 2024-2026 KK
---
## 🙏 致谢
- [OpenClaw](https://openclaw.ai) — 强大的AI助手框架
- [Electron](https://www.electronjs.org) — 跨平台桌面应用框架
- [MiniMax](https://www.minimaxi.com) — 高质量语音克隆API
- [Nomi](https://nomi.ai) & [AIBI](https://aibi.com) — UI设计灵感
- [Bunny Hole](https://bunnyhole.com) — 眼睛设计参考
---
**用❤️打造 by KK**
[🔝 回到顶部](#-kkclaw-desktop-pet)
