dvcrn OpenClaw Insight — Usage Guide
CLI tool that analyzes local OpenClaw session history and generates interactive reports with usage statistics, behavior patterns, friction analysis, and improvement suggestions. 100% local — no data leaves your machine.
Installation
One-Click Install (Recommended)
Use the official one-click installation script:
curl -fsSL https://raw.githubusercontent.com/linsheng9731/openclaw-insight/main/install.sh | bash
This script will automatically:
- Detect your operating system and architecture
- Download the appropriate binary release
- Verify the integrity of the downloaded file
- Install it in a suitable location ($HOME/.local/bin by default)
- Make the command available in your PATH
Install Specific Version
To install a specific version (e.g., v1.0.0):
curl -fsSL https://raw.githubusercontent.com/linsheng9731/openclaw-insight/main/install.sh | bash -s -- --version v1.0.0
From Source
For development or if you want to build from source:
git clone https://github.com/linsheng9731/openclaw-insight.git
cd openclaw-insight
npm install && npm run build
CLI Usage
# Default: analyze last 30 days, open HTML report in browser
openclaw-insight
# Analyze last 7 days
openclaw-insight --days 7
# JSON output
openclaw-insight --format json --output report.json
# Specific agent + custom output
openclaw-insight --agent my-agent --output ~/Desktop/insight.html
# Verbose, no auto-open
openclaw-insight --verbose --no-open
Options
| Option | Default | Description |
|---|---|---|
-d, --days <n> |
30 |
Number of days to analyze |
-m, --max-sessions <n> |
200 |
Maximum sessions to process |
-a, --agent <id> |
auto-detect | Agent ID to analyze |
-s, --state-dir <path> |
~/.openclaw |
OpenClaw state directory |
-o, --output <path> |
~/.openclaw/usage-data/report.html |
Output file path |
-f, --format <fmt> |
html |
Output format: html or json |
--no-open |
— | Don not auto-open the report in browser |
-v, --verbose |
— | Enable verbose output |
What the Report Includes
Usage Statistics
- Sessions: total count, daily average, activity streaks
- Tokens: input/output breakdown, cache hit rates, cost estimation
- Temporal: daily activity charts, peak hours identification
- Channels: per-channel session counts and token efficiency
- Models: model diversity, per-model cache performance
Behavior Patterns
Automatically detects: peak hours, channel preferences, session duration profiles, cache utilization efficiency, model diversity, and tool usage preferences. Each pattern has an impact level (high / medium / low).
Friction Events
Identifies pain points in your sessions:
| Type | Description |
|---|---|
high_token_waste |
Excessive output relative to input |
excessive_compactions |
Repeatedly hitting context window limits |
abandoned_session |
Started but barely used sessions |
underutilized_cache |
Large sessions with zero cache hits |
context_overflow |
Repeated context window exhaustion |
single_message_sessions |
One-shot interactions with high overhead |
Improvement Suggestions
Prioritized recommendations across these categories:
- Token Efficiency — cache optimization, verbosity control, batching
- Channel Optimization — multi-channel access, per-channel efficiency
- Model Selection — routing simple tasks to cheaper models
- Context Management — conversation splitting, token budgets
- Scheduling — usage pattern optimization
- Memory Utilization — cross-session context retention
- Feature Discovery — underused OpenClaw capabilities
- Workflow Improvement — conversation depth, specification clarity
Each suggestion includes impact, effort, detailed explanation, and optional config snippets.
Data Sources
The tool reads from OpenClaw local state directory (read-only, never modifies data):
~/.openclaw/
agents/{agentId}/
sessions/
sessions.json # Session metadata index
{sessionId}.jsonl # Per-session conversation transcripts
JSON Output Structure
When using --format json, the report contains:
InsightReport {
generatedAt, periodStart, periodEnd, daysAnalyzed,
summary — aggregate stats (sessions, tokens, cost, streaks, etc.)
dailyActivity — per-day breakdown
hourlyDistribution — 24-hour activity heatmap
channelStats — per-channel metrics
modelStats — per-model metrics
sessionAnalyses — detailed per-session data
patterns — detected behavior patterns
frictions — friction events
suggestions — improvement recommendations
}
Common Scenarios
| User Request | Command |
|---|---|
| Show my stats | openclaw-insight |
| How much am I spending? | openclaw-insight --format json then read summary.estimatedCostUsd |
| Why are my sessions slow? | Run analysis then focus on friction events |
| Compare my channels | Run analysis then present channelStats |
| Report for last week | openclaw-insight --days 7 |
| How can I use OpenClaw better? | Run analysis then present top suggestions |
Troubleshooting
| Problem | Fix |
|---|---|
| No agents found | Verify ~/.openclaw exists and contains agent data |
| No sessions in last N days | Increase --days value |
| Empty channel/model stats | OpenClaw version may be too old |
| Build errors | Upgrade to Node.js >= 22 |
Development
npm install # Install dependencies
npm run build # Build
npm run dev # Development mode
npm test # Run tests
npm run clean # Clean build artifacts