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:

CODEBLOCK0

This script will automatically:

1. 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):

CODEBLOCK1

From Source

For development or if you want to build from source:

CODEBLOCK2

CLI Usage

CODEBLOCK3

Options

Option	Default	Description
INLINECODE0	INLINECODE1	Number of days to analyze
INLINECODE2

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
INLINECODE15	Excessive output relative to input
INLINECODE16

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

CODEBLOCK4

JSON Output Structure

When using --format json, the report contains:

CODEBLOCK5

Common Scenarios

User Request	Command
Show my stats	INLINECODE22
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

CODEBLOCK6