> ## Documentation Index
> Fetch the complete documentation index at: https://claw-lens.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Claw Lens is a zero-config local dashboard for your OpenClaw AI agents — observability, cost analytics, security audit, and debugging tools in one place.

Run `npx claw-lens-cli` to start the dashboard at `http://localhost:4242`. No account, no API key, no external service — everything runs on your machine. Available in both English and Simplified Chinese.

<img src="https://mintcdn.com/matrix-45c0bb95/mjaGeg6mPl8hfb1t/images/ph_overview_2.png?fit=max&auto=format&n=mjaGeg6mPl8hfb1t&q=85&s=d462a8d670931c69570c8f099cb47e71" alt="Claw Lens Overview Dashboard" style={{ borderRadius: "8px", marginTop: "1rem", marginBottom: "2rem" }} width="720" height="974" data-path="images/ph_overview_2.png" />

***

## You type a prompt. Your agent runs for five minutes. What is it doing?

You see the final output — but not the tool calls, the retries, or the tokens it burned to get there. Right now, running an AI agent feels like flying blind.

***

## Live Monitor

Watch your agents work in real time. See which agent is running, what tool it just called, whether it's stuck in a loop — streamed live over WebSocket, not polled from logs.

Every message, every tool call, every result, as it happens.

<img src="https://mintcdn.com/matrix-45c0bb95/mjaGeg6mPl8hfb1t/images/ph_live.png?fit=max&auto=format&n=mjaGeg6mPl8hfb1t&q=85&s=ad454de94c51b776ef5e4bbc14c0df7b" alt="Live Monitor — real-time agent activity stream" style={{ borderRadius: "8px", marginTop: "0.75rem", marginBottom: "2rem" }} width="1214" height="879" data-path="images/ph_live.png" />

***

## Cost & Token Analytics

Track spend by day, by model, and by agent. See cache hit rates, cost-per-session breakdowns, and token composition across any time range.

When a session costs more than expected, drill into the per-agent breakdown to find out where the tokens went.

<img src="https://mintcdn.com/matrix-45c0bb95/mjaGeg6mPl8hfb1t/images/ph_token_1.png?fit=max&auto=format&n=mjaGeg6mPl8hfb1t&q=85&s=8825520b463c00cbeba64d96935ce87e" alt="Token Usage — cost summary and trend" style={{ borderRadius: "8px", marginTop: "0.75rem", marginBottom: "1rem" }} width="1305" height="813" data-path="images/ph_token_1.png" />

<img src="https://mintcdn.com/matrix-45c0bb95/mjaGeg6mPl8hfb1t/images/ph_token_2.png?fit=max&auto=format&n=mjaGeg6mPl8hfb1t&q=85&s=928f425c8d443f401ef15818f5a197a9" alt="Token Usage — per-agent and per-model breakdown" style={{ borderRadius: "8px", marginTop: "0.75rem", marginBottom: "2rem" }} width="1137" height="699" data-path="images/ph_token_2.png" />

***

## Sessions

Browse every session in one filterable table — model, tokens, cost, cache hit rate, context pressure, burn rate, errors, and activity time at a glance. Filter by agent, time range, or search by session ID.

<img src="https://mintcdn.com/matrix-45c0bb95/mjaGeg6mPl8hfb1t/images/ph_sessions.png?fit=max&auto=format&n=mjaGeg6mPl8hfb1t&q=85&s=235cef2610821758b2c09b9b425fcc1e" alt="Sessions — filterable session table" style={{ borderRadius: "8px", marginTop: "0.75rem", marginBottom: "1rem" }} width="1137" height="833" data-path="images/ph_sessions.png" />

Click into any session to see the full details: cache hit analysis, cost and token charts that grow step by step, context pressure over time, and every user and assistant message with token in/out, cache read/write, cost, and latency. Expand any message to inspect arguments, output, and errors.

<img src="https://mintcdn.com/matrix-45c0bb95/mjaGeg6mPl8hfb1t/images/sessions_details.png?fit=max&auto=format&n=mjaGeg6mPl8hfb1t&q=85&s=0d194c8fe479c048e456c48fd767fea4" alt="Session Details — per-step cost and token breakdown" style={{ borderRadius: "8px", marginTop: "0.75rem", marginBottom: "1rem" }} width="1478" height="907" data-path="images/sessions_details.png" />

<img src="https://mintcdn.com/matrix-45c0bb95/mjaGeg6mPl8hfb1t/images/sessions_msg.png?fit=max&auto=format&n=mjaGeg6mPl8hfb1t&q=85&s=4dd887e1ef9b0f8ede8e32449a3e0a82" alt="Session Messages — message-level token and cost details" style={{ borderRadius: "8px", marginTop: "0.75rem", marginBottom: "2rem" }} width="1496" height="786" data-path="images/sessions_msg.png" />

***

## Session Timeline

A Gantt chart of a single session — every LLM call and tool invocation laid out on a time axis. See exactly where time is spent: is it the model thinking, or a tool running slow? Idle gaps are auto-compressed so you focus on what actually happened.

<img src="https://mintcdn.com/matrix-45c0bb95/mjaGeg6mPl8hfb1t/images/ph_timeline.png?fit=max&auto=format&n=mjaGeg6mPl8hfb1t&q=85&s=4dad451e7e30cc20d091f3d40568b33c" alt="Session Timeline — Gantt-style execution trace" style={{ borderRadius: "8px", marginTop: "0.75rem", marginBottom: "2rem" }} width="947" height="859" data-path="images/ph_timeline.png" />

Click any turn to expand the full detail — input arguments, output, and errors.

<img src="https://mintcdn.com/matrix-45c0bb95/I7e44DvJoCpYRcvw/images/ph_timeline_error.png?fit=max&auto=format&n=I7e44DvJoCpYRcvw&q=85&s=595452bec04dd1b59202a488deaa32a5" alt="Session Timeline — Gantt-style execution trace" style={{ borderRadius: "8px", marginTop: "0.75rem", marginBottom: "2rem" }} width="1196" height="386" data-path="images/ph_timeline_error.png" />

***

## Agents

See all your agents at a glance — who's running, who's idle, who's healthy. Each agent card shows health status, current task, model, cost, error rate, cache hit rate, and context pressure.

<img src="https://mintcdn.com/matrix-45c0bb95/mjaGeg6mPl8hfb1t/images/ph_agent_1.png?fit=max&auto=format&n=mjaGeg6mPl8hfb1t&q=85&s=ebd919a81f1d29ba3ad2b56e9772bed4" alt="Agents — health, status, and activity overview" style={{ borderRadius: "8px", marginTop: "0.75rem", marginBottom: "2rem" }} width="1072" height="679" data-path="images/ph_agent_1.png" />

Expand any agent to see token usage trends, a 7-day activity heatmap, session frequency, and error history.

<img src="https://mintcdn.com/matrix-45c0bb95/mjaGeg6mPl8hfb1t/images/ph_agent_2.png?fit=max&auto=format&n=mjaGeg6mPl8hfb1t&q=85&s=498168e8fefbf8b852422def7457c5f1" alt="Agents — expanded detail with trends and heatmap" style={{ borderRadius: "8px", marginTop: "0.75rem", marginBottom: "2rem" }} width="1127" height="450" data-path="images/ph_agent_2.png" />

***

## Security Audit

Automatic scanning across every session for credential leaks, prompt injection attempts, dangerous shell commands, and data exfiltration patterns. Each event is risk-scored so you can filter by severity.

Includes a per-agent security profile — tool footprint, directory access, network domains, and a trust status.

<img src="https://mintcdn.com/matrix-45c0bb95/mjaGeg6mPl8hfb1t/images/ph_audit.png?fit=max&auto=format&n=mjaGeg6mPl8hfb1t&q=85&s=fb1d91d4a7f0933d38d00d3a41ab137f" alt="Security Audit — risk-scored event timeline" style={{ borderRadius: "8px", marginTop: "0.75rem", marginBottom: "2rem" }} width="1245" height="767" data-path="images/ph_audit.png" />

***

## Context Breakdown

Visualize how system prompt, conversation history, and tool results fill up the context window at every API call. See exactly when and where context pressure spikes.

<img src="https://mintcdn.com/matrix-45c0bb95/mjaGeg6mPl8hfb1t/images/ph_context_breakdown.png?fit=max&auto=format&n=mjaGeg6mPl8hfb1t&q=85&s=2107f344e1bc5754aa93ba9f1d2cef4f" alt="Context Breakdown — context window composition per step" style={{ borderRadius: "8px", marginTop: "0.75rem", marginBottom: "2rem" }} width="947" height="720" data-path="images/ph_context_breakdown.png" />

***

## And more

<CardGroup cols={2}>
  <Card title="Cron Jobs" icon="clock" href="/monitoring/cron">
    Auto-detect scheduled agent runs with full run history — status, duration, and success/failure logs.
  </Card>

  <Card title="Tool Profiler" icon="gauge" href="/debugging/profiler">
    Latency distribution, failure rates, and slow call identification for every tool your agents use.
  </Card>

  <Card title="Deep Turns" icon="layer-group" href="/debugging/deep-turns">
    Detect turns with abnormally deep tool-call sequences — the first sign an agent is looping or struggling.
  </Card>

  <Card title="Cache Trace" icon="diagram-project" href="/debugging/cache-trace">
    Pipeline flow visualization and diff between consecutive LLM calls to debug prompt cache misses.
  </Card>

  <Card title="i18n" icon="language" href="https://github.com/msfirebird/claw-lens/blob/main/README.zh.md">
    Full dashboard available in English and Simplified Chinese. Switch anytime from the sidebar.
  </Card>

  <Card title="Adopt a Claw" icon="shrimp">
    A little easter egg — find the mascot hiding in settings and adopt it. It comes with different moods.
  </Card>
</CardGroup>

***

## Get started in 30 seconds

<Steps>
  <Step title="Run one command">
    ```bash theme={null}
    npx claw-lens-cli
    ```

    The dashboard opens at `http://localhost:4242`. No config, no signup.
  </Step>

  <Step title="That's it">
    Claw Lens auto-detects your OpenClaw home directory and reads agent logs locally. All data stays on your machine.
  </Step>
</Steps>

<Note>
  Requires Node.js 18+. Your OpenClaw agent must have run at least one session to produce log data.
</Note>

***

<CardGroup cols={2}>
  <Card title="Quick Start" icon="bolt" href="/quickstart">
    Detailed setup guide and configuration options.
  </Card>

  <Card title="Full Documentation" icon="book" href="/monitoring/overview">
    Explore every feature in depth.
  </Card>
</CardGroup>
