Clawlens - OpenClaw Usage Insights#

Generate a comprehensive usage insights report by analyzing conversation history.

When to Use#

User SaysAction"show me my usage report"Run full report"analyze my conversations"Run full report"how am I using Claw"Run full report"clawlens" / "claw lens"Run full report"usage insights" / "usage analysis"Run full report

How to Run#

Execute the analysis script:

bash

python3 scripts/clawlens.py [OPTIONS]

Options#

FlagDefaultDescription--agent-id``mainAgent ID to analyze--days``180Analysis time window in days--modelauto-detectLLM model in litellm format (e.g. deepseek/deepseek-chat). If omitted, auto-detected from OpenClaw config.--lang``zhReport language: zh or en``--format``mdOutput format: md (Markdown) or html (self-contained dark-themed HTML)--no-cachefalseIgnore cached facet extraction results--max-sessions``2000Maximum sessions to process--concurrency``10Max parallel LLM calls--verbosefalsePrint progress to stderr-o / --outputstdoutOutput file path

Model Selection (Agent Interaction)#

When the user requests a clawlens report without specifying a model, you must ask the user before running:

是否使用 OpenClaw 当前配置的模型来生成报告？如果不使用，请告诉我你想用的模型（litellm 格式，如 deepseek/deepseek-chat）。

• User agrees to use OpenClaw model: Run without --model (the script auto-detects from ~/.openclaw/openclaw.json).
• User specifies a different model: Run with --model <user-choice>. The user must also set the corresponding API key env var (e.g. DEEPSEEK_API_KEY).

Note: Each user's OpenClaw model configuration may differ — some use API-key-based providers (e.g. openai-completions), others use OAuth-based providers (e.g. anthropic-messages). The script handles both transparently.

Examples#

bash

# Auto-detect model from OpenClaw config (simplest)
python3 scripts/clawlens.py --verbose

# Auto-detect, English, last 7 days
python3 scripts/clawlens.py --lang en --days 7

# Manually specify model (DeepSeek)
DEEPSEEK_API_KEY=sk-xxx python3 scripts/clawlens.py --model deepseek/deepseek-chat

# OpenAI, English, last 7 days
OPENAI_API_KEY=sk-xxx python3 scripts/clawlens.py --model openai/gpt-4o --lang en --days 7

# Verbose, save to file
ANTHROPIC_API_KEY=sk-xxx python3 scripts/clawlens.py --model anthropic/claude-sonnet-4-20250514 --verbose -o /tmp/clawlens-report.md

# HTML report (dark-themed, self-contained)
DEEPSEEK_API_KEY=sk-xxx python3 scripts/clawlens.py --model deepseek/deepseek-chat --format html -o /tmp/clawlens-report.html

Output#

The script outputs a report to stdout (or to the file specified by -o). Progress messages go to stderr when --verbose is set.

• Markdown ( --format md, default): Plain Markdown report. Present it directly to the user.
• HTML ( --format html): Self-contained dark-themed HTML file with glassmorphism styling, animated stat cards, CSS bar charts, and interactive navigation. Opens directly in any browser — no external dependencies. Requires the markdown Python package for Markdown-to-HTML conversion.

The report includes all dimensions: usage overview, task classification, friction analysis, skills ecosystem, autonomous behavior audit, and multi-channel analysis.

Present the output directly to the user. Do not summarize or truncate it.

Model Configuration#

--model is optional. If omitted, the model is automatically resolved from OpenClaw configuration:

1. Reads primary model from ~/.openclaw/openclaw.json ( agents.defaults.model.primary, e.g. kimi-code/kimi-for-coding)
2. Looks up the provider's baseUrl and api type (e.g. openai-completions, anthropic-messages)
3. Retrieves API key/token from ~/.openclaw/agents/{agentId}/agent/auth-profiles.json
4. Maps to litellm format automatically (e.g. openai/kimi-for-coding with custom api_base)

If you prefer to specify a model manually, use --model with litellm's provider format:

Provider--model valueRequired env varDeepSeekdeepseek/deepseek-chat``DEEPSEEK_API_KEYOpenAIopenai/gpt-4o``OPENAI_API_KEYAnthropicanthropic/claude-sonnet-4-20250514``ANTHROPIC_API_KEYOpenAI-compatibleopenai/<model-id> + set OPENAI_API_BASE``OPENAI_API_KEY

The format is always <provider>/<model-id>. Refer to litellm docs for the full list of supported providers and their env var naming conventions.

Data Source#

The script reads conversation data from:

• ~/.openclaw/agents/{agentId}/sessions/sessions.json (session index)
• ~/.openclaw/agents/{agentId}/sessions/*.jsonl (per-session logs, including unindexed historical files)
• ~/.openclaw/skills/ (installed skills directory for ecosystem analysis)

Cache is written to ~/.openclaw/agents/{agentId}/sessions/.clawlens-cache/facets/ to avoid re-analyzing the same sessions.

Privacy Notice#

This skill sends conversation transcript data to an external LLM provider (specified by --model) for analysis. Specifically:

• Stage 2 (Facet Extraction): Each session's conversation transcript (truncated to ~80K chars) is sent to the LLM to extract structured analysis (task categories, friction points, etc.). Results are cached locally so each session is only sent once.
• Stage 4 (Report Generation): Aggregated statistics and session summaries (not raw transcripts) are sent to the LLM to generate the report sections.

API key handling: When --model is omitted, this skill reads openclaw.json and auth-profiles.json to auto-detect the model and retrieve the API key. The API key is used only for LLM calls during report generation and is not stored or transmitted elsewhere. When --model is specified explicitly, the user must provide the API key via environment variables — no OpenClaw config files are accessed for credentials.