Agentic Ledger is a local-first proxy and analytics layer for OpenClaw that tracks usage, enforces budgets, and replays runs.
Install & Download
1. ClawHub CLI
The fastest way to install a skill directly from the registry.
npx clawhub@latest install agentic-ledger
2. Manual Installation
Copy the skill folder to one of these locations
~/.openclaw/skills/ <project>/skills/ Priority: Workspace > Local > Bundled
3. Prompt Installation
Copy this prompt to OpenClaw to install it automatically.
Help me install agentic-ledger using Clawhub. If Clawhub is not installed, install it first (npm i -g clawhub).
Prefer to download?
Get the raw skill files in a ZIP archive.
What is Agentic Ledger?
Agentic Ledger is an Openclaw Skills workflow for observing, controlling, and optimizing agent spend without sending data off-machine. It sits between OpenClaw and the model provider, recording every prompt, response, token count, latency, cost, and error locally while preserving full privacy.
Beyond reporting, it can enforce hard budget walls that refuse calls once thresholds are crossed, making it more than a dashboard. It also supports replaying captured runs on cheaper or local models so you can compare quality, cost, and failure modes before changing your production setup.
Agentic Ledger Use Cases
- Track token usage, dollar spend, latency, and errors for OpenClaw agent activity.
- Answer "what did the agent do?" and "how much did it cost?" using real ledger data, not estimates.
- Enforce daily or session budget caps that block new calls when limits are exceeded.
- Diagnose repeated loops, runaway runs, and model cost spikes.
- Re-run captured sessions on cheaper or local OpenAI-style models to evaluate savings.
- Review per-model breakdowns, blocked calls, and cache savings from recent activity.
How Agentic Ledger Works
- Install Agentic Ledger on the host machine and start the local proxy service.
- Connect OpenClaw so its model provider base URL points to the ledger proxy, including Docker-aware host detection when needed.
- Let OpenClaw run normally; the proxy intercepts each call and records prompts, responses, tokens, cost, latency, and errors on the local machine.
- Query the ledger APIs or dashboard to inspect reports, sessions, runs, and spend over time.
- Configure budgets to create hard refusal walls that stop forwarding calls when daily or session limits are reached.
- Use the replay feature from the dashboard to rerun captured sessions against cheaper or local models and compare output quality versus total cost.
Agentic Ledger Setup
Run Agentic Ledger on the host machine, not inside the OpenClaw container:
pip install agentic-ledger
agenticledger start
agenticledger connect openclaw
If agenticledger is not on your PATH, run it from the virtual environment bin directory:
<venv>/bin/agenticledger
After connecting, restart the OpenClaw gateway so the updated provider URL is loaded. If you need to set an explicit upstream or are using a custom gateway, configure it and restart the proxy:
agenticledger config set proxy.upstream_url <your provider or gateway URL>
agenticledger stop && agenticledger start
Recommended OpenClaw approval setup for repeated read-only cost checks:
openclaw approvals allowlist add --agent main "/usr/bin/curl"
Verify the service is reachable, using the host address that works in your environment:
curl -s -m 3 http://localhost:8000/health || curl -s -m 3 http://host.docker.internal:8000/health
The dashboard is available at http://localhost:8000 in the host browser.
Agentic Ledger Data Schema & Taxonomy
Agentic Ledger organizes data as locally stored run, session, report, and replay records. The proxy persists all captured events on the host machine and does not store provider API keys.
Core record types
| Entity | Purpose | Typical contents |
|---|---|---|
| Session | Groups related agent activity | session ID, time window, cumulative spend, model mix |
| Run | Captures a distinct execution | prompt, response, tokens, latency, cost, error state |
| Report | Aggregates spend and usage over a time range | total spend, per-model totals, cache savings, blocked calls |
| Replay | Re-executes a captured run on another model | original output, replay output, quality comparison, dual cost totals |
Taxonomy and metadata
tokens: prompt and completion usage per call.cost: per-call and aggregated dollar spend.latency: request duration metrics.errors: provider failures and blocked requests.blocked: amber budget-wall refusals that indicate enforcement working as intended.model: provider/model identifier used for breakdowns.cache_savings: optimization signal when notable.status: refusal status used for budget walls; 402 is recommended for OpenClaw to prevent retry loops.
Local endpoints used by Openclaw Skills
GET /health— service health check.GET /api/reports?days=7— recent spend and usage summary.GET /api/runs— captured runs.GET /api/sessions— session history.
Storage and privacy notes
- All operational data stays on the local machine.
- No cloud account is required.
- No telemetry is sent upstream.
- Provider API keys are forwarded per call by OpenClaw and are not stored in the ledger.
Agentic Ledger Advanced Features
- Local-first architecture that keeps usage data on the host machine with no cloud dependency.
- Hard budget enforcement that refuses calls once daily or session limits are exceeded.
- OpenClaw-aware connection flow that detects Docker and rewrites the provider endpoint correctly.
- Wire-format routing for both Anthropic and OpenAI-style providers without extra upstream configuration on modern versions.
- JSON API access for automated reporting, programmatic audits, and external tooling.
- Replay mode for comparing a real captured run against cheaper or local models like LM Studio or any OpenAI-style server.
- Dashboard-based side-by-side grading of original versus replayed output, including cost comparison and match quality.
- Optional API key support for secured reads without exposing provider credentials.
SKILL.md
Loading
Related Openclaw Skills
China Weather Data
Openclaw Skills for China Weather Data lets you query, download, and automate China meteorological station weather data with an official CMA source and a free Open-Meteo fallback.
GeoTIFF Metadata Viewer
Openclaw Skills for GeoTIFF Metadata Viewer lets you inspect GeoTIFF file metadata, CRS, resolution, tags, and corner coordinates with zero dependencies.
China Administrative Divisions Downloader
Openclaw Skills for downloading and exporting Chinese administrative-division vector data with search, metadata lookup, bbox calculation, and batch GIS output.
Open-Elevation
Openclaw Skills for Open-Elevation lets you query global elevation data by latitude and longitude, both one point at a time and in large batches.
WorkBuddy Session Callback
WorkBuddy Session Callback lets one session, cron job, or external process wake another WorkBuddy session and inject a message with full context.
yt-agent
yt-agent turns YouTube videos and subscriptions into grounded summaries, highlights, Q&A, presentations, and digests through the yt-mem-ai CLI.
Featured*
