name: kkclaw description: 给你的 AI Agent 一个桌面身体 — Setup Wizard、14情绪球体、语音克隆、歌词窗、Doctor 自检、跨平台支持（Windows + macOS） version: 3.1.2 author: xiao-k-assistant tags: [desktop-pet, electron, tts, voice, emotion, openclaw, visualization, cross-platform]

kkclaw — 桌面龙虾 AI 伴侣

给你的 AI Agent 一个桌面身体：可视化球体 + 语音交互 + 情绪表达。

功能特性

• 🧙 Setup Wizard — 首次运行引导配置，3 分钟上手
• 🔐 safeStorage 加密 — API Key 本地加密存储，不再明文
• 🎭 人设定制 — 自动生成 AGENTS.md / SOUL.md / USER.md / HEARTBEAT.md
• 🎵 声音系统 — MiniMax 声音克隆 + CosyVoice + Edge TTS 三级降级，永不失声
• 👀 情绪表达 — 14 种情绪 + 多种眼睛微表情 + 动态 glow 光效
• 🩺 Doctor 自检 — 一键诊断 Gateway / 模型 / TTS / 端口 / 日志 / 歌词窗
• 🎛️ 模型管理 — Provider CRUD、模型增删、延迟测速、预设快速添加
• 🧠 Gateway 同步 — WebSocket 实时同步 OpenClaw Agent 状态，毫秒级响应
• 💪 7x24 可靠 — 自动恢复、健康评分监控、Switch Logger
• 🖥️ 轻量渲染 — 纯 HTML/CSS/JS 球体，CSS radial-gradient 琉璃质感，不依赖框架
• 🎤 语音播报 — Agent 回复自动转语音，支持情感识别与停顿标记
• 🖱️ 桌面集成 — 窗口置顶、鼠标穿透、拖动跟随、歌词式字幕窗口

技术栈

• Electron（桌面容器）
• OpenClaw Gateway（WebSocket 通信）
• MiniMax Speech / CosyVoice / Edge TTS（语音合成）
• CSS Animation + requestAnimationFrame（球体动画）

安装

git clone https://github.com/kk43994/kkclaw.git
cd kkclaw
npm install
npm start

或下载安装包：

• Windows: https://github.com/kk43994/kkclaw/releases/download/v3.1.2/KKClaw-Desktop-Pet-3.1.2-Setup.exe
• macOS (Intel): https://github.com/kk43994/kkclaw/releases/download/v3.1.2/KKClaw-Desktop-Pet-3.1.2-x64.dmg
• macOS (Apple Silicon): https://github.com/kk43994/kkclaw/releases/download/v3.1.2/KKClaw-Desktop-Pet-3.1.2-arm64.dmg

配置

编辑 pet-config.json 自定义：

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

目录结构

kkclaw/
├── main.js              # Electron 主进程
├── index.html           # 球体渲染 UI
├── lyrics.html          # 歌词字幕窗口
├── setup-wizard.html    # Setup Wizard 界面
├── setup-wizard.js      # Setup Wizard 逻辑
├── openclaw-client.js   # Gateway WebSocket 客户端
├── 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

🦞 KKClaw Desktop Pet

English | 中文

<a id="-中文"></a>

🇨🇳 中文

OpenClaw 桌面可视化伴侣 — 流体玻璃球宠物、14情绪系统、声音克隆（MiniMax TTS）、一键配置向导、Gateway 智能守护

OpenClaw Core + Desktop Embodiment = A living interface with emotion, voice, and presence

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

🌟 项目亮点

给你的 OpenClaw AI 一个看得见、听得到的桌面化身。

🦞 球体 & 动画

| 功能 | 说明 | |------|------| | 🔮 流体玻璃球 | 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种情��语调...