| name | clawface |
| description | Floating avatar widget for AI agents showing emotions, actions, and visual effects. Give your OpenClaw a face! Use when the user wants visual feedback, a floating status window, or to see agent emotions while it works. Triggers on "show avatar", "uruchom avatara", "pokaż avatara", "agent face", "visual feedback". |
🤖 ClawFace
Give your OpenClaw a face!
Got a dedicated machine running OpenClaw with a monitor? Tired of staring at logs all day?
Give your agent a personality!
- 9 emotions — from happy to angry, thinking to proud
- 9 actions — coding, searching, reading, speaking...
- 15 visual effects — matrix rain, fire, confetti, radar scan...
That's 1,215 unique combinations + custom messages from your agent!
Perfect for:
- 💻 Laptop setups where you want to SEE your agent working
- 🖥️ Dedicated OpenClaw machines with a monitor
- 🎮 Making your AI assistant feel alive
- 📺 Impressing your friends/coworkers
⚠️ Note: Only tested on macOS. Should work on Windows/Linux but YMMV.
🚀 Quick Test (try it now!)
python3 -c "import tkinter; print('Ready!')"
Terminal 1 — Run ClawFace:
python3 SKILL_PATH/scripts/avatar.py --mode robot
Terminal 2 — Run Demo:
python3 SKILL_PATH/scripts/avatar.py --demo
Watch the avatar cycle through all emotions, actions, and effects automatically! 🎉
Manual control:
echo '{"emotion":"excited","action":"success","effect":"confetti","message":"It works!"}' > ~/.clawface/avatar_state.json
⚠️ Requirements
Python 3.10+ with tkinter:
python3 -c "import tkinter; print('OK')"
📦 Full Installation
1. Install the auto-thinking hook (recommended):
cp -r SKILL_PATH/hooks/clawface-thinking ~/.openclaw/hooks/
openclaw hooks enable clawface-thinking
This makes the avatar show "thinking" automatically when a turn starts — no delay!
2. Launch the avatar:
nohup python3 SKILL_PATH/scripts/avatar.py --mode robot > /dev/null 2>&1 &
Note: Replace SKILL_PATH with actual path, e.g., /usr/local/lib/node_modules/openclaw/skills/clawface
🎯 Core Principle: BE DYNAMIC!
Don't set one state and forget it. Update the avatar continuously as you work:
User asks question
→ thinking/reading (reading their message)
→ thinking/thinking (analyzing)
→ happy/speaking (formulating response)
→ neutral/idle (sent, waiting)
Every action you take should be reflected. The avatar is your LIVE status indicator.
🎭 State Reference
Emotions
| Emotion | Use when... |
|---|
neutral | Default, waiting |
thinking | Processing, analyzing |
happy | Things going well |
excited | Big win, celebration |
proud | Personal achievement |
confused | Uncertain, unexpected |
tired | Long task |
sad | Failed despite trying |
angry | Error, frustration |
Actions
| Action | Use when... |
|---|
idle | Waiting for user |
reading | Reading files/docs |
thinking | Analyzing, planning |
searching | Web search, grep |
coding | Writing code |
loading | Running commands |
speaking | Sending response |
success | Completed task |
error | Something failed |
Effects
| Effect | Vibe |
|---|
none | Clean, minimal |
matrix | Techy, data flow |
radar | Scanning, searching |
brainwave | Deep thinking |
typing | Writing |
soundwave | Speaking |
gear | Mechanical work |
fire | Intense, productive |
lightning | Fast, powerful |
confetti | Celebration! |
heart | Affection |
glitch | Error, broken |
sparkles | Magic |
pulse | Active but calm |
progressbar:XX | Progress (0-100) |
⚡ Best Practices
🔴 MINIMUM FLOW FOR EVERY RESPONSE:
thinking → processing user input
speaking → sending your reply
idle → done, waiting
This is mandatory. Every single reply should show this progression.
Tips:
- Update BEFORE each action — set
reading before you read
- Update AFTER completion — show
success/error, then idle
- Match intensity — small task = subtle, big task = expressive
- Always return to idle — when waiting for user
🔧 Technical Reference
State File
Write JSON to ~/.clawface/avatar_state.json:
{
"emotion": "happy",
"action": "coding",
"effect": "fire",
"message": "Building something awesome!"
}
Display Modes
🤖 Robot Mode (--mode robot) — default
- LED-style pixel eyes with animations
- Mechanical arms with claws
- Retro-futuristic cyberpunk vibe
- Best for: tech aesthetic, dedicated screens
😊 Face Mode (--mode face)
- Simplified cartoon face
- Expressive eyes and mouth
- Friendly, approachable look
- Best for: casual use, smaller windows
Switch modes with buttons in the UI or restart with different --mode.
Window Controls
- Drag to move
- Drag edges to resize
F for fullscreenQ to quit
