kkclaw — Desktop Lobster AI Companion
Give your AI agent a desktop body: a visual sphere + voice interaction + emotional expression.
Features
- 🧙 Setup Wizard — First-run configuration guide, 3 minutes to get started
- 🔐 safeStorage Encryption — API keys stored locally encrypted, no more plaintext
- 🎭 Persona Customization — Automatically generates
AGENTS.md/SOUL.md/USER.md/HEARTBEAT.md - 🎵 Audio System — MiniMax Voice Cloning + CosyVoice + Edge TTS triple fallback, never silent
- 👀 Emotional Expression — 14 emotions + multiple eye micro-expressions + dynamic glow effects
- 🩺 Doctor Self-Check — One-click diagnosis of Gateway / model / TTS / ports / logs / lyrics window
- 🎛️ Model Management — Provider CRUD, model add/delete, latency testing, quick presets
- 🧠 Gateway Sync — Real-time WebSocket synchronization with OpenClaw Agent state, millisecond response
- 💪 7x24 Reliability — Auto-recovery, health score monitoring, Switch Logger
- 🖥️ Lightweight Rendering — Pure HTML/CSS/JS sphere, CSS radial-gradient glass texture, no framework dependency
- 🎤 Voice Broadcast — Automatic conversion of agent replies to speech, supports emotion detection and pause markers
- 🖱️ Desktop Integration — Window pin on top, mouse-through, drag-follow, lyrics-style subtitle window
Tech Stack
- Electron (desktop container)
- OpenClaw Gateway (WebSocket communication)
- MiniMax Speech / CosyVoice / Edge TTS (speech synthesis)
- CSS Animation + requestAnimationFrame (sphere animation)
Installation
git clone https://github.com/kk43994/kkclaw.git
cd kkclaw
npm install
npm start
Or download the installer:
- 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
Configuration
Edit pet-config.json to customize:
- TTS engine and voice
- Sphere color and size
- OpenClaw Gateway connection
- Emotion mapping rules
- Setup Wizard initial guide flow
Directory Structure
kkclaw/
├── main.js # Electron main process
├── index.html # Sphere rendering UI
├── lyrics.html # Lyrics subtitle window
├── setup-wizard.html # Setup Wizard interface
├── setup-wizard.js # Setup Wizard logic
├── gateway-client.js # Gateway communication client
├── smart-voice.js # Voice scheduling system
├── templates/ # Agent template files
├── voice/ # TTS engine modules
├── utils/ # Utility modules
├── scripts/ # Build scripts
└── docs-dev/ # Development documentation
Links
- GitHub: https://github.com/kk43994/kkclaw
- Landing Page: https://kk43994.github.io/kkclaw/
- ClawHub: https://clawhub.ai/kk43994/desktop-pet
- Version: v3.1.2