kk43994/kkclaw

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 邏輯
├── 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