{"_id":"0xai-openclaw-guardian","_rev":"3-9200bba379898e63b4f521556c841878","name":"0xai-openclaw-guardian","dist-tags":{"latest":"2.0.0-alpha.2"},"versions":{"2.0.0-alpha.0":{"name":"0xai-openclaw-guardian","version":"2.0.0-alpha.0","keywords":["openclaw","observability","cost-tracking","ai-agents","dashboard","monitoring"],"author":{"name":"0xAI-Builders"},"license":"MIT","_id":"0xai-openclaw-guardian@2.0.0-alpha.0","maintainers":[{"name":"0xjesus","email":"pdlgmcn@protonmail.com"}],"homepage":"https://github.com/0xAI-Builders/0xai-openclaw-guardian#readme","bugs":{"url":"https://github.com/0xAI-Builders/0xai-openclaw-guardian/issues"},"bin":{"openclaw-obs":"bin/cli.mjs","openclaw-observability":"bin/cli.mjs"},"dist":{"shasum":"15e6b9d8d95d7727aa536b1f0e7778b6e9033706","tarball":"https://registry.npmjs.org/0xai-openclaw-guardian/-/0xai-openclaw-guardian-2.0.0-alpha.0.tgz","fileCount":15,"integrity":"sha512-HeibV6Bh54FUFDgCMUGH6zf0ywni5faq4GrG82nNMagETuErc/HforY3SyPEI+MKJLkIEF9Z3Th6dORxR4bvDQ==","signatures":[{"sig":"MEYCIQCXRYFwAXPtafKlN7WeUEUbRU5fLpRT5jqEsSYqtQDRDQIhAMhefoRuFbwF0CO1Xwx4SOPURFjJeYvjGewnQ6RsjC7h","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":240453},"main":"src/server.mjs","type":"module","engines":{"node":">=18.0.0"},"gitHead":"8f394e5796782cc0749313e1c878f9e0cff02092","scripts":{"dev":"node src/server.mjs","start":"node src/server.mjs"},"_npmUser":{"name":"0xjesus","email":"pdlgmcn@protonmail.com"},"repository":{"url":"git+https://github.com/0xAI-Builders/0xai-openclaw-guardian.git","type":"git"},"_npmVersion":"10.9.4","description":"Real-time cost tracking, security monitoring, and settings dashboard for OpenClaw AI agent deployments","directories":{},"_nodeVersion":"22.22.1","dependencies":{"noosphere":"*","better-sqlite3":"^11.10.0"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/0xai-openclaw-guardian_2.0.0-alpha.0_1776297857080_0.9886539177898055","host":"s3://npm-registry-packages-npm-production"}},"2.0.0-alpha.1":{"name":"0xai-openclaw-guardian","version":"2.0.0-alpha.1","keywords":["openclaw","observability","cost-tracking","ai-agents","dashboard","monitoring"],"author":{"name":"0xAI-Builders"},"license":"MIT","_id":"0xai-openclaw-guardian@2.0.0-alpha.1","maintainers":[{"name":"0xjesus","email":"pdlgmcn@protonmail.com"}],"homepage":"https://github.com/0xAI-Builders/0xai-openclaw-guardian#readme","bugs":{"url":"https://github.com/0xAI-Builders/0xai-openclaw-guardian/issues"},"bin":{"openclaw-obs":"bin/cli.mjs","openclaw-observability":"bin/cli.mjs"},"dist":{"shasum":"d5e246d287c43716755fab3ebf5b6854db94d0f6","tarball":"https://registry.npmjs.org/0xai-openclaw-guardian/-/0xai-openclaw-guardian-2.0.0-alpha.1.tgz","fileCount":16,"integrity":"sha512-7jMgs3QPNdWTdQCL1tmE8eOUNmouoeWaXAkgaZJI42LnAXYQzaMPp7+qGY/coCRAKAaYddZiPKjNYE80gaF7yQ==","signatures":[{"sig":"MEUCIQCqmddyNfQzYDThx8dwjpwDCh4pi7XsQtDy6Sx3mQ5mgwIgdbauuTlJqoQfbwWFZwlm5fgUi2BjCrnHwj6G0Ze/Mlw=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":248751},"main":"src/server.mjs","type":"module","engines":{"node":">=18.0.0"},"gitHead":"952ef784af01e29f3599adb9dab951c13791d695","scripts":{"dev":"node src/server.mjs","start":"node src/server.mjs"},"_npmUser":{"name":"0xjesus","email":"pdlgmcn@protonmail.com"},"repository":{"url":"git+https://github.com/0xAI-Builders/0xai-openclaw-guardian.git","type":"git"},"_npmVersion":"10.9.4","description":"Real-time cost tracking, security monitoring, and settings dashboard for OpenClaw AI agent deployments","directories":{},"_nodeVersion":"22.22.1","dependencies":{"noosphere":"*","better-sqlite3":"^11.10.0"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/0xai-openclaw-guardian_2.0.0-alpha.1_1776299180673_0.048689055356474054","host":"s3://npm-registry-packages-npm-production"}},"2.0.0-alpha.2":{"name":"0xai-openclaw-guardian","version":"2.0.0-alpha.2","description":"Real-time observability, cost tracking, and kill-switches for OpenClaw AI agent deployments — multi-provider proxy (Anthropic, OpenAI, Google, OpenRouter, Groq, Cerebras, xAI, Ollama, HuggingFace) with a Catppuccin-themed dashboard.","type":"module","main":"src/server.mjs","bin":{"openclaw-obs":"bin/cli.mjs","openclaw-observability":"bin/cli.mjs"},"scripts":{"start":"node bin/cli.mjs","dev":"node bin/cli.mjs","init":"node bin/cli.mjs init","status":"node bin/cli.mjs status"},"keywords":["openclaw","observability","cost-tracking","ai-agents","dashboard","monitoring","billing-proxy","kill-switch","rate-limiting","anthropic","openai","gemini","ollama","claude","llm-observability"],"license":"MIT","engines":{"node":">=18.0.0"},"dependencies":{"better-sqlite3":"^11.10.0","noosphere":"*"},"repository":{"type":"git","url":"git+https://github.com/0xAI-Builders/0xai-openclaw-guardian.git"},"homepage":"https://github.com/0xAI-Builders/0xai-openclaw-guardian#readme","bugs":{"url":"https://github.com/0xAI-Builders/0xai-openclaw-guardian/issues"},"author":{"name":"0xAI-Builders","url":"https://github.com/0xAI-Builders"},"funding":[{"type":"github","url":"https://github.com/sponsors/0xAI-Builders"},{"type":"individual","url":"https://github.com/sponsors/0xjesus"}],"publishConfig":{"access":"public"},"_id":"0xai-openclaw-guardian@2.0.0-alpha.2","gitHead":"01ae4b3dd8740e53e96f65b9121e5f4ae04dd086","_nodeVersion":"22.22.1","_npmVersion":"10.9.4","dist":{"integrity":"sha512-L59bsZJo04EFuTz7lgvOh+Ei3xvl/i1mUAdJEi2S5yhbsAl2RBZMdFLKS3l4C47kBpZUsBir9r5dfoy+0gelzg==","shasum":"6b56848f1513774913fcc15d8edab139a0222864","tarball":"https://registry.npmjs.org/0xai-openclaw-guardian/-/0xai-openclaw-guardian-2.0.0-alpha.2.tgz","fileCount":18,"unpackedSize":254167,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDVr2vvxmI2OrSqhl6O4Cgg/Kq6N8w/N4nqZOQhixvJ+AIhALs6o2l3l3nkwLG8rM6i/AcHHfYoX0OkwsYq8ERHCtWJ"}]},"_npmUser":{"name":"0xjesus","email":"pdlgmcn@protonmail.com"},"directories":{},"maintainers":[{"name":"0xjesus","email":"pdlgmcn@protonmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/0xai-openclaw-guardian_2.0.0-alpha.2_1776309700278_0.682744969180334"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-16T00:04:16.961Z","modified":"2026-04-16T03:21:40.517Z","2.0.0-alpha.0":"2026-04-16T00:04:17.217Z","2.0.0-alpha.1":"2026-04-16T00:26:20.836Z","2.0.0-alpha.2":"2026-04-16T03:21:40.411Z"},"bugs":{"url":"https://github.com/0xAI-Builders/0xai-openclaw-guardian/issues"},"author":{"name":"0xAI-Builders","url":"https://github.com/0xAI-Builders"},"license":"MIT","homepage":"https://github.com/0xAI-Builders/0xai-openclaw-guardian#readme","keywords":["openclaw","observability","cost-tracking","ai-agents","dashboard","monitoring","billing-proxy","kill-switch","rate-limiting","anthropic","openai","gemini","ollama","claude","llm-observability"],"repository":{"type":"git","url":"git+https://github.com/0xAI-Builders/0xai-openclaw-guardian.git"},"description":"Real-time observability, cost tracking, and kill-switches for OpenClaw AI agent deployments — multi-provider proxy (Anthropic, OpenAI, Google, OpenRouter, Groq, Cerebras, xAI, Ollama, HuggingFace) with a Catppuccin-themed dashboard.","maintainers":[{"name":"0xjesus","email":"pdlgmcn@protonmail.com"}],"readme":"# 0xAI OpenClaw Guardian\n\nReal-time observability, **cost tracking**, **kill-switches** and configuration dashboard for [OpenClaw](https://openclaw.ai) AI agent deployments.\n\n[![npm version](https://img.shields.io/npm/v/0xai-openclaw-guardian.svg?style=flat-square&color=fab387)](https://www.npmjs.com/package/0xai-openclaw-guardian)\n[![npm downloads](https://img.shields.io/npm/dm/0xai-openclaw-guardian.svg?style=flat-square&color=a6e3a1)](https://www.npmjs.com/package/0xai-openclaw-guardian)\n[![license](https://img.shields.io/npm/l/0xai-openclaw-guardian.svg?style=flat-square&color=89b4fa)](./LICENSE)\n[![Node](https://img.shields.io/node/v/0xai-openclaw-guardian.svg?style=flat-square&color=cba6f7)](https://nodejs.org)\n[![GitHub Sponsors](https://img.shields.io/badge/sponsor-0xAI--Builders-f38ba8.svg?style=flat-square&logo=github-sponsors)](https://github.com/sponsors/0xAI-Builders)\n[![Buy Me a Coffee](https://img.shields.io/badge/buy%20me%20a%20coffee-0xjesus-yellow.svg?style=flat-square&logo=buymeacoffee)](https://buymeacoffee.com/0xjesus)\n\n- 🔍 Intercepts **every AI call** from OpenClaw to any provider (Anthropic, OpenAI, Google, OpenRouter, Groq, Cerebras, xAI, Ollama, HuggingFace)\n- 💰 Real per-call cost calculation via **noosphere** pricing catalog (45+ models, auto-synced)\n- 🛡 **Kill-switches**: USD caps (daily/weekly/monthly), per-agent/per-model caps, rate limits for zero-cost providers (ollama), loop detector, emergency pause\n- 📊 Dashboard at `http://localhost:3847` with tabs: **Spend · Calls · Crons · Limits · Settings · Security**\n- 🔗 Stateful: SQLite-backed `calls.db` for live queries and aggregations\n- 🪙 Subscription-aware: shows **SUB vs API** per call, always prints the API-equivalent cost (even for Claude Max)\n\n![Dashboard — Spend tab](docs/dashboard-spend.png)\n\n> 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.\n\n---\n\n## Install\n\nZero setup if you just want to run it:\n\n```bash\n# Global CLI\nnpm install -g openclaw-observability\nopenclaw-obs\n\n# Or without install\nnpx openclaw-observability\n```\n\nThen open **http://localhost:3847** in your browser.\n\nThe proxy starts automatically on `http://127.0.0.1:18801` the first time it detects Claude credentials at `~/.claude/.credentials.json`.\n\n---\n\n## Wire it into OpenClaw\n\nEdit `~/.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.\n\n```json\n{\n  \"models\": {\n    \"providers\": {\n      \"anthropic\": { \"baseUrl\": \"http://127.0.0.1:18801\" },\n      \"openai\":    { \"baseUrl\": \"http://127.0.0.1:18801/openai/v1\" },\n      \"google\":    { \"baseUrl\": \"http://127.0.0.1:18801/google\" },\n      \"openrouter\":{ \"baseUrl\": \"http://127.0.0.1:18801/openrouter/v1\" },\n      \"groq\":      { \"baseUrl\": \"http://127.0.0.1:18801/groq/openai/v1\" },\n      \"cerebras\":  { \"baseUrl\": \"http://127.0.0.1:18801/cerebras/v1\" },\n      \"xai\":       { \"baseUrl\": \"http://127.0.0.1:18801/xai/v1\" },\n      \"ollama\":    { \"baseUrl\": \"http://127.0.0.1:18801/ollama\", \"api\": \"ollama\" }\n    }\n  }\n}\n```\n\nRestart the OpenClaw gateway so the new `baseUrl`s take effect.\n\n---\n\n## Environment variables\n\nAll optional.\n\n| Variable | Default | Description |\n|---|---|---|\n| `OPENCLAW_DIR` | `~/.openclaw` | Path to your OpenClaw directory |\n| `OBS_PORT` | `3847` | Dashboard server port |\n| `OBS_HOST` | `0.0.0.0` | Bind address |\n| `OBS_LIMITS_FILE` | `$OPENCLAW_DIR/observability/limits.json` | Spend + rate limit config |\n| `OBS_BILLING_PROXY_AUTOSTART` | `1` | Start the proxy on boot when Claude creds are present |\n| `OBS_BILLING_PROXY_PORT` | `18801` | Proxy port (all providers multiplex here) |\n| `OBS_BILLING_PROXY_HOST` | `127.0.0.1` | Proxy bind address |\n\n---\n\n## Dashboard tabs\n\n### 💸 Spend\nHistorical spend aggregated by agent / model / source / day / cron. Reads from session JSONL files. Works even for subscription calls (API-equivalent cost is always computed).\n\n### 📋 Calls\nEvery single call captured by the proxy, live. Filters: provider, model, billing mode (SUB/API). Columns:\n\n| Col | Meaning |\n|---|---|\n| Time | local timestamp |\n| Provider / Model | who served the call |\n| Agent | derived from request body / openclaw.json whitelist |\n| Query | last user message (tooltip has full text) |\n| In / Out / Cache / Total | token counts |\n| Cost / $/1k | API-equivalent USD |\n| Lat | round-trip latency |\n| Billing | **SUB** (subscription plan) or **API** (pay-per-token) |\n\n### ⏰ Crons\nList every OpenClaw cron with schedule, agent, last-run status, consecutive errors. Enable/disable or **permanently delete** any cron from the UI.\n\n### 🛡 Limits — Kill-switches\nEdit `~/.openclaw/observability/limits.json` with a form. Proxy hot-reloads on mtime change.\n\n- **Emergency pause** — single-click kill-switch. Auto-saves immediately. Sticks a red banner across the dashboard while active.\n- **Global USD caps** — daily / weekly / monthly. Blocks upstream requests with HTTP 429 when exceeded. Does NOT trigger for zero-cost providers (see next).\n- **Rate + token caps** per provider — required for Ollama / local inference. Supports `callsPerMinute`, `callsPerHour`, `callsPerDay`, `tokensPerDay`.\n- **Loop detector** — if any single session makes more than N calls in X seconds, further calls are auto-blocked.\n\nExample `limits.json`:\n\n```json\n{\n  \"enabled\": true,\n  \"paused\": false,\n  \"global\": { \"dailyUsd\": 10, \"weeklyUsd\": 50, \"monthlyUsd\": 200 },\n  \"perAgent\":  { \"anhelo\": { \"dailyUsd\": 3 } },\n  \"perModel\":  { \"claude-opus-4-6\": { \"dailyUsd\": 5 } },\n  \"rateLimits\": {\n    \"perProvider\": {\n      \"ollama\": { \"callsPerMinute\": 120, \"callsPerHour\": 2000, \"tokensPerDay\": 50000000 }\n    }\n  },\n  \"loopDetector\": { \"enabled\": true, \"windowSec\": 60, \"maxCalls\": 30 }\n}\n```\n\n### ⚙️ Settings\nSelect each agent's model. Toggle crons. Inspect provider connectivity.\n\n### 🔐 Security\nAudit: exposed secrets in config files, file permissions, encryption status.\n\n---\n\n## REST API\n\nAll endpoints are local, no auth needed (bind to loopback by default).\n\n| Method | Path | Purpose |\n|---|---|---|\n| GET | `/api/dashboard` | Spend aggregate for range/filters |\n| GET | `/api/calls?from&to&provider&agent_id&model&limit&offset` | Paginated call log |\n| GET | `/api/calls/aggregate?by=provider|model|agent_id` | Roll-up stats |\n| GET | `/api/limits` | Current limits + spend snapshot |\n| POST | `/api/limits` | Atomic write to `limits.json` |\n| GET | `/api/crons` | List every cron, enabled or not |\n| POST | `/api/crons/:id/toggle` | `{enable:true|false}` |\n| DELETE | `/api/crons/:id` | Permanent delete |\n| GET | `/api/billing-proxy` | Proxy health + guard snapshot |\n| GET | `/api/security` | Security audit |\n\n---\n\n## Deep-linkable URLs\n\nEvery tab and section has a hash slug. Hover any heading to reveal a 🔗 icon — click to copy a shareable URL.\n\n```\n#spend\n#calls              #calls/filters\n#crons\n#limits             #limits/caps       #limits/loop        #limits/rates\n#settings\n#security\n```\n\n---\n\n## Kill-switch codes\n\nWhen the proxy blocks a request it returns HTTP 429 with a structured payload. Useful for debugging and alerting:\n\n| Code | Trigger |\n|---|---|\n| `paused` | Emergency switch is ON |\n| `global_daily_cap` · `global_weekly_cap` · `global_monthly_cap` | Global USD cap reached |\n| `agent_daily_cap` · `model_daily_cap` · `provider_daily_cap` | Per-dimension USD cap |\n| `loop_detected` | Session fired too many calls too fast |\n| `provider_rpm_cap` · `provider_rph_cap` · `provider_rpd_cap` | Rate-limit for zero-cost provider |\n| `provider_tpd_cap` · `agent_id_tpd_cap` · `model_tpd_cap` | Token-budget cap |\n\n---\n\n## How costs are computed\n\n- Pricing table comes from [noosphere](https://www.npmjs.com/package/noosphere) (`@mariozechner/pi-ai` generated catalog, ~45 models) plus a small fallback table.\n- 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.\n- Google uses the double-counting-safe formula: `uncached = input − cacheRead`.\n- Ollama / local inference is always priced at $0. Those providers are protected by rate limits instead.\n\n---\n\n## Hooks (optional, for auto-launch)\n\nCopy the 3 hook handlers into your OpenClaw hooks directory to automate startup and spend enforcement:\n\n```bash\nmkdir -p ~/.openclaw/hooks/{observability,spend-guard,model-guard}\ncp node_modules/openclaw-observability/hooks/observability/handler.ts ~/.openclaw/hooks/observability/\ncp node_modules/openclaw-observability/hooks/spend-guard/handler.ts   ~/.openclaw/hooks/spend-guard/\ncp node_modules/openclaw-observability/hooks/model-guard/handler.ts   ~/.openclaw/hooks/model-guard/\n```\n\n| Hook | Trigger | Effect |\n|---|---|---|\n| **observability** | Gateway startup | Launches the dashboard server |\n| **spend-guard** | Before each agent turn | Rejects the call if caps are breached |\n| **model-guard** | Before each agent turn | Prevents drift to more expensive models |\n\n---\n\n## Security notes\n\n- The proxy binds to loopback (`127.0.0.1`) by default. Do **not** expose it publicly — it relays OAuth tokens.\n- `~/.claude/.credentials.json` is read in-memory; never logged or echoed.\n- `limits.json` and `calls.db` live inside `~/.openclaw/observability/`. The repo `.gitignore` excludes every user-specific directory.\n- Run `git log -p` against this repo to verify: zero secrets committed.\n\n---\n\n## Development\n\n```bash\ngit clone https://github.com/<your-org>/openclaw-observability\ncd openclaw-observability\nnpm install\nnode bin/cli.mjs\n```\n\nSource layout:\n\n```\nsrc/\n├── server.mjs           # Dashboard HTTP + REST API\n├── billing-proxy.mjs    # Anthropic proxy (OAuth rewriting)\n├── multi-provider.mjs   # Generic router for OpenAI/Google/Ollama/etc\n├── usage-parser.mjs     # Per-provider token extractor\n├── logger.mjs           # SQLite call log (better-sqlite3, JSONL fallback)\n├── guards.mjs           # Kill-switch evaluator (caps + rate + loop detector)\n├── pricing.mjs          # noosphere-backed cost calculator\n└── dashboard.html       # Single-file SPA, Tailwind + vanilla JS\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md"}