Mapick Cost Firewall

The big red switch for runaway AI agents.

Local LLM cost monitoring, automatic breaker rules, dashboard control, and one-command emergency stop for OpenClaw.
Catch retry loops, token storms, and surprise AI bills before they become screenshots.

Try it · Dashboard · Kill switch · What it stops · Commands · Privacy · Where it fits

---

Why This Exists

AI agents are wonderful until one gets stuck in a retry loop at 3 AM.

Provider dashboards tell you what happened after the bill lands. Mapick Cost Firewall acts earlier: it watches local call metadata, detects runaway behavior, and trips a breaker before one broken source keeps spending.

Think of it as a handbrake for agent infrastructure:

openclaw firewall stop

One command. Every AI call paused. Breathe first, debug second.

Try It

Verified on a real OpenClaw instance with v0.2.9.

curl -fsSL https://raw.githubusercontent.com/mapick-ai/cost-firewall/v0.2.12/install.sh | bash
openclaw firewall status

Manual install:

openclaw plugins install @mapick/cost-firewall
openclaw plugins enable mapick-firewall
openclaw gateway restart
openclaw firewall status

Recommended first run:

openclaw firewall mode observe
openclaw firewall log --last 20

Start in observe mode, watch what would have happened, then switch to protect once the thresholds match your workload.

openclaw firewall mode protect

Dashboard

After install, open:

http://localhost:18789/mapick/dashboard

The dashboard is local to your OpenClaw gateway and shows:

• today's token spend
• blocked count and saved estimate
• emergency stop state
• breaker thresholds
• cooling sources
• active runs
• recent firewall events

The same emergency brake is available from the dashboard and the CLI.

Kill Switch

When an agent starts spending faster than you can read logs:

openclaw firewall stop

Confirm it:

openclaw firewall status

You should see:

{
  "emergency_stop": true
}

When you are ready to resume:

openclaw firewall resume

What It Stops

Failure mode	What Mapick watches	Default behavior
Retry loop	Same source fails repeatedly	Trip after 3 consecutive failures
Token storm	Tokens used inside a sliding window	Trip at 100K tokens / 60s
Call flood	Calls made inside a sliding window	Trip at 30 calls / 60s
Budget runaway	Daily token total crosses your cap	Block globally until reset
Panic moment	You hit emergency stop	Block all AI calls immediately

Sources are tracked independently where OpenClaw provides enough context. One noisy agent should not take every other agent down with it.

Commands

Command	Action
openclaw firewall status	Show mode, token count, blocked count, limits, cooldown sources
openclaw firewall stop	Emergency stop: pause all AI calls
openclaw firewall resume	Resume after emergency stop
openclaw firewall mode observe	Record only, do not block
openclaw firewall mode protect	Enable breaker rules
openclaw firewall budget set 500000	Set a daily token cap
openclaw firewall budget reset	Remove the daily token cap
openclaw firewall log --last 20	Show recent firewall events
openclaw firewall reset <source>	Clear cooldown for one source

OpenClaw chat command registration uses the same vocabulary: /firewall status, /firewall stop, /firewall resume, /firewall log.

Configuration

{
  "plugins": {
    "entries": {
      "mapick-firewall": {
        "enabled": true,
        "config": {
          "dailyTokenLimit": null,
          "breaker": {
            "consecutiveFailures": 3,
            "cooldownSec": 30,
            "tokenVelocityThreshold": 100000,
            "tokenVelocityWindowSec": 60,
            "callFrequencyThreshold": 30,
            "callFrequencyWindowSec": 60,
          },
        },
      },
    },
  },
}

Defaults are meant to catch obvious loops. Raise thresholds for busy agent workloads; lower the daily cap for hobby projects or demos.

How It Works

flowchart LR
  A["Agent / OpenClaw session"] --> B{"Mapick Cost Firewall"}
  B -->|"allowed"| C["Upstream LLM"]
  B -->|"blocked"| D["Synthetic blocked response"]
  C --> E["Usage metadata"]
  E --> F["Breaker state"]
  F -->|"trip"| B
  E --> G["Local JSONL events"]
  G --> H["CLI / dashboard"]

Loading

Mapick does not need prompt text to trip breakers. The useful signals are metadata:

• source identifier
• provider and model
• outcome and error category
• estimated token usage
• timestamps and cooldown state

Privacy

Question	Answer
Does it need a Mapick account?	No
Does it send telemetry to Mapick?	No
Does it store prompt text by default?	No
Where are events stored?	Local OpenClaw plugin state
Can I audit it?	Yes, MIT licensed TypeScript

The default privacy setting is storePromptText: false.

Verified On Real OpenClaw

v0.2.9 was tested on a real OpenClaw gateway:

Check	Result
Package installed	@mapick/cost-firewall@0.2.9
Gateway status	running
API route	/mapick/api/stats returns application/json
Dashboard route	/mapick/dashboard returns Mapick Firewall HTML
CLI status	returns version: 0.2.9
Emergency stop	openclaw firewall stop sets emergency_stop: true
Resume	openclaw firewall resume sets emergency_stop: false
Test suite	9 files, 47 tests passing

If you previously installed early builds, you may see a duplicate plugin warning from an old legacy path. The active plugin should point to:

~/.openclaw/npm/node_modules/@mapick/cost-firewall/dist/index.js

and report:

{
  "version": "0.2.9"
}

Where It Fits

Mapick is not trying to replace a full AI gateway or observability platform.

Tool category	Examples	Use them for	Use Mapick for
AI gateway	LiteLLM, Portkey Gateway	multi-provider routing, load balancing, central API access	local emergency brake and cost circuit breaker
Observability	Helicone, Langfuse	traces, analytics, experiments, dashboards	stopping a runaway local agent immediately
Provider dashboard	OpenAI, OpenRouter, Anthropic	billing history and provider-side usage	local pre-bill intervention
DIY scripts	shell, cron, custom rate limits	one-off control	packaged rules, CLI, dashboard, OpenClaw integration

The shortest positioning: gateways route, dashboards explain, Mapick brakes.

Troubleshooting

If openclaw firewall status fails, check that the API is mounted:

curl -i http://127.0.0.1:18789/mapick/api/stats

Expected:

Content-Type: application/json

If you see OpenClaw Control HTML instead, restart the gateway:

openclaw gateway restart
openclaw firewall status

If you installed older beta builds and see a duplicate plugin warning, remove or ignore the old legacy extension path after confirming the active plugin is 0.2.9.

Development

npm install
npm run build
npm test

License

MIT