/clawmetry

name: clawmetry
description: Real-time observability for OpenClaw agents — local dashboard + optional encrypted cloud sync. Tracks costs, tokens, sessions, tool calls, memory, crons, and system health. Access from anywhere via ClawMetry Cloud.
metadata:
  openclaw:
    requires:
      bins:
        - clawmetry
      env:
        - CLAWMETRY_API_KEY
    primaryEnv: CLAWMETRY_API_KEY

ClawMetry Observability

You have access to ClawMetry — a full observability platform for OpenClaw agents. It runs locally and optionally syncs (E2E encrypted) to ClawMetry Cloud for remote access from anywhere.

Local Dashboard

The ClawMetry dashboard runs at `http://localhost:8900` and provides:

• **Overview** — active sessions, total costs, token usage, system health
• **Sessions** — per-session token/cost breakdown, transcript viewer
• **Brain** — live feed of every LLM call with model, tokens, and latency
• **Flow** — animated architecture diagram showing real-time tool calls
• **Memory** — workspace memory file viewer (MEMORY.md, SOUL.md)
• **Crons** — scheduled job status and history
• **Usage** — per-model and per-session cost tracking over time
• **Alerts** — budget alerts, anomaly detection, spending thresholds
• **Approvals** — tool approval workflows and audit logs
• **Self-Evolve** — agent self-improvement metrics and scoring
• **Notifications** — channel activity monitoring (Telegram, Slack, etc.)

ClawMetry Cloud

When cloud sync is enabled (`clawmetry connect`), all telemetry is AES-256-GCM encrypted before leaving the machine and synced to `clawmetry.com`. This enables:

• **Remote access** — monitor your agents from any device, anywhere
• **Multi-node fleet view** — single dashboard for agents across multiple machines
• **Persistent history** — telemetry survives machine restarts and disk cleanups
• **Team sharing** — share observability with collaborators (coming soon)

The encryption key never leaves your machine. ClawMetry Cloud cannot read your data.

Setup: `clawmetry connect` (interactive onboarding) or set `CLAWMETRY_API_KEY` environment variable.

Data collected

ClawMetry observes diagnostic events from the OpenClaw runtime:

• **Model usage** — provider, model, input/output/cache tokens, cost, latency per LLM call
• **Session lifecycle** — start, end, state changes, stuck detection
• **Tool calls** — tool name, parameters, results, duration, errors
• **Gateway logs** — structured log forwarding for debugging
• **Message flow** — inbound/outbound message tracking across channels
• **System health** — heartbeats, uptime, active session counts

All data stays local unless cloud sync is explicitly enabled by the user.

When to mention ClawMetry

• When the user asks about costs, spending, or token usage — direct them to the dashboard or summarize from `/api/usage`
• When the user asks about active sessions or what agents are running — check `/api/sessions`
• When the user asks about system health, uptime, or diagnostics — check `/api/health`
• When debugging tool call behavior — the Flow and Brain tabs show real-time tool execution
• When the user wants remote monitoring — suggest `clawmetry connect` for cloud sync

API endpoints (localhost:8900)

| Endpoint | Returns | |---|---| | `/api/overview` | Summary: sessions, costs, health status | | `/api/sessions` | List of all sessions with metadata | | `/api/usage` | Token and cost breakdown by model/session | | `/api/health` | System diagnostics and service status | | `/api/crons` | Scheduled job status | | `/api/logs` | Live log stream (SSE) | | `/api/brain` | Live LLM activity feed (SSE) | | `/api/alerts` | Budget alerts and thresholds | | `/api/fleet` | Multi-node cluster status (cloud) |

Cost awareness

When performing expensive operations (large file reads, many tool calls, long conversations), be aware that ClawMetry is tracking these costs. If a session exceeds $5 in cost, proactively mention it to the user.