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:

1. Detect your operating system and architecture
2. Download the appropriate binary release
3. Verify the integrity of the downloaded file
4. Install it in a suitable location ($HOME/.local/bin by default)
5. 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