🤖 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!)

# 1. Check if you have Python + tkinter:
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:

# Check:
python3 -c "import tkinter; print('OK')"

# Install if missing:
# macOS:   brew install python-tk@3.14
# Ubuntu:  sudo apt install python3-tk
# Windows: reinstall Python, check "tcl/tk and IDLE" during install

---

📦 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:

1. Update BEFORE each action — set reading before you read
2. Update AFTER completion — show success/error, then idle
3. Match intensity — small task = subtle, big task = expressive
4. 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 fullscreen
• Q to quit