ClawHub Download Tracker

Overview#

A CLI tool that fetches official download counts for skills published on ClawHub, stores history in local CSV, and pushes snapshots/reports via Feishu.

Use when: User wants to monitor their ClawHub skill downloads, set up automated tracking, or generate trend reports.

Do NOT use for: Real-time analytics (this is periodic snapshots, not streaming), other registries (only ClawHub), individual user analytics (skill-level only).

Quick Commands#

bash

# Snapshot (collect + Feishu push)
python3 ~/.openclaw/workspace/skills/clawhub-download-tracker/clawhub_tracker.py

# Reports
python3 .../clawhub_tracker.py report daily
python3 .../clawhub_tracker.py report weekly
python3 .../clawhub_tracker.py report monthly

# Manage monitor list
python3 .../clawhub_tracker.py add <slug> [note]
python3 .../clawhub_tracker.py remove <slug>
python3 .../clawhub_tracker.py list

Workflow#

Snapshot collection#

text

1. Load skills.csv (managed by add/remove)
2. For each slug: clawhub inspect <slug> --json → extract stats.downloads
3. Compare to last_state.json
4. If delta ≠ 0 → append to checklog.csv + update last_state
5. Build summary text
6. Archive to reports/YYYY-MM.md
7. Push to Feishu (if configured)

Report generation#

text

1. Read checklog.csv (only delta ≠ 0 records)
2. Filter by date range (last 1d / 7d / month-to-date)
3. Build report with: per-skill start→end, cumulative delta, peak time, total
4. Print + archive + Feishu push

Add/remove skills#

text

add <slug>     → append to skills.csv (auto-create with header if missing)
remove <slug>  → remove from skills.csv (historical checklog preserved)
list           → show monitor list with last known download counts

Prerequisites#

• clawhub CLI installed (auto-detected via shutil.which with fallback to /opt/homebrew/bin/clawhub)

• Python 3 (built-in on macOS)

• Feishu credentials (only needed for push notifications):

  • CLAWHUB_FEISHU_APP_ID
  • CLAWHUB_FEISHU_APP_SECRET
  • CLAWHUB_FEISHU_USER_OPEN_ID

Configure via env vars or ~/.openclaw/workspace/data/clawhub-tracker/.env

Storage Strategy#

• checklog.csv — only records with delta ≠ 0 (sparse, keeps file small)
• last_state.json — latest snapshot per slug (avoids re-scanning checklog on each run)
• reports/YYYY-MM.md — monthly archive of all outputs
• tracker.log — run history with errors
• File locking via fcntl.flock — safe under concurrent launchd triggers

Data Files#

text

~/.openclaw/workspace/data/clawhub-tracker/
├── skills.csv         # slug,note
├── checklog.csv       # timestamp,slug,downloads,delta
├── last_state.json    # {slug: {downloads, ts}}
├── reports/           # YYYY-MM.md archives
├── tracker.log        # Run logs
└── .tracker.lock      # File lock (transient)

Data Source#

Fetches official stats.downloads via clawhub inspect <slug> --json. Direct from ClawHub registry — no third-party APIs.

Edge Cases#

ScenarioBehaviorSlug not found in ClawHubMark as fetch failed, skipInvalid slug formatReject (regex validation, prevents injection)Missing .envSkip Feishu push, continue with local filesEmpty skills.csvSend "no skills to monitor" notice to Feishu, exitConcurrent runsSecond instance detects lock, exits gracefullychecklog missing (e.g. migration)Fall back to last_state.json for delta

See Also#

• README.md — full user-facing docs (installation, launchd setup, security)
• README.zh.md — Chinese version
• test_clawhub_tracker.py — test suite