Skip to main content
Claw Lens is designed to run entirely on your machine. No data leaves your computer — not to the Claw Lens project, not to any analytics service, not to any third party.

​
What data Claw Lens reads

Claw Lens reads the session files that OpenClaw writes when your agents run. These files are stored in your OpenClaw home directory (by default ~/.openclaw) and follow the path pattern: 
~/.openclaw/agents/<agent-name>/sessions/<session-id>.jsonl
Each .jsonl file contains the message and tool-call history for a single agent session. Claw Lens parses these files to populate its dashboard views.

​
Where Claw Lens stores data

All parsed data is stored in a local SQLite database on your machine. The database file is created at: 
~/.openclaw/claw-lens.db
If you have set the OPENCLAW_HOME environment variable, the database lives at: 
$OPENCLAW_HOME/claw-lens.db
The database holds all session data, tool call history, and security audit findings. It is a standard SQLite file — you can inspect it with any SQLite client if needed.
The security audit data (flagged findings, risk scores, agent baselines) is stored in the same database file, not in a separate location.

​
Network access

The dashboard server binds exclusively to 127.0.0.1. It is never reachable from another machine on your network — even if you configure a custom port or open it in your firewall. Claw Lens makes no outbound network calls of its own. There is no telemetry, no analytics, no crash reporting, and no update pings sent anywhere.

​
Clearing all stored data

To wipe everything Claw Lens has stored, delete the database file: 
rm ~/.openclaw/claw-lens.db
If you set OPENCLAW_HOME: 
rm "$OPENCLAW_HOME/claw-lens.db"
The next time you start claw-lens, it creates a fresh database and re-reads your agent session files from scratch.
Deleting the database also removes all security audit findings, dismissed false positives, and computed risk scores. This cannot be undone.

​
Refreshing agent data

If you want to reload agent data without deleting the database, use the Refresh Data button on the Settings page. This forces Claw Lens to re-read all session files and update its stored data. You can also trigger a refresh via the API: 
curl -X POST http://localhost:4242/api/refresh
Claw Lens tracks each file by its modification time and size. On a normal startup it only processes files that have changed since the last run. A forced refresh re-reads every file regardless.

​
Data retention

Claw Lens can only show data that still exists on disk. OpenClaw manages the lifecycle of session files — when OpenClaw deletes a file, that data disappears from Claw Lens on the next refresh. Understanding these retention settings helps you control how much history is available in the dashboard.

​
Session file lifecycle

Session files are not deleted immediately. Instead, OpenClaw renames them with a suffix before eventually removing them:
  • .deleted — when a session is archived, the file is renamed from .jsonl to .jsonl.deleted.<timestamp>
  • .reset — when context is compacted mid-session, the old transcript is renamed to .jsonl.reset.<timestamp> and a fresh .jsonl is created
Both suffixed files still count toward token usage in Claw Lens. They are only physically deleted when the retention period expires.

​
Session retention

By default, OpenClaw removes archived session files after 30 days. You can change this in ~/.openclaw/openclaw.json: 
{
  "session": {
    "maintenance": {
      "pruneAfter": "90d",
      "resetArchiveRetention": "90d"
    }
  }
}
​
pruneAfter
string
How long .deleted files are kept before being physically removed. Default: "30d".
​
resetArchiveRetention
string
How long .reset files are kept. Defaults to the value of pruneAfter if not set.
Accepted values: "30d", "720h", or false (never prune).
Restart the OpenClaw gateway after changing retention settings.

​
Cron session retention

Cron run metadata is stored separately from session transcripts:
FilePathRetention
Run log (metadata)~/.openclaw/cron/runs/<jobId>.jsonlKept permanently
Session transcript~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonlPruned after retention period
By default, OpenClaw prunes cron session transcripts after 24 hours. Once the session file is deleted, the run record still appears in the Cron page, but the “See in Sessions” link disappears. To extend the retention window, add this to ~/.openclaw/openclaw.json: 
{
  "cron": {
    "sessionRetention": "48h"
  }
}
Accepted values: "24h", "7d", or false (never prune).
Restart the OpenClaw gateway after changing retention settings.

​
Cache trace retention

The cache trace file powers the Context Breakdown and Cache Trace pages. It is not enabled by default. Two ways to enable it: Option 1 — add to ~/.openclaw/openclaw.json: 
{
  "diagnostics": {
    "cacheTrace": {
      "enabled": true,
      "includeMessages": true,
      "includePrompt": true,
      "includeSystem": true
    }
  }
}
Option 2 — send the keyword OPENCLAW_CACHE_TRACE to OpenClaw and let it enable the setting for you.
The cache trace file grows quickly. Set up a cron job to clean it periodically, or it will consume significant disk space over time.

​
Summary

WhatWhere
Agent session files~/.openclaw/agents/*/sessions/*.jsonl (written by OpenClaw, read by Claw Lens)
Cron run logs~/.openclaw/cron/runs/<jobId>.jsonl (metadata, kept permanently)
Cache trace file~/.openclaw/ (requires manual cleanup)
Claw Lens database~/.openclaw/claw-lens.db
External data sentNone
TelemetryNone