🦞 ClawGrowth

OpenClaw Agent Growth Metrics Dashboard

中文 • Features • Quick Start • Screenshots • Documentation

---

🎯 What is ClawGrowth?

ClawGrowth is a gamified metrics dashboard designed for OpenClaw agents. It transforms raw agent data into meaningful visualizations, helping you understand how your AI agents work, their growth trajectory, and collaboration relationships.

Think of it as a fitness tracker for your AI agents — monitoring their health, tracking their progress, and celebrating every achievement.

---

✨ Features

📊 Real-time Dashboard

• Live agent status monitoring
• Interactive metric cards with drill-down details
• Responsive dark theme with glass morphism design

🎮 Gamification System

• XP & Levels — Earn experience from conversations, tool usage, and more
• 5 Growth Stages — Seedling → Growing → Mature → Expert → Legend
• 5 Color Tiers — Purple → Blue → Teal → Orange → Red
• Achievements — Unlock milestone achievements as agents progress

📈 Five-Dimension Scoring

Dimension	Weight	Measures
Efficiency	25%	Token efficiency, cache hits, response speed
Output	25%	Token output, tool calls, conversation rounds
Automation	20%	Cron execution volume and success rate
Collaboration	15%	Multi-claw interactions
Accumulation	15%	Skills, memories, learning records

🏥 Four-Status Monitoring

• Energy — Context capacity and freshness
• Health — Cron quality and tool reliability
• Mood — Interaction quality and activity
• Hunger — Learning freshness and depth

📉 Analytics & History

• 7-day growth trend charts
• Tool distribution analysis
• Cron job monitoring
• Workspace completeness metrics

🤝 Collaboration Network

• Visualize claw-to-claw interactions
• Track collaboration patterns
• Monitor shared workspace activity

---

📸 Screenshots

Dashboard Overview	Growth & Progress
Tool Analytics	Agents Overview
Automation & Cron	Workspace

---

🚀 Quick Start

Requirements

Component	Minimum	Recommended	Notes
Python	3.6+	3.9+	Backend runtime
pip	19.0+	Latest	Python package manager
Node.js	-	-	Not required (pure static frontend)
OpenClaw	-	Latest	The claw system being monitored

Step 1: Clone Repository

git clone https://github.com/deepquest-ai/clawgrowth
cd clawgrowth

Step 2: Start Backend (Must Start First)

# Enter backend directory
cd backend

# Install dependencies
pip install -r requirements.txt

# Start backend server
python3 app.py

Success indicator:

INFO:     Uvicorn running on http://0.0.0.0:57178 (Press CTRL+C to quit)

Verify backend:

curl http://localhost:57178/health
# Should return: {"ok":true}

Step 3: Start Frontend (In Another Terminal)

# Enter frontend directory
cd frontend

# Option A: Python built-in server
python3 -m http.server 57177

# Option B: Nginx (recommended for production)
# Configure frontend directory as Nginx root

Success indicator:

Serving HTTP on 0.0.0.0 port 57177 ...

Step 4: Access the Dashboard

• Frontend URL: http://localhost:57177
• API URL: http://localhost:57178
• Default Password: deepquest.cn

---

Startup Order

┌─────────────────────────────────────────────────────────┐
│                    Startup Order                        │
├─────────────────────────────────────────────────────────┤
│                                                         │
│   1. Backend (Must Start First)                         │
│      └── python3 backend/app.py                         │
│          └── Listens on :57178                          │
│          └── Initializes database                       │
│          └── Starts scheduler                           │
│                                                         │
│   2. Frontend (After Backend is Ready)                  │
│      └── python3 -m http.server 57177                   │
│          └── Listens on :57177                          │
│          └── Proxies /api/* to backend                  │
│                                                         │
└─────────────────────────────────────────────────────────┘

⚠️ Important: Frontend depends on backend API. Start backend first!

---

Background Execution (Production)

Using nohup

# Backend in background
cd backend
nohup python3 app.py > logs/app.log 2>&1 &

# Frontend in background
cd frontend
nohup python3 -m http.server 57177 > ../backend/logs/frontend.log 2>&1 &

Using systemd (Recommended)

Create service file /etc/systemd/system/clawgrowth.service:

[Unit]
Description=ClawGrowth Backend
After=network.target

[Service]
Type=simple
User=your_user
WorkingDirectory=/path/to/clawgrowth/backend
ExecStart=/usr/bin/python3 app.py
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable service:

sudo systemctl daemon-reload
sudo systemctl enable clawgrowth
sudo systemctl start clawgrowth

---

Troubleshooting

Q: Frontend shows blank page or errors?

A: Check if backend is running:

curl http://localhost:57178/health

Q: Port already in use?

A: Change ports:

# Backend port
export CLAWGROWTH_PORT=8080
python3 app.py

# Frontend port
python3 -m http.server 8081

Q: No claw data visible?

A: Verify OpenClaw directory is correctly configured:

export CLAWGROWTH_OPENCLAW_ROOT=~/.openclaw
python3 app.py

Q: How to change default password?

A: Login → Settings → Change Password, or delete backend/data/config.json to reset to default password.

---

⚙️ Configuration

ClawGrowth supports two configuration methods, in order of priority:

1. Environment variables - Suitable for Docker, CI/CD scenarios
2. Config file - Suitable for local deployment, more intuitive

Option 1: Config File (Recommended)

Copy the example config file and modify:

cp config.example.json config.json

Edit config.json:

{
  "openclaw_root": "~/.openclaw",
  "db_path": "",
  "host": "0.0.0.0",
  "port": 57178,
  "scheduler_enabled": true,
  "collect_hourly": true,
  "cleanup_hour": 3,
  "tool_retention_days": 7,
  "cron_retention_days": 30
}

⚠️ Important: openclaw_root must point to your OpenClaw installation directory, otherwise claw data cannot be read!

Common configuration examples:

// Linux/macOS default installation
{ "openclaw_root": "~/.openclaw" }

// Custom installation path
{ "openclaw_root": "/opt/openclaw" }

// Windows
{ "openclaw_root": "C:/Users/YourName/.openclaw" }

Option 2: Environment Variables

Variable	Config File Field	Default	Description
CLAWGROWTH_OPENCLAW_ROOT	openclaw_root	~/.openclaw	OpenClaw installation directory
CLAWGROWTH_DB_PATH	db_path	{openclaw_root}/clawgrowth/clawgrowth.db	Database path
CLAWGROWTH_HOST	host	0.0.0.0	API server host
CLAWGROWTH_PORT	port	57178	API server port
CLAWGROWTH_SCHEDULER	scheduler_enabled	true	Enable built-in scheduler
CLAWGROWTH_COLLECT_HOUR	collect_hourly	true	Hourly data collection
CLAWGROWTH_CLEANUP_HOUR	cleanup_hour	3	Daily cleanup hour (0-23)
CLAWGROWTH_TOOL_DAYS	tool_retention_days	7	Tool log retention days
CLAWGROWTH_CRON_DAYS	cron_retention_days	30	Cron log retention days

Frontend Configuration

Frontend is a pure static single-page app. No build required, no Node.js needed.

Default behavior: Uses same-origin API (works automatically when frontend and backend are on the same domain)

Custom API address (for separate frontend/backend deployment):

# Copy and edit config file
cp frontend/config.example.js frontend/config.js

Edit frontend/config.js:

window.CLAWGROWTH_API_BASE = 'http://your-backend-server:57178';

💡 config.js is automatically loaded if it exists. No need to modify index.html

Authentication

Default password: deepquest.cn

Change password:

1. Login → Settings → Change Password
2. Or manually generate hash: echo -n "your_password" | sha256sum

---

📡 API Endpoints

Method	Endpoint	Description
GET	/health	Health check
POST	/api/auth/login	Login
POST	/api/auth/logout	Logout
POST	/api/auth/change-password	Change password
GET	/api/auth/check	Verify token
GET	/api/agents	All agents overview
GET	/api/agent/{id}	Agent details
GET	/api/agent/{id}/history	Historical data
GET	/api/shared	Shared workspace stats
POST	/api/collect-all	Trigger data collection
POST	/api/cleanup	Trigger data cleanup
GET	/api/scheduler/status	Scheduler status

---

📖 Documentation

• Algorithm Rules — Scoring formulas and calculation logic
• Database Design — Schema and data flow
• API Reference — Full API documentation

---

🛠️ Project Structure

ClawGrowth/
├── backend/
│   ├── app.py              # FastAPI application
│   ├── config.py           # Configuration
│   ├── database.py         # SQLite schema
│   ├── service.py          # Business logic
│   ├── calculators/        # Scoring algorithms
│   │   ├── scores.py       # Five-dimension scores
│   │   ├── status.py       # Four-status calculations
│   │   └── xp.py           # XP and level system
│   ├── collectors/         # Data collectors
│   │   ├── session_parser.py
│   │   ├── cron_parser.py
│   │   └── workspace_scanner.py
│   └── data/
│       └── config.json     # Password configuration
├── frontend/
│   ├── index.html          # Single-page application
│   └── config.example.js   # Frontend config example
├── docs/
│   ├── en/                 # English documentation
│   └── zh/                 # Chinese documentation
├── config.example.json     # Backend config example
├── LICENSE
├── CHANGELOG.md
└── README.md

---

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

👤 Author

DeepQuest.cn

• WeChat: deepquestai
• Website: deepquest.cn

---

Made with ❤️ for the OpenClaw community