convez.ai
AgenteDevOps & InfraestruturaIntermediário
vivekchand

ClawMetry

vivekchand/clawmetry

Observabilidade unificada para agentes IA - zero config, auto-detecção

Ver no GitHub
BomPluginScore · de 0 a 100

Plataforma de observabilidade em tempo real para 12 runtimes de agentes IA diferentes (OpenClaw, NVIDIA NemoClaw, Claude Code e outros). Oferece um único dashboard para monitorar fluxos de mensagens, uso de tokens, custos, logs e sessões de toda sua frota de agentes.

Instalação

$npx convez-ai vivekchand/clawmetry

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
439
Forks
73
Acompanhando
7
Saúde
85%
Último commit
há 1 dia
Versão
v0.12.899
Issues abertas
67
Contribuidores
16

Casos de uso

  • Monitorar agentes IA em produção com visualização em tempo real
  • Rastrear custos e consumo de tokens por runtime de agente
  • Debugar fluxos de execução de agentes com logs e transcripts
  • Configurar alertas e aprovações para operações críticas

Veredito

ClawMetry é uma ferramenta robusta e necessária para quem trabalha com múltiplos agentes IA em produção. A auto-detecção zero-config e o dashboard unificado reduzem significativamente a complexidade operacional, embora sua utilidade máxima dependa de ter múltiplos runtimes ativos.

README

A tradução para o português deste README ainda está na fila.

🦞 ClawMetry

PyPI Downloads PyPI Downloads/week PyPI version GitHub stars License: MIT

See your agent think. Real-time observability for 12 AI agent runtimes: OpenClaw, NVIDIA NemoClaw, Claude Code, OpenAI Codex & 8 more. One dashboard for your whole agent fleet.

🌐 Read this in: English · 简体中文 · 日本語 · 한국어 · Español · Português (BR) · Français · Deutsch · हिन्दी · العربية · Русский · more →

One command. Zero config. Auto-detects everything.

pip install clawmetry && clawmetry

Opens at http://localhost:8900 and you're done.

Flow Visualization

Works with 12 agent runtimes

ClawMetry started as observability for OpenClaw, and now meters your whole agent fleet in one dashboard, auto-detecting each runtime on your machine:

🦞 OpenClaw · 🟩 NVIDIA NemoClaw · ◆ Claude Code · ⬡ OpenAI Codex · Cursor · 🪿 Goose · ⚡ Hermes · opencode · ◈ Qwen Code · Aider · NanoClaw · PicoClaw

OpenClaw and NemoClaw are free in the open-source app; the other runtimes light up with ClawMetry Cloud or a self-hosted Pro license. Switch runtimes from the header and every tab — cost, tokens, tools, traces — re-scopes to that runtime.

What You Get

  • Flow — Live animated diagram showing messages flowing through channels, brain, tools, and back
  • Overview — Health checks, activity heatmap, session counts, model info
  • Usage — Token and cost tracking with daily/weekly/monthly breakdowns
  • Sessions — Active agent sessions with model, tokens, last activity
  • Crons — Scheduled jobs with status, next run, duration
  • Logs — Color-coded real-time log streaming
  • Memory — Browse SOUL.md, MEMORY.md, AGENTS.md, daily notes
  • Transcripts — Chat-bubble UI for reading session histories
  • Alerts — Budget caps, error-rate triggers, agent-offline detection; routes to Slack, Discord, PagerDuty, Telegram, Email
  • Approvals — Gate destructive deletes, force pushes, DB mutations, sudo, package installs, network calls behind one-click sign-off

Screenshots

🧠 Brain — Live agent event stream

Brain tab

📊 Overview — Token usage & session summary

Overview tab

⚡ Flow — Real-time tool call feed

Flow tab

💰 Tokens — Cost breakdown by model & session

Tokens tab

🧬 Memory — Workspace file browser

Memory tab

🔐 Security — Posture & audit log

Security tab

🚨 Alerts — Budget caps, error-rate triggers, webhooks to Slack / Discord / PagerDuty / Email

Alerts tab

✋ Approvals — Gate risky tool calls behind manual sign-off; policy-backed protection rules

Approvals tab

Install

One-liner (recommended):

curl -sSL https://raw.githubusercontent.com/vivekchand/clawmetry/main/install.sh | bash

pip:

pip install clawmetry
clawmetry

From source:

git clone https://github.com/vivekchand/clawmetry.git
cd clawmetry && pip install flask && python3 dashboard.py

v2 Frontend Development

The v2 React app lives in frontend/ and is served at /v2 when the Flask server is started with v2 enabled.

Use two terminals while developing:

# Terminal 1: Flask API/server on :8900
CLAWMETRY_V2=1 python3 dashboard.py
# Terminal 2: Vite dev server on :5173
cd frontend
nvm use
npm ci
npm run dev

Open http://localhost:5173/v2/. Vite proxies /api requests to http://localhost:8900, so the React app can talk to the local Flask server without extra CORS setup.

To build the bundle that ships with the Python package:

cd frontend
npm run build

The production bundle is written to clawmetry/static/v2/dist/.

Runtime / Agent Compatibility

ClawMetry observes many AI-agent runtimes, not just OpenClaw. Each non-OpenClaw runtime ships a dedicated reader adapter that translates its native session format into ClawMetry's unified shapes; the daemon ingests them into the same DuckDB store + cloud snapshot, tagged with the runtime, and the Session replay tab shows a runtime switcher when more than one is present. See docs/compatibility.md for the full matrix + a guide to adding runtimes, and docs/RUNTIME_FAMILY.md for the OpenClaw-family primer.

Runtime / AgentStatusNotes
OpenClawNativeReference runtime, auto-detected
PicoClawBeta adapterFlat providers.Message JSONL (~/.picoclaw/workspace/sessions). Transcripts, model, tool calls.
NanoClawBeta adapterPer-session SQLite (data/v2-sessions). Transcripts + message counts.
HermesBeta adapterSQLite ~/.hermes/state.db. Transcripts, model, tokens/cost.
Claude CodeBeta adapterJSONL ~/.claude/projects/.../<id>.jsonl. Transcripts, model, tool calls + thinking, token usage.
CodexBeta adapterRollout JSONL ~/.codex/sessions/.... Transcripts, model, tool calls, token usage.
CursorBeta adapterSQLite state.vscdb. Chat/composer transcripts, model.
AiderBeta adapter.aider.chat.history.md per project. Transcripts, model, token counts.
GooseBeta adapterSQLite ~/.local/share/goose. Transcripts, model, tool calls, token totals.
opencodeBeta adapterSQLite ~/.local/share/opencode. Transcripts, model, tool calls, tokens + cost.
Qwen CodeBeta adapterJSONL ~/.qwen/projects/.../chats. Transcripts, model, tool calls, token usage.

"Beta adapter" means ClawMetry ships a reader for that runtime's real on-disk format, each built + verified against a real install on a real machine (see tests/fixtures/runtimes/<rt>/). Adapters are read-only; each is honest about what its runtime actually stores (e.g. PicoClaw/NanoClaw/Cursor don't write token cost to disk). When several runtimes run on one node, the runtime switcher scopes the sessions view to one for a clean deep-dive.

Track any SDK agent — out-loop cost attribution

The runtimes above all write sessions to disk. Your own production agent — the one you built on the OpenAI Agents SDK, LangChain, the Vercel AI SDK, LlamaIndex, E2B, or a plain httpx loop — doesn't. ClawMetry's zero-config interceptor still captures its LLM calls (cost, tokens, latency, errors) by monkey-patching httpx/requests:

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

# ...your agent runs as normal; every LLM call is now tracked + attributed.

set_source() (or the CLAWMETRY_SOURCE=support-agent env var) tags each call with a named source, so every product you run shows up as its own first-class, cost-attributable line in the dashboard's 🔌 Out-loop sources card on Overview — calls, providers, latency, error rate per agent. No source set? The calls are still tracked; the card just stays hidden.

CLAWMETRY_SOURCE=billing-agent python my_agent.py

This is the same data layer the runtime adapters feed (DuckDB → cloud snapshot), so out-loop sources sync to the cloud dashboard the same as everything else, E2E-encrypted.

OpenTelemetry — vendor-neutral, send your traces anywhere

ClawMetry speaks OpenTelemetry in both directions, using the GenAI semantic conventions, so your agent traces are never locked into one tool.

Export every session — LLM calls, tools, sub-agents, tokens, cost — as OTLP/HTTP GenAI spans to any collector (Datadog, Grafana, Honeycomb, or your own OTel Collector):

clawmetry --otel-export http://localhost:4318/v1/traces
# equivalently:
CLAWMETRY_OTEL_EXPORT_ENDPOINT=http://localhost:4318/v1/traces clawmetry

Auth headers and poll interval are optional env vars:

CLAWMETRY_OTEL_EXPORT_HEADERS='{"X-API-Key":"…"}'   # extra HTTP headers
CLAWMETRY_OTEL_EXPORT_INTERVAL=60                    # seconds (default 60)

Ingest — the built-in OTLP receiver accepts traces and metrics from anything else at /v1/traces and /v1/metrics (pip install clawmetry[otel] for protobuf ingest).

You get the zero-config, local-first ClawMetry dashboard and your data in whatever backend your team already runs — no lock-in, no second agent to install.

Configuration

Most people don't need any config. ClawMetry auto-detects your workspace, logs, sessions, and crons.

If you do need to customize:

clawmetry --port 9000              # Custom port (default: 8900)
clawmetry --host 127.0.0.1         # Bind to localhost only
clawmetry --workspace ~/mybot      # Custom workspace path
clawmetry --name "Alice"           # Your name in Flow visualization

All options: clawmetry --help

Supported Channels

ClawMetry shows live activity for every OpenClaw channel you have configured. Only channels that are actually set up in your openclaw.json appear in the Flow diagram — unconfigured ones are automatically hidden.

Click any channel node in the Flow to see a live chat bubble view with incoming/outgoing message counts.

ChannelStatusLive PopupNotes
📱 Telegram✅ Full✅Messages, stats, 10s refresh
💬 iMessage✅ Full✅Reads ~/Library/Messages/chat.db directly
💚 WhatsApp✅ Full✅Via WhatsApp Web (Baileys)
🔵 Signal✅ Full✅Via signal-cli
🟣 Discord✅ Full✅Guild + channel detection
🟪 Slack✅ Full✅Workspace + channel detection
🌐 Webchat✅ Full✅Built-in web UI sessions
📡 IRC✅ Full✅Terminal-style bubble UI
🍏 BlueBubbles✅ Full✅iMessage via BlueBubbles REST API
🔵 Google Chat✅ Full✅Via Chat API webhooks
🟣 MS Teams✅ Full✅Via Teams bot plugin
🔷 Mattermost✅ Full✅Self-hosted team chat
🟩 Matrix✅ Full✅Decentralized, E2EE support
🟢 LINE✅ Full✅LINE Messaging API
⚡ Nostr✅ Full✅Decentralized NIP-04 DMs
🟣 Twitch✅ Full✅Chat via IRC connection
🔷 Feishu/Lark✅ Full✅WebSocket event subscription
🔵 Zalo✅ Full✅Zalo Bot API

Auto-detection: ClawMetry reads your ~/.openclaw/openclaw.json and only renders the channels you've actually configured. No manual setup required.

Docker Deployment

Want to run ClawMetry in a container? No problem! 🐳

Quick start with Docker:

# Build the image
docker build -t clawmetry .

# Run with default settings
docker run -p 8900:8900 clawmetry

# Or mount your agent's data dir (shown: OpenClaw's ~/.openclaw)
docker run -p 8900:8900 \
  -v ~/.openclaw:/root/.openclaw \
  -v /tmp/moltbot:/tmp/moltbot \
  clawmetry

Docker Compose example:

version: '3.8'
services:
  clawmetry:
    build: .
    ports:
      - "8900:8900"
    volumes:
      - ~/.openclaw:/root/.openclaw:ro
      - /tmp/moltbot:/tmp/moltbot:ro
    restart: unless-stopped

Note: When running in Docker, mount your agent's data + log directories (e.g. ~/.openclaw, ~/.claude, ~/.codex) so ClawMetry can auto-detect your setup.

Requirements

  • Python 3.8+
  • Flask (installed automatically via pip)
  • An AI agent runtime on the same machine: OpenClaw, NVIDIA NemoClaw, Claude Code, Codex, Cursor, Goose, Hermes, opencode, Qwen Code, Aider, NanoClaw, or PicoClaw (or mounted volumes for Docker)
  • Linux or macOS

NemoClaw / OpenShell Support

ClawMetry automatically detects NemoClaw — NVIDIA's enterprise security wrapper for OpenClaw that runs agents inside sandboxed OpenShell containers.

No extra configuration is needed in most cases. The sync daemon auto-discovers session files whether they live in ~/.openclaw/ on the host or inside an OpenShell container.

How it works

ClawMetry detects NemoClaw in two ways:

  1. Binary detection — checks for the nemoclaw CLI and runs nemoclaw status to get sandbox info
  2. Container detection — scans running Docker containers for openshell, nemoclaw, or ghcr.io/nvidia/ images, then reads sessions via volume mounts or docker cp

Session files synced from NemoClaw containers are tagged with runtime=nemoclaw and container_id metadata in the cloud dashboard, so you can tell them apart from standard OpenClaw sessions at a glance.

Recommended setup: sync daemon on the HOST

For the best experience, run ClawMetry's sync daemon on the host machine (not inside the sandbox). This avoids NemoClaw network policy restrictions.

# On the host (outside the sandbox)
pip install clawmetry
clawmetry connect
clawmetry sync

The sync daemon will automatically find sessions inside any running OpenShell containers.

Optional: explicit sandbox name

If auto-detection doesn't work, point ClawMetry at the right sandbox:

export NEMOCLAW_SANDBOX=my-sandbox-name
clawmetry sync

Running inside the sandbox (advanced)

If you must run the sync daemon inside the OpenShell sandbox, add this egress rule to your NemoClaw network policy so it can reach the ClawMetry ingest API:

# nemoclaw-policy.yaml
network:
  egress:
    - host: ingest.clawmetry.com
      port: 443
      protocol: https

Apply with:

nemoclaw policy apply --file nemoclaw-policy.yaml

Ports and endpoints

EndpointPortProtocolRequired
ingest.clawmetry.com443HTTPSYes (sync daemon → cloud)
localhost:89008900HTTPYes (local dashboard UI)
Docker socket (/var/run/docker.sock)—Unix socketFor container session discovery

The sync daemon only makes outbound HTTPS calls to ingest.clawmetry.com. No inbound ports are required.


Cloud Deployment

See the Cloud Testing Guide for SSH tunnels, reverse proxy, and Docker.

Testing

This project is tested with BrowserStack.

BrowserStack

Telemetry

ClawMetry sends a single anonymous "first run" ping to https://app.clawmetry.com/api/install the first time you run the clawmetry CLI on a new machine. We use this to count installs (the only marketing metric we have for an OSS project) and to learn which agent frameworks our users have installed.

Exactly one POST per install, containing:

FieldExampleWhy
install_idrandom UUID stored at ~/.clawmetry/install_iddedup; not linked to your email or api_key
version0.12.167what versions are in the wild
os / os_versionDarwin / 25.3.0platform support priorities
python3.11.15Python version support matrix
agentopenclaw / nemoclaw / hermes / nonewhich agents we should integrate with next
is_ci / ci_providertrue / github_actionsseparate human installs from CI noise

What we do NOT send: IP (cloud derives the country code server-side from the request, then discards the IP), hostname, username, workspace path, file contents, your api_key, your email, anything PII or workspace-specific. The wire payload is auditable in clawmetry/telemetry.py.

Opt out (any one of these disables it permanently):

export CLAWMETRY_NO_TELEMETRY=1                # per-shell
export DO_NOT_TRACK=1                          # W3C cross-tool standard
touch ~/.clawmetry/notelemetry                 # persistent file marker

A network failure here never blocks clawmetry from running — the ping is fire-and-forget on a daemon thread with a 3 s timeout.

Star History

License

MIT


Ver o original no GitHub

Bom para

Relacionados