2.0.0-alpha.0

0xAI OpenClaw Guardian

Real-time observability, cost tracking, kill-switches and configuration dashboard for OpenClaw AI agent deployments.

• 🔍 Intercepts every AI call from OpenClaw to any provider (Anthropic, OpenAI, Google, OpenRouter, Groq, Cerebras, xAI, Ollama, HuggingFace)
• 💰 Real per-call cost calculation via noosphere pricing catalog (45+ models, auto-synced)
• 🛡 Kill-switches: USD caps (daily/weekly/monthly), per-agent/per-model caps, rate limits for zero-cost providers (ollama), loop detector, emergency pause
• 📊 Dashboard at http://localhost:3847 with tabs: Spend · Calls · Crons · Limits · Settings · Security
• 🔗 Stateful: SQLite-backed calls.db for live queries and aggregations
• 🪙 Subscription-aware: shows SUB vs API per call, always prints the API-equivalent cost (even for Claude Max)

Real-time spend breakdown by agent, model, and source. API-equivalent cost is displayed even for subscription (Claude Max) calls, so you always see the economic value consumed.

---

Install

Zero setup if you just want to run it:

# Global CLI
npm install -g openclaw-observability
openclaw-obs

# Or without install
npx openclaw-observability

Then open http://localhost:3847 in your browser.

The proxy starts automatically on http://127.0.0.1:18801 the first time it detects Claude credentials at ~/.claude/.credentials.json.

---

Wire it into OpenClaw

Edit ~/.openclaw/openclaw.json so each provider's baseUrl points at the local proxy. That makes every call route through observability, pricing, kill-switches, and the logger.

{
  "models": {
    "providers": {
      "anthropic": { "baseUrl": "http://127.0.0.1:18801" },
      "openai":    { "baseUrl": "http://127.0.0.1:18801/openai/v1" },
      "google":    { "baseUrl": "http://127.0.0.1:18801/google" },
      "openrouter":{ "baseUrl": "http://127.0.0.1:18801/openrouter/v1" },
      "groq":      { "baseUrl": "http://127.0.0.1:18801/groq/openai/v1" },
      "cerebras":  { "baseUrl": "http://127.0.0.1:18801/cerebras/v1" },
      "xai":       { "baseUrl": "http://127.0.0.1:18801/xai/v1" },
      "ollama":    { "baseUrl": "http://127.0.0.1:18801/ollama", "api": "ollama" }
    }
  }
}

Restart the OpenClaw gateway so the new baseUrls take effect.

---

Environment variables

All optional.

---

Dashboard tabs

💸 Spend

Historical spend aggregated by agent / model / source / day / cron. Reads from session JSONL files. Works even for subscription calls (API-equivalent cost is always computed).

📋 Calls

Every single call captured by the proxy, live. Filters: provider, model, billing mode (SUB/API). Columns:

⏰ Crons

List every OpenClaw cron with schedule, agent, last-run status, consecutive errors. Enable/disable or permanently delete any cron from the UI.

🛡 Limits — Kill-switches

Edit ~/.openclaw/observability/limits.json with a form. Proxy hot-reloads on mtime change.

• Emergency pause — single-click kill-switch. Auto-saves immediately. Sticks a red banner across the dashboard while active.
• Global USD caps — daily / weekly / monthly. Blocks upstream requests with HTTP 429 when exceeded. Does NOT trigger for zero-cost providers (see next).
• Rate + token caps per provider — required for Ollama / local inference. Supports callsPerMinute, callsPerHour, callsPerDay, tokensPerDay.
• Loop detector — if any single session makes more than N calls in X seconds, further calls are auto-blocked.

Example limits.json:

{
  "enabled": true,
  "paused": false,
  "global": { "dailyUsd": 10, "weeklyUsd": 50, "monthlyUsd": 200 },
  "perAgent":  { "anhelo": { "dailyUsd": 3 } },
  "perModel":  { "claude-opus-4-6": { "dailyUsd": 5 } },
  "rateLimits": {
    "perProvider": {
      "ollama": { "callsPerMinute": 120, "callsPerHour": 2000, "tokensPerDay": 50000000 }
    }
  },
  "loopDetector": { "enabled": true, "windowSec": 60, "maxCalls": 30 }
}

⚙️ Settings

Select each agent's model. Toggle crons. Inspect provider connectivity.

🔐 Security

Audit: exposed secrets in config files, file permissions, encryption status.

---

REST API

All endpoints are local, no auth needed (bind to loopback by default).

---

Deep-linkable URLs

Every tab and section has a hash slug. Hover any heading to reveal a 🔗 icon — click to copy a shareable URL.

#spend
#calls              #calls/filters
#crons
#limits             #limits/caps       #limits/loop        #limits/rates
#settings
#security

---

Kill-switch codes

When the proxy blocks a request it returns HTTP 429 with a structured payload. Useful for debugging and alerting:

---

How costs are computed

• Pricing table comes from noosphere (@mariozechner/pi-ai generated catalog, ~45 models) plus a small fallback table.
• For subscription calls (e.g. Claude Max) the proxy still prices at API rates, so the dashboard shows the economic value consumed even though nothing is charged.
• Google uses the double-counting-safe formula: uncached = input − cacheRead.
• Ollama / local inference is always priced at $0. Those providers are protected by rate limits instead.

---

Hooks (optional, for auto-launch)

Copy the 3 hook handlers into your OpenClaw hooks directory to automate startup and spend enforcement:

mkdir -p ~/.openclaw/hooks/{observability,spend-guard,model-guard}
cp node_modules/openclaw-observability/hooks/observability/handler.ts ~/.openclaw/hooks/observability/
cp node_modules/openclaw-observability/hooks/spend-guard/handler.ts   ~/.openclaw/hooks/spend-guard/
cp node_modules/openclaw-observability/hooks/model-guard/handler.ts   ~/.openclaw/hooks/model-guard/

---

Security notes

• The proxy binds to loopback (127.0.0.1) by default. Do not expose it publicly — it relays OAuth tokens.
• ~/.claude/.credentials.json is read in-memory; never logged or echoed.
• limits.json and calls.db live inside ~/.openclaw/observability/. The repo .gitignore excludes every user-specific directory.
• Run git log -p against this repo to verify: zero secrets committed.

---

Development

git clone https://github.com/<your-org>/openclaw-observability
cd openclaw-observability
npm install
node bin/cli.mjs

Source layout:

src/
├── server.mjs           # Dashboard HTTP + REST API
├── billing-proxy.mjs    # Anthropic proxy (OAuth rewriting)
├── multi-provider.mjs   # Generic router for OpenAI/Google/Ollama/etc
├── usage-parser.mjs     # Per-provider token extractor
├── logger.mjs           # SQLite call log (better-sqlite3, JSONL fallback)
├── guards.mjs           # Kill-switch evaluator (caps + rate + loop detector)
├── pricing.mjs          # noosphere-backed cost calculator
└── dashboard.html       # Single-file SPA, Tailwind + vanilla JS

License

MIT