What is Claw Sama? / 这是什么？

Claw Sama is an AI companion who lives on your desktop as a 3D VRM avatar — built as an OpenClaw plugin. She speaks with voice, shows emotions in real time, watches your screen to understand what you're up to, and responds when you touch her. She isn't something you open when you need help. She's just there — present, alive, and keeping you company.

Claw Sama 是一个以 3D VRM 形象常驻桌面的 AI 伙伴，基于 OpenClaw 插件运行。她用语音说话，实时流露情绪，观察你的屏幕感知你在做什么，你触摸她时也会有反应。她不是你需要帮助时才打开的工具，而是就在那里——陪着你。

Features / 特性

🎭 Live VRM Avatar / 活灵活现的虚拟形象

• 3D VRM model with real-time facial expressions — happy, sad, angry, surprised, think, curious...
• Lip-sync perfectly matched to voice output
• Idle animations & random fidgets — she's alive even when you're not talking
• Eyes follow your mouse cursor or camera
• 5 built-in VRM models + import your own custom models
• 3D VRM 模型，实时面部表情切换
• 口型与语音完美同步
• 待机动画和随机小动作——不说话的时候她也是活的
• 视线跟踪鼠标或摄像头
• 5 款内置 VRM 模型 + 支持导入自定义模型

🧠 AI Conversation & Voice / AI 对话与语音

• Chat via text or voice, she replies with voice — not just text
• Voice call mode with redesigned UI — smooth, immersive voice conversations
• LLM-powered personality — she has her own character, not just a chatbot
• Configurable persona via SOUL.md & IDENTITY.md — define her personality, speech style, backstory
• One-click persona generation — take a screenshot of the VRM model, AI creates a matching bilingual character profile
• Session memo — key events like touch and dance are quietly noted, so she remembers the context of your time together
• Edge TTS (free, Chinese/English/Japanese) or Qwen TTS (20+ expressive voices)
• Full UI i18n — switch between Chinese and English in settings
• 文字或语音聊天，她会用语音回复——不只是文字
• 语音通话模式，全新 UI 设计——流畅沉浸的语音对话体验
• LLM 驱动的独立人格——不只是聊天机器人，她有自己的性格
• 通过 SOUL.md 和 IDENTITY.md 自定义人设——定义性格、说话风格、背景故事
• 一键生成人设——截取模型截图，AI 自动生成双语匹配角色设定
• 会话备忘录——触摸、舞蹈等关键时刻会被悄悄记下，让她始终记得你们相处的点滴
• Edge TTS（免费，中/英/日语音）或通义千问 TTS（20+ 种表现力丰富的语音）
• 全 UI 国际化——在设置中切换中文 / 英文

💗 Mood System / 情绪系统

• Live mood indicator — a canvas-based liquid heart + bar shows her current emotional state in real time
• 5-tier color system: pink (euphoric) → orange (happy) → green (calm) → blue (neutral) → grey (low)
• Mood shifts from conversation, touch reactions, and dancing — floats up/down with ❤️ delta bubbles
• Mood influences how she talks and behaves
• 实时情绪指示器——液态心形 + 液柱以动画方式呈现当前情绪状态
• 五级色彩系统：粉红（开心）→ 橙（愉快）→ 绿（平静）→ 蓝（正常）→ 灰（低落）
• 情绪受对话、触摸和舞蹈影响动态变化，并以 ❤️ 气泡飘动显示增减值
• 情绪实时影响她的说话方式和行为

👀 Companion Interaction / 陪伴式交互

• She watches your screen and understands what you're doing — then talks to you about it
• Playing Slay the Spire? She helps you plan your deck and warns you about elite fights
• Debugging a React component? She notices you've been stuck for a while and suggests taking a break
• Watching a movie on Bilibili? She comments on the plot twist she just saw
• Reading documentation? She quietly cheers you on: "You got this!"
• Click to touch her — reactions vary by body part: pat her head and she's happy or shy; touch her chest, belly, or bottom and she gets angry; poke her arm and she's surprised or playful; tap her leg and she's a little awkward — each touch plays a matching animation and she may speak
• 通过屏幕观察感知你正在做的事，像真正的伙伴一样自然地融入你的日常
• 在打杀戮尖塔？ 她会帮你分析卡组搭配，提醒你小心精英怪
• 调试 React 组件？ 她发现你卡了好一会儿，建议你起来活动活动
• 在 B 站看电影？ 她会吐槽刚才的剧情反转
• 在看技术文档？ 她默默给你打气："加油，你可以的！"
• 点击触摸她——不同部位有不同反应：摸头会开心或害羞，摸胸/肚子/臀部会生气，戳手臂会惊喜或调皮，碰腿会有点尴尬——每次触摸都有匹配的动画，她可能还会开口说话

💃 Dance System / 舞蹈系统

• VMD dance playback with BGM — pick a preset and watch her dance
• Expanded FBX action pool — richer idle animations and emotional reactions
• Full-body IK (Inverse Kinematics) — natural motion retargeting from VMD/FBX to VRM
• VMD 舞蹈播放配合 BGM——选择预设即可观赏舞蹈
• 扩展的 FBX 动作库——更丰富的待机动画和情绪反应
• 全身 IK（逆运动学）——从 VMD/FBX 到 VRM 的自然动作重定向

🖥️ Desktop Integration / 桌面集成

• Always-on-top transparent window — she floats above everything
• Click-through — doesn't block your work, only responds when you interact
• Drag to move, rotate camera, zoom in/out
• Pin/unpin, hide/show, collapse menu
• macOS & Windows native support via Tauri
• 置顶透明窗口——始终浮在最上层
• 点击穿透——不影响工作，只在你交互时才响应
• 拖拽移动、旋转视角、缩放
• 置顶/取消置顶、显示/隐藏、折叠菜单
• 通过 Tauri 原生支持 macOS 和 Windows

Install / 安装

As OpenClaw Plugin (recommended) / 作为 OpenClaw 插件安装（推荐）

openclaw plugins install @luckybugqqq/claw-sama

The npm package includes pre-built binaries for Windows (.exe) and macOS (.app). OpenClaw loads the plugin and launches the desktop pet automatically.

npm 包内含 Windows (.exe) 和 macOS (.app) 预编译文件。OpenClaw 加载插件后自动启动桌面宠物。

Update / 更新插件

npm cache clean --force
openclaw plugins update @luckybugqqq/claw-sama

Build from Source / 从源码构建

git clone https://github.com/luckybugqqq/claw-sama.git
cd claw-sama/app
npm install
npx tauri build

Requires Node.js 20+ and Rust toolchain. / 需要 Node.js 20+ 和 Rust 工具链。

Settings / 设置

Open settings via the gear icon on the avatar window: / 点击角色窗口上的齿轮图标打开设置：

| Tab / 标签 | Options / 选项 | |---|---| | General / 常规 | Hide UI, subtitles, TTS, volume, gaze tracking, UI position, screen observation, hide mood bar, language / 隐藏UI、字幕、语音、音量、视线跟踪、UI位置、屏幕观察、隐藏情绪条、语言 | | Voice / 语音 | TTS provider (Edge/Qwen), voice selection with preview / TTS 服务商、语音选择与试听 | | Model / 形象 | Built-in VRM models, import custom .vrm / 内置VRM模型、导入自定义模型 | | Persona / 人设 | Edit IDENTITY.md & SOUL.md, one-click AI generation (bilingual) / 编辑人设文件、一键AI生成（双语）| | Dance / 舞蹈 | Dance presets with BGM, VMD playback / 舞蹈预设与BGM、VMD播放 |

Architecture / 架构

claw-sama/
├── index.ts              # OpenClaw plugin backend / 插件后端
├── app/
│   ├── src/              # React + Three.js frontend / 前端
│   │   ├── components/   # VRMScene, TextBubble, ChatInput, SettingsPanel
│   │   ├── emote.ts      # Emotion controller / 表情控制器
│   │   ├── lip-sync.ts   # Audio-driven lip sync / 口型同步
│   │   ├── motion-controller.ts  # Dance & action orchestration / 舞蹈与动作编排
│   │   ├── vmd-loader.ts # VMD dance file parser / VMD 舞蹈文件解析
│   │   └── vrm-ik-handler.ts    # Full-body IK retargeting / 全身IK重定向
│   ├── public/           # VRM models, animations & BGM / 模型、动画和BGM
│   └── src-tauri/        # Tauri desktop shell / 桌面外壳
└── package.json

Tech Stack / 技术栈

• Frontend / 前端: React, Three.js, @pixiv/three-vrm
• Desktop / 桌面: Tauri
• Backend / 后端: OpenClaw plugin SDK (Node.js)
• AI: LLM via OpenClaw runtime (supports multiple providers / 支持多种模型)
• TTS / 语音合成: Edge TTS / Qwen TTS

Acknowledgments / 致谢

• Inspired by AIRI — an AI companion project by moeru-ai
• Inspired by Lobe Vidol — virtual idol interaction by LobeHub

License / 许可

MIT