---
title: proxy
description: The ClawMetry enforcement proxy — budget limits, loop detection and model routing on port 4100, with every subcommand and flag.
keywords: LLM budget proxy, agent spend limit, loop detection proxy, model routing
eyebrow: CLI reference
---

# `clawmetry proxy`

A local proxy that sits in front of your model calls and enforces limits.
Optional — observation does not need it — but it is the only place a budget can
actually *block* rather than merely alert.

```bash
clawmetry proxy start
```

## Subcommands

### `proxy start`

| Flag | Default | Effect |
|---|---|---|
| `--port` | `4100` | Port to listen on |
| `--host` | `127.0.0.1` | Bind address |
| `--daily-budget USD` | — | Daily spend limit |
| `--monthly-budget USD` | — | Monthly spend limit |
| `--no-loop-detection` | | Disable loop detection |
| `--log-requests` | | Log every proxied request |
| `--foreground` | | Run in the foreground |

```bash
clawmetry proxy start --daily-budget 25 --monthly-budget 400
```

### `proxy stop`

```bash
clawmetry proxy stop
```

### `proxy status`

```bash
clawmetry proxy status
clawmetry proxy status --json
```

### `proxy config`

Read or change the configuration without restarting.

| Flag | Values | Effect |
|---|---|---|
| `--daily-budget USD` | | Set the daily budget |
| `--monthly-budget USD` | | Set the monthly budget |
| `--action` | `block`, `warn`, `downgrade` | What happens at the limit |
| `--loop-detection` | `on`, `off` | Toggle loop detection |

```bash
clawmetry proxy config --daily-budget 50 --action warn
clawmetry proxy config --action block
clawmetry proxy config --loop-detection on
```

## Budget actions

| Action | Behaviour at the limit |
|---|---|
| `warn` | Let the call through, record and surface it |
| `block` | Refuse the call |
| `downgrade` | Route to a cheaper model instead of refusing |

Start on `warn`. Moving to `block` before you trust the numbers is how people
end up with a broken agent and no idea why. `downgrade` is the humane middle:
the work continues, more cheaply, and the dashboard tells you it happened.

## Pointing agents at it

The proxy is a standard HTTP proxy for provider endpoints. Configure the runtime
to use it as its base URL — the mechanism differs per runtime and per SDK, but
it is the same base-URL override you would use for any gateway.

## Why OpenClaw's pause needs it

OpenClaw has no pause primitive. ClawMetry's pause for an OpenClaw session is a
flag file that **only the proxy enforces**. With no proxy running, a "pause" on
an OpenClaw session changes nothing, and the Guard tab reports `advisory_only`
rather than claiming the agent was held.

If pausing OpenClaw agents matters to you, run the proxy.

→ [Pause, stop, kill](/docs/guard/process-control/)

## Loop detection

The proxy detects repeated identical calls in-flight, which is earlier than the
transcript-based [detectors](/docs/guard/detectors/) can see them. The two are
complementary: the proxy catches a tight loop before it costs much, the
detectors catch the slower shapes — busy-but-not-progressing, repeated tool
failures — that only appear over a window.

| Variable | Effect |
|---|---|
| `CLAWMETRY_PROXY_DAILY_USD` | Daily budget |
| `CLAWMETRY_PROXY_MONTHLY_USD` | Monthly budget |
| `CLAWMETRY_PROXY_AUTO_ROUTE` | Automatic model routing |

→ [Enforcement proxy](/docs/guard/proxy/) for the design, and
[Budgets and limits](/docs/cost/budgets/) for how it fits with alerts.