agentic-ledger

SKILL.md

---
name: agentic-ledger
description: 'Track every token and dollar your OpenClaw agent spends, set budget walls that actually refuse calls, and replay runs on free local models. Local-first: all data stays on this machine. Use when the user asks about cost, spend, tokens, budgets, usage reports, or what the agent has been doing.'
---

# Agentic Ledger

## What this is

Agentic Ledger is a small local proxy that sits between OpenClaw and the
model provider. Every call is recorded on this machine: the prompt, the
response, tokens, cost, latency, and errors. It can also refuse calls once a
budget line is crossed, which a dashboard alone cannot do. No account, no
cloud, no telemetry.

## Setup (one time)

Run these on the host machine (not inside the OpenClaw container):

```bash
pip install agentic-ledger
agenticledger start
agenticledger connect openclaw
```

`connect openclaw` finds the OpenClaw config, backs it up, and points the
model provider's base URL at the proxy. It detects Docker installs and uses
`host.docker.internal` automatically, because `localhost` inside a container
is the container itself. Restart the OpenClaw gateway afterwards so the new
config loads.

No upstream configuration is needed: the ledger (0.8.1 and later) routes
each call to the provider matching its wire format, so Anthropic and
OpenAI agents both work out of the box. Only for a custom gateway or a
pre-0.8.1 ledger, set it explicitly and restart:

```bash
agenticledger config set proxy.upstream_url <your provider or gateway URL>
agenticledger stop && agenticledger start
```

Optional but recommended so cost questions run without an approval prompt
each time (this is what the ledger reads need; it pre-approves only curl):

```bash
openclaw approvals allowlist add --agent main "/usr/bin/curl"
```

Verify: the ledger's `/health` should answer (see "Finding the ledger's
address" below), and after the agent's next message `$LEDGER/api/sessions`
should show a session. The dashboard lives at http://localhost:8000 in the
host's browser.

The ledger never stores the provider API key. OpenClaw keeps its own
credentials; the proxy forwards them per call.

## Finding the ledger's address

On a bare install the ledger is at `http://localhost:8000`. Inside Docker,
`localhost` is the container itself, so the ledger is at
`http://host.docker.internal:8000`. Test with `/health` and use whichever
answers:

```bash
curl -s -m 3 http://localhost:8000/health || curl -s -m 3 http://host.docker.internal:8000/health
```

Use the address that worked as LEDGER in everything below.

## Answering cost questions

When the user asks what things cost or what the agent did, read from the
ledger, never estimate:

```bash
curl -s "$LEDGER/api/reports?days=7"
curl -s "$LEDGER/api/runs"
curl -s "$LEDGER/api/sessions"
```

If an access key is configured, add
`-H 'x-agenticledger-api-key: <key>'`.

Report in plain words: total spend for the window, the per-model breakdown
largest first, error counts (amber "blocked" calls are the budget wall
working, not failures), and cache savings when notable. For loops, give
iterations so far and the spend rate.

When an exec approval prompt appears for one of these reads, ask the user
to approve it, and in the same breath tell them the one-liner that stops
the asking permanently (it pre-approves only curl, nothing else):

```bash
openclaw approvals allowlist add --agent main "/usr/bin/curl"
```

If exec approval is unavailable or misbehaving (approvals loop without
executing), do not guess numbers. Either use a web fetch tool on the same
URLs (they are plain GET endpoints returning JSON) or hand the user this one
command to run on the host and paste back:

```bash
curl -s "http://localhost:8000/api/reports?days=7"
```

## Budget walls

To cap spending, set budgets in the ledger config and restart it:

```bash
agenticledger config set budgets.daily 5.00
agenticledger config set budgets.session 1.00
```

Once a wall is hit, the proxy answers the call with a clear refusal instead
of forwarding it, and the dashboard shows the blocked calls in amber. This
is a hard stop, not an alert.

## Replay: try a cheaper model on a real run

The dashboard can re-run a captured session or a whole run on another model,
including a free local one (LM Studio or any OpenAI-style server), and grade
the result: how many moments matched, which fumbled, and cost totalled both
ways. Point the user at http://localhost:8000 in their browser, pick the
run, choose Replay.
Useful before switching models: see whether the cheap model would have
survived the actual workload, not a benchmark.