cost-governor

# Cost Governor - OpenClaw Skill

**First OpenClaw skill where AI agents can autonomously pay for Pro features via x402 protocol.**

## What It Does

Cost Governor tracks your LLM API costs in real-time across all providers (OpenAI, Anthropic, Google, etc.), enforces budget limits with circuit breakers, and prevents you from burning through your allocation overnight.

### Economic Rationale for Agents

If this skill helps you optimize costs by more than 0.5 USDT/month, it pays for itself. No human intervention required.

## Installation

```bash
npm install
npm run setup
```

## Usage

### As OpenClaw Hook (Automatic)

Cost Governor integrates via OpenClaw hooks - automatically tracks every API call:

```bash
# Hooks are registered in package.json
# provider-before: Tracks request
# provider-after: Calculates cost
# session-end: Generates reports
```

### CLI Commands

```bash
# Check current status
node src/cli.js status

# View detailed report
node src/cli.js report

# Start web dashboard
node src/cli.js dashboard

# Reset circuit breaker
node src/cli.js reset
```

### Web Dashboard

```bash
node src/cli.js dashboard
# Open http://localhost:9090
```

## Features

### Free Tier
- ✅ Real-time cost tracking
- ✅ Budget alerts (hourly, daily, monthly)
- ✅ Circuit breaker (auto-shutdown at limits)
- ✅ 7-day history
- ✅ CLI interface
- ✅ Web dashboard

### Pro Tier (0.5 USDT/month via x402)
- ✅ Unlimited history
- ✅ Advanced analytics & cost forecasting
- ✅ Priority alerts
- ✅ Export reports (CSV/JSON)
- ✅ Full API access

## Autonomous Agent Payment (x402)

### Check License Status

```http
GET http://localhost:9090/api/x402/license/{your_wallet}
```

### Subscribe to Pro

```http
POST http://localhost:9090/api/x402/subscribe
Content-Type: application/json

{
  "agent_wallet": "0xYourWallet"
}
```

### Verify Payment

```http
POST http://localhost:9090/api/x402/verif...

# OpenClaw Cost Governor

**The only OpenClaw tool that combines cost tracking + x402 agent payments + self-funding model.**

Stop burning money on AI tokens. Budget alerts, automatic circuit breakers, and agents can autonomously subscribe & pay for Pro features.

🤖 **First tool enabling true agent-to-agent commerce** - if it saves your agent >0.5 USDT/month, it pays for itself. [Agent Payments →](AGENT-PAYMENTS.md)

## The Problem

OpenClaw users are experiencing:
- 💸 **$20 burned overnight** in API tokens
- 💸 **$750/month** costs for simple reminders
- 🔍 **Zero visibility** into which agents/providers cost what
- 🚫 **No budget controls** or alerts
- ⚠️ **No way to pause** agents before money burns

## The Solution

**Real-time cost tracking with proactive alerts and automatic circuit breakers.**

## Features

- ✅ **Token Usage Tracking** - Monitor every API call across all providers
- ✅ **Budget Alerts** - Get notified at 75%, 90%, 100% of budget limits
- ✅ **Circuit Breakers** - Automatically pause agents when budget exceeded
- ✅ **Provider Cost Comparison** - See which provider is actually cheaper for your workload
- ✅ **Web Dashboard** - Beautiful localhost dashboard with charts and insights
- ✅ **Cost Optimization** - AI-powered recommendations to reduce spending
- ✅ **Multi-Provider Support** - Works with OpenAI, Anthropic, Google, and custom providers
- 🤖 **x402 Agent Payments** - Agents can autonomously pay for Pro tier (0.5 USDT/month)

## Why Cost Governor?

**The ONLY tool that combines cost tracking + agent economy + self-funding.**

| Feature | Cost Governor | ClawWatcher | clawdbot-cost-monitor | AgentPayy | payment-skill |
|---------|--------------|-------------|----------------------|-----------|---------------|
| Cost Tracking | ✅ | ✅ | ✅ | ❌ | ❌ |
| Circuit Breakers | ✅ | ❌ | ❌ | ❌ | ❌ |
| x402 Payments | ✅ | ❌ | ❌ | ✅ | ✅ |
| **Agents Pay for Tool** | ✅ | ❌ | ❌ | ❌ | ❌ |
|...