ClawMetry Documentation

Complete guide to installing, configuring, and using ClawMetry, the real-time observability dashboard for AI agents.

Installation

The fastest way is the one-line installer. It detects your OS, installs ClawMetry, and starts it. These are the same options as the Quick Start on the homepage.

One command (recommended)

curl -fsSL https://clawmetry.com/install.sh | bash

Works on macOS, Linux, and Windows (WSL). Opens at http://localhost:8900 and auto-detects your OpenClaw workspace.

Ask your agent

Already running an OpenClaw agent? Just ask it (run in a long-running PTY, the setup is interactive):

Help me install in a long running PTY
pip install clawmetry && clawmetry setup && setup clawmetry sync via supervisord

pip

pip install clawmetry
clawmetry onboard

Windows PowerShell

iwr -useb https://clawmetry.com/install.ps1 | iex

Windows CMD

curl -fsSL https://clawmetry.com/install.cmd -o install.cmd && install.cmd && del install.cmd

macOS companion app (beta)

Prefer a native menubar app? Download for macOS (macOS 14+, Apple Silicon or Intel). Runs alongside the CLI.

Requirements

• Python 3.8 or higher
• Flask (installed automatically via pip)
• An OpenClaw workspace (ClawMetry auto-detects it)

Track any SDK agent

ClawMetry auto-detects on-disk runtimes (OpenClaw, Claude Code, Codex, Cursor, Aider, Goose, and more). But your own production agent — built on the OpenAI Agents SDK, LangChain, the Vercel AI SDK, LlamaIndex, E2B, or a plain httpx loop — doesn't write sessions to disk. Two lines capture its LLM calls (cost, tokens, latency, errors) and attribute them to a named product:

import clawmetry.track                          # activate the interceptor
clawmetry.track.set_source("support-agent")    # name this product

Each named source shows up as its own first-class line in the dashboard's 🔌 Out-loop sources card — calls, providers, latency, and error rate per agent. You can set it from the environment instead:

CLAWMETRY_SOURCE=billing-agent python my_agent.py

It feeds the same DuckDB → cloud snapshot pipeline as the on-disk runtimes, so out-loop sources sync to the cloud dashboard end-to-end encrypted, the same as everything else.

Features

🌊 Live Flow Visualization

The signature feature. An animated SVG architecture diagram that lights up in real-time as your agent processes messages. Color-coded by type:

• 🟣 Purple — your message entering through a channel
• 🔵 Blue — request flowing to the brain (LLM)
• 🟡 Yellow — tool calls (exec, browser, search, cron, TTS, memory)
• 🟢 Green — response flowing back to you
• 🔴 Red — errors

📊 Token & Cost Tracking

Track token usage and costs per session, per model, and per tool. Bar charts show daily, weekly, and monthly totals. With OpenTelemetry enabled, get real token counts and actual costs instead of estimates.

🤖 Sub-Agent Monitoring

When your agent spawns sub-agents, ClawMetry shows you every step: files being read, commands being run, tools being called, and what the sub-agent is thinking. Available as summary, narrative, or full logs.

⏰ Cron Job Dashboard

Monitor scheduled jobs with status indicators, schedule expressions, last/next run times, and duration. Get alerted when cron jobs fail.

📜 Session History & Transcripts

Every session is logged with timeline, tool calls, and cost. The transcript viewer shows conversations in a chat-bubble UI with color-coded roles.

📁 Memory File Browser

Browse and track changes to your agent's memory files: SOUL.md, MEMORY.md, AGENTS.md, and daily notes. See what changed and when.

🏥 System Health

At-a-glance dashboard showing service uptime, disk usage, active sub-agents, and cron job status.

Configuration

ClawMetry works with zero configuration. It auto-detects your OpenClaw workspace by looking for standard files and directories. To customize:

• CLAWMETRY_PORT — Change the port (default: 8900)
• CLAWMETRY_HOST — Change the host (default: 0.0.0.0)
• OPENCLAW_HOME — Point to a specific OpenClaw workspace

How ClawMetry Compares

Feature	ClawMetry	Grafana	Datadog	LangSmith
AI agent native	✅	❌	❌	Partial
Zero config	✅	❌	❌	❌
Self-hosted	✅	✅	❌	❌
Free	✅	✅	❌	Limited
Sub-agent visibility	✅	❌	❌	❌
Token cost tracking	✅	Manual	Manual	✅
One-command install	✅	❌	❌	❌

FAQ

Does ClawMetry work without OpenClaw?

Yes. ClawMetry works with 12 AI agent runtimes: OpenClaw, NVIDIA NemoClaw, Claude Code, Codex, Cursor, Aider, Goose, Hermes, opencode, Qwen Code, NanoClaw, and PicoClaw. It reads each runtime's sessions, logs, and tool activity to give you one observability dashboard across all of them. OpenClaw and NemoClaw are free on every plan.

Is my data sent anywhere?

No. ClawMetry runs entirely locally. No data leaves your machine. No cloud accounts, no telemetry, no tracking.

Can I run it on a Raspberry Pi?

Yes! ClawMetry is lightweight (single Python file + Flask). It runs on any device that supports Python 3.8+.

How do I update?

pip install --upgrade clawmetry

Where do I report bugs?

Open an issue on GitHub.

← Back to Home