# ClawButler — Full Documentation

> OpenClaw Agent governance platform — monitor, approve, and control with full audit trails. The management layer for your OpenClaw Agent ecosystem. Leverages MCP (tool/data connection) and A2A (agent-to-agent interop) protocols as the standards layer.

---

## What is ClawButler?

Organizations running OpenClaw Agents face a growing governance gap: agents run 24/7, costs grow without visibility, high-risk operations execute without review, and there is no unified audit trail. As the number of OpenClaw Agents scales, operators lose control.

ClawButler is the governance layer that bridges this gap. It connects to your OpenClaw instance via secure WebSocket connectors, auto-discovers agents through MCP protocol, and provides a single pane of glass for identity management, real-time monitoring, cost attribution, human-in-the-loop approvals, and immutable audit trails — without replacing your agent builder.

Built on open standards — MCP (Model Context Protocol) for tool and data connections, A2A for agent-to-agent interop — ClawButler is fully open-source. Self-host on your own infrastructure for complete data sovereignty, or use the managed cloud service.

---

## Core Concepts

### Agent Registry
A unified identity layer where OpenClaw Agents are registered, discovered, and managed. Supports 18 management endpoints including enable/disable toggle, structured configuration across 6 tabs (overview, tools, skills, channels, files, cron), and real-time health tracking.

### MCP Protocol
Model Context Protocol standardizes how agents discover and connect to external tools and data sources — databases, APIs, file systems — with unified authentication and access control.

### A2A Interop
Agent-to-Agent protocol enables collaboration, allowing agents to delegate tasks and share context with proper authorization and audit trails.

### HITL Approvals
Human-in-the-loop workflows intercept high-risk operations before execution. Configurable rules with risk-level assessment, cost estimation, and batch processing — approve once or allow-always for trusted patterns.

### Audit Trail
Append-only event log with monotonic sequence IDs captures every agent action. Trace linking connects related operations across agents, and PII masking ensures compliance while maintaining accountability.

---

## Features

### Governance & Compliance

#### Unified Governance
Register your OpenClaw instance via secure WebSocket connectors and auto-discover all agents in a unified registry. 18 management endpoints provide enable/disable, structured config across 6 tabs (overview, tools, skills, channels, files, cron), and one-click connector diagnostics.

#### HITL Approvals
Intercept high-risk Agent operations with configurable approval rules. Each request includes risk level, cost estimate, and impact assessment. Support for batch approve/reject, allow-once vs allow-always decisions, and optimistic concurrency on rule updates — all with full audit trail.

#### Audit & Compliance
Multi-dimensional search across all audit events: filter by agent, event type, risk level, trace ID, keyword, and date range. Trace chain linking reconstructs full operation histories. Config rollback with preview, and automatic PII masking on sensitive fields.

#### Config Safety V2.0 — Two-Layer Protection

**Layer 1: Per-Agent Config Rollback** — Every Agent config change (manual or AI-assisted) automatically creates an immutable snapshot with monotonically increasing version numbers. Scoped to agent_config, workspace_bundle, bindings, or dependency_meta. Features:
- Semantic diff shows changes categorized by identity, model, tools, skills, bindings, etc.
- Dry-run rollback preview shows impact before executing
- Save-before-restore: current live config is automatically saved as a checkpoint before any rollback
- Risk classification: critical (permissions/secrets) requires approval; high/medium executes directly
- Drift detection flags divergence between live OpenClaw state and latest snapshot
- Rollback syncs changes back to OpenClaw gateway via `config.set()` RPC

**Layer 2: Gateway-Level Backup & Restore (Connector Artifacts)** — Encrypted `.cbpkg` backup packages capture the entire OpenClaw gateway configuration:
- Global sections: model defaults, agent defaults, approval rules, channels, cron jobs
- Per-agent: identity, model, tools, skills, channels, runtime, workspace files
- Three intents: backup (all secrets encrypted), clone (portable), share (publishable)
- Three restore strategies: merge (additive), replace_scope (selective), exact_restore (full reset)
- Preview import changes before applying
- Auto-creates checkpoint artifact after successful restore for further rollback
- AES-256-GCM encryption with scrypt KDF for backup security

#### Common Troubleshooting: Config Recovery

**Scenario: AI assistant or manual edit broke a single Agent's config**
1. Go to Agent detail → Config History tab (or `clawbutler connector artifact list <connector-id>` via CLI)
2. Find the last known-good version in the snapshot list
3. Click "Preview Rollback" to see what will change
4. Execute rollback — current state is auto-saved first, so you can undo the undo

**Scenario: Global config change broke all Agents (e.g., changed agents.defaults)**
1. Go to Connector detail → Artifacts tab
2. If you have a previous backup artifact, click "Import" with `replace_scope` or `exact_restore` strategy
3. Preview the changes, confirm, and execute
4. If no backup exists: export a backup NOW for future recovery, then manually fix the config

**Scenario: Not sure what changed — drift detection**
1. Go to Agent detail → Config History → click "Drift Check"
2. ClawButler compares live OpenClaw config vs latest snapshot
3. Shows exactly which fields drifted and suggests a recovery target version

#### Kill Switch
Emergency agent shutdown that disables locally and propagates to OpenClaw. Three-state health monitoring (healthy/degraded/offline) with 30-second offline detection. Recovery requires explicit confirmation to prevent accidental restarts.

### Operations & Insights

#### Real-Time Activity
Live Server-Sent Events (SSE) streaming with 15-second heartbeat and cursor-based resume via Last-Event-ID. Filter by agent, event type, risk level, and time range. Daily summary digests and long-running task progress tracking keep you informed.

#### Cost Tracking & Budget
Per-agent cost attribution with breakdown by model and task type. Configurable trend analysis (daily/weekly/monthly), anomaly rate alerts, and budget circuit-breakers that automatically enforce spending limits. Model routing optimizer suggests cost-saving alternatives with explainable risk assessment.

#### Cron Scheduling
Schedule recurring agent tasks with full CRUD synced to the upstream platform. Run history with pagination, consecutive failure detection with alerts, and aggregated cron summary statistics across all agents.

#### Intelligence Analytics
Cost root cause analysis with contribution trees, per-agent reliability scoring, and value quantification.

#### Report Generation
Scheduled reports with email delivery subscriptions. On-demand generation, retry for failed deliveries, and anomaly highlights.

### Templates & Automation

#### Verified Templates V2.5
Template registry with type-safe variable definitions (string / number / boolean / json), pre-deploy preview of config changes, workspace files, and dependency impact. Post-deploy checks with severity levels run automatically. Compatibility matrix declares OpenClaw version and model capability requirements.

#### Runbooks V3
Multi-step operational automation centered on the OpenClaw-native path. Typed steps support approval gates, verification, and evidence capture, with full run lifecycle management, state machine validation, event timeline, and audit trail. Supports manual, scheduled, and rule-based triggers.

#### Agent Scorecard (ARS v2.5)
Agent Reliability Scoring — per-agent evaluation snapshots with reliability, quality, and cost metrics. Session breakdown tracks lifecycle states (idle, active, degraded, critical). Resource Groups provide grouping and routing aggregation. Full quad-platform coverage: Web detail tab, Mobile screen, MCP agent summary tool, CLI summary helpers.

#### Runtime Host Intake
Pair a machine, discover Hermes / Claude Code / Codex / OpenClaw instances, batch-add only the connectors you want, and sync attach-mode sessions into the control plane. OpenClaw remains the fullest provider-native governance path.

### Integrations & Extensions

- **Web Push Notifications**: In-app notifications with Web Push delivery via VAPID. Subscription management with quiet hours, per-channel preferences, and cooldown controls.
- **Data Export**: Background CSV/PDF export with secure, expiring download tokens and automatic retry.
- **Runtime Hosts**: Discovery, connector intake, and attach-mode session projection for Hermes / Claude Code / Codex / OpenClaw runtimes.
- **Authentication**: Email/password, GitHub OAuth, and Google OAuth. Device flow for CLI with org-aware capability resolution.

---

## Architecture Overview

### System Architecture

```
┌─────────────────────────────────────────────┐
│              ClawButler Stack              │
│                                              │
│   ┌─────────────┐    ┌─────────────────┐    │
│   │   Web (FE)   │    │   API (BE)       │    │
│   │  Next.js 15  │    │  FastAPI 0.115   │    │
│   │  Port: 3000  │    │  Port: 8000      │    │
│   └──────┬───────┘    └──────┬──────────┘    │
│          │                    │               │
│   ┌──────┴────────────────────┴──────────┐   │
│   │         PostgreSQL 17 + Valkey 8      │   │
│   └───────────────────────────────────────┘   │
│                                              │
│   ┌──────────────────────────────────────┐   │
│   │     Caddy (Reverse Proxy + HTTPS)     │   │
│   └──────────────────────────────────────┘   │
└─────────────────────────────────────────────┘
```

### Tech Stack

| Layer     | Stack                                                        |
|-----------|--------------------------------------------------------------|
| Web       | Next.js 15 (App Router, standalone) + React 19 + Tailwind 4 + Auth.js v5 |
| API       | FastAPI + Python 3.12 + SQLAlchemy 2 (async) + Alembic + structlog |
| Database  | PostgreSQL 17 + Valkey 8 (Redis-compatible)                  |
| CI        | GitHub Actions (lint / typecheck / test / build)             |
| Deploy    | Docker Compose + Caddy reverse proxy (auto HTTPS)            |

### Repository Structure

```
├── apps/
│   ├── api/              # FastAPI backend (Python 3.12, uv)
│   │   ├── routers/      # 53 API routers, 200+ endpoints
│   │   ├── services/     # 68 business logic services
│   │   ├── models/       # SQLAlchemy models (54 tables)
│   │   ├── schemas/      # Pydantic schemas
│   │   ├── migrations/   # 55 Alembic migrations
│   │   ├── tests/        # 111 test files
│   │   └── Dockerfile
│   └── web/              # Next.js frontend (Node 22, pnpm)
│       ├── src/app/      # App Router pages
│       ├── src/i18n/     # zh-CN / en-US
│       ├── scripts/      # UI gate checks
│       └── Dockerfile
├── deploy/               # Deployment config
│   ├── deploy.sh         # One-click deploy
│   ├── rollback.sh       # One-click rollback
│   ├── docker-compose.production.yml  # Production port bindings
│   └── .env.production   # Production env template
├── docker-compose.yml    # Full stack orchestration
└── .github/workflows/    # CI pipeline
```

---

## Self-Hosted Deployment Guide

### System Requirements

| Resource | Minimum    | Recommended  |
|----------|-----------|--------------|
| CPU      | 2 vCPU    | 4 vCPU       |
| RAM      | 4 GB      | 8 GB         |
| Disk     | 20 GB SSD | 40 GB SSD    |
| OS       | Ubuntu 22.04+ / Debian 12+ | Ubuntu 24.04 LTS |

### Prerequisites

- Docker Engine 24+ and Docker Compose v2
- A domain name with DNS A record pointing to your server
- (Optional) SMTP server for email features
- (Optional) GitHub OAuth app for social login

### Quick Start (5 Minutes)

```bash
# 1. Clone the repository
git clone https://github.com/Octo-o-o-o/clawbutler.git
cd clawbutler

# 2. Generate secrets and create .env
cp deploy/.env.production .env
bash scripts/generate-secrets.sh >> .env
nano .env  # Fill in your domain, SMTP, etc.

# 3. Deploy (database migrations run automatically on first boot)
docker compose up -d --build

# 4. Verify
until curl -sf http://localhost:8000/health > /dev/null 2>&1; do sleep 2; done
echo "ClawButler is ready!"

# Web UI:  http://localhost:3000
# API docs: http://localhost:8000/docs
```

### Required Configuration (.env)

| Variable            | Description                        | Example                              |
|--------------------|------------------------------------|--------------------------------------|
| DB_PASSWORD         | PostgreSQL password                | (auto-generated)                     |
| JWT_SECRET_KEY      | API JWT signing key                | (auto-generated)                     |
| AUTH_SECRET          | NextAuth.js session secret         | (auto-generated)                     |
| ENCRYPTION_KEY      | Field-level encryption key         | (auto-generated)                     |
| CORS_ORIGINS        | Allowed origins for CORS           | https://your-domain.com              |
| AUTH_URL            | NextAuth.js canonical URL          | https://your-domain.com              |
| NEXT_PUBLIC_API_BASE_URL | Public API URL for frontend   | https://your-domain.com/api          |

### Optional Configuration

| Variable            | Description                        | Required For              |
|--------------------|------------------------------------|---------------------------|
| SMTP_HOST           | SMTP server hostname               | Email notifications       |
| SMTP_PORT           | SMTP port (587 for TLS)            | Email notifications       |
| SMTP_USER           | SMTP username                      | Email notifications       |
| SMTP_PASSWORD       | SMTP password                      | Email notifications       |
| SMTP_FROM_EMAIL     | Sender email address               | Email notifications       |
| AUTH_GITHUB_ID      | GitHub OAuth App Client ID         | GitHub login              |
| AUTH_GITHUB_SECRET  | GitHub OAuth App Client Secret     | GitHub login              |
| SENTRY_DSN          | Sentry error tracking DSN          | Error monitoring          |
| STRIPE_WEBHOOK_SECRET | Stripe webhook signing secret    | Payment processing        |

### Production HTTPS with Caddy

Create a `Caddyfile`:

```caddyfile
your-domain.com {
    handle /api/auth/* { reverse_proxy localhost:3000 }
    handle /api/events/* { reverse_proxy localhost:3000 }
    handle /api/*      { reverse_proxy localhost:8000 }
    handle /health     { reverse_proxy localhost:8000 }
    handle /docs       { reverse_proxy localhost:8000 }
    handle             { reverse_proxy localhost:3000 }
}
```

Install and start Caddy:

```bash
sudo apt install -y caddy
sudo cp Caddyfile /etc/caddy/Caddyfile
sudo systemctl restart caddy
```

### Upgrade Process

```bash
cd ~/clawbutler
git pull origin main
docker compose up -d --build
# Database migrations run automatically on container start
```

### Backup

```bash
docker compose exec postgres pg_dump -U postgres agentplanet > backup_$(date +%Y%m%d).sql
```

### Rollback

```bash
bash deploy/rollback.sh <git-commit-sha>
```

---

## How It Works

### Step 1: Connect
Connect your OpenClaw instance through secure WebSocket connectors. ClawButler auto-discovers all agents via MCP protocol and registers them in a unified identity layer — no manual setup required.

### Step 2: Monitor
Track every agent action through live SSE streaming, multi-dimensional cost analytics, and three-state health monitoring. Daily summaries and anomaly alerts surface issues before they escalate.

### Step 3: Govern
Set approval rules for high-risk operations, configure budget circuit-breakers with threshold alerts, and schedule compliance reports. Every decision is logged in an immutable audit trail.

---

## API Reference

The API is built with FastAPI and provides automatic OpenAPI documentation with 200+ endpoints across 53 routers.

- **Interactive Docs**: `https://your-domain.com/api/docs` (Swagger UI)
- **OpenAPI Spec**: `https://your-domain.com/api/openapi.json`
- **Health Check**: `GET /health`

### Authentication

All API requests require a JWT Bearer token:

```
Authorization: Bearer <jwt-token>
```

### Key API Endpoint Categories

| Category | Router | Key Endpoints |
|----------|--------|---------------|
| Auth | `/api/v1/auth` | register, login, refresh, reset-password |
| Agents | `/api/v1/agents` | CRUD, config, enable/disable, health |
| Connectors | `/api/v1/connectors` | create, test, sync |
| Dashboard | `/api/v1/dashboard` | overview, summary |
| Activity | `/api/v1/activity` | events, daily-summary |
| Approvals | `/api/v1/approvals` | list, approve, reject, batch, rules |
| Cost | `/api/v1/cost` | summary, by-agent, trends, anomalies |
| Audit | `/api/v1/audit` | search, detail, trace-chain |
| Cron | `/api/v1/cron` | jobs, runs, create/update/delete |
| Config | `/api/v1/agents` | versions, diff, rollback, drift-check |
| Budget | `/api/v1/budgets` | create, update, reset, enforce |
| Kill Switch | `/api/v1/kill-switch` | disable, recover |
| Intelligence | `/api/v1/intelligence` | root-cause, advice, reliability, value |
| Memory | `/api/v1/memory` | search, edit, history |
| Notifications | `/api/v1/notifications` | list, read, subscribe, preferences |
| Reports | `/api/v1/reports` | list, generate, subscribe |
| Templates | `/api/v1/templates` | list, preview, import, deploy |
| Runbooks | `/api/v1/runbooks` | CRUD, versions, trigger, runs, events |
| Export | `/api/v1/exports` | create, download, status |
| Runtime Hosts | `/api/v1/runtime-hosts` | pair, discover, batch-add, session sync |

---

## Development Setup

### Backend (API)

```bash
cp .env.example apps/api/.env
(cd apps/api && uv python install 3.12 && uv sync --all-extras && uv run alembic upgrade head)
(cd apps/api && uv run pytest tests/ -q && uv run ruff check .)
(cd apps && uv run --project api uvicorn api.main:app --reload --host 0.0.0.0 --port 8000)
```

### Frontend (Web)

```bash
cd apps/web
corepack enable && pnpm install
pnpm dev
pnpm lint && pnpm typecheck && pnpm build
```

### Local Infrastructure

```bash
docker compose -f deploy/docker-compose.dev.yml up -d
```

---

## Internationalization

Two languages supported:
- **Chinese (zh-CN)**: Primary language
- **English (en-US)**: Full translation

Language files: `apps/web/src/i18n/{zh-CN,en-US}.json`

---

## License

ClawButler is open-source software. See the repository for license details.

## Links

- Website: https://clawbutler.cc
- GitHub: https://github.com/Octo-o-o-o/clawbutler
- Documentation: https://clawbutler.cc/docs
- Features: https://clawbutler.cc/docs/features
- Self-Host Guide: https://clawbutler.cc/docs/self-host
- Ecosystem: https://clawbutler.cc/docs/ecosystem
- Compare Plans: https://clawbutler.cc/docs/compare