Metadata-Version: 2.4
Name: easyclaw
Version: 0.2.1
Summary: Autonomous doctor and personal trainer for OpenClaw agents
Project-URL: Homepage, https://easyclaw.help
Project-URL: Documentation, https://easyclaw.help/docs
Project-URL: Repository, https://github.com/slickrick74/easyclaw
Project-URL: Issues, https://github.com/slickrick74/easyclaw/issues
Project-URL: Changelog, https://github.com/slickrick74/easyclaw/blob/main/CHANGELOG.md
Author: EasyClaw Team
License-Expression: LicenseRef-Proprietary
Keywords: agent,ai,autonomous,devops,monitoring,openclaw,self-healing,sidecar
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.10
Requires-Dist: aiofiles>=24.1.0
Requires-Dist: psutil>=5.9
Requires-Dist: python-telegram-bot>=21.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# EasyClaw

Autonomous doctor and personal trainer for [OpenClaw](https://openclaw.dev) agents.

EasyClaw is a lightweight sidecar daemon that monitors, diagnoses, self-heals, and optimizes OpenClaw instances — without user intervention. It runs alongside your OpenClaw agent and keeps it healthy 24/7.

## Features

- **Auto-Discovery** — detects your OpenClaw installation, config, logs, and running process automatically
- **Log Monitoring** — tails OpenClaw logs in real-time, classifies errors against 17 built-in patterns
- **Self-Healing** — 16 built-in remediations for common failures (OOM, crashes, stale locks, DNS, rate limits, post-update issues)
- **AI Agent Brain** — LLM-powered reasoning via OpenRouter (GLM-4.7-Flash) with tool calling for complex diagnostics
- **Circuit Breaker** — prevents restart loops with configurable thresholds
- **MCP Knowledge Base** — queries a cloud knowledge hub with 29 articles, 20+ model profiles, and diagnostic patterns
- **Telegram Bot** — two-way conversational interface with `/status`, `/logs`, `/stats` commands and CRITICAL alert forwarding
- **KPI Tracking** — MTTR, uptime %, auto-fix rate, intervention rate with persistent snapshots
- **Status Dashboard** — local HTTP endpoint (`localhost:18790`) for health data
- **Resource Capping** — enforces 10% CPU / 256MB RAM budget via systemd or nice values
- **Security Sandbox** — validates all commands before execution, blocks dangerous operations

## Install

```bash
curl -sL easyclaw.help/install | bash
```

Or via pip:

```bash
pip install easyclaw
```

Or Docker:

```bash
docker run -d \
  --name easyclaw \
  -v ~/.openclaw:/host/.openclaw:ro \
  -v /tmp/openclaw:/host/tmp/openclaw:ro \
  -v ~/.easyclaw:/home/easyclaw/.easyclaw \
  easyclaw/easyclaw:latest
```

## Quick Start

```bash
# Run diagnostics first
easyclaw doctor

# Start the daemon (foreground for first run)
easyclaw start -f

# Or background
easyclaw start

# Check status
easyclaw status

# Stop
easyclaw stop
```

## Configuration

EasyClaw stores its config at `~/.easyclaw/config.yaml`. Key settings:

```yaml
# Core
heartbeat_interval: 30        # seconds
health_check_interval: 60     # seconds
log_retention_days: 7
max_restart_attempts: 3       # circuit breaker
restart_window: 600           # circuit breaker window (10 min)
gateway_port: 18789

# Alerts
alert_webhook: null           # n8n/Telegram/Slack webhook URL

# MCP Knowledge Base
mcp_endpoint: null            # e.g., http://your-server:8002
mcp_token: null               # subscription token

# AI Agent Brain
openrouter_api_key: null      # enables LLM-powered reasoning
openrouter_model: "z-ai/glm-4.7-flash"
agent_enabled: true

# Telegram Bot
telegram_bot_token: null      # from @BotFather
telegram_chat_ids: []         # authorized chat IDs
telegram_alert_severity: "CRITICAL"
```

## Architecture

EasyClaw runs as an asyncio daemon with 16 concurrent subsystems:

```
Log Tailing ──> Classifier ──> Alert Pipeline ──> Webhook/Telegram
                    │
                    ▼
              Agent Brain (LLM) ──> MCP Knowledge Base
                    │
                    ▼
              Healer (fallback: rules-based)
                    │
                    ▼
              Executor ──> Sandbox ──> Shell Commands
                    │
                    ▼
              Fix Ledger ──> Circuit Breaker
```

The agent brain activates on events (not continuously), with a 10-second batch window and 30-second cooldown. Typical cost: <$0.02/day. If no API key is configured or OpenRouter is down, it falls back to the rules-based healer automatically.

## Requirements

- Python 3.10+
- Linux, macOS, or WSL2
- OpenClaw installed (runs in standby mode without it)

## License

Proprietary. See [easyclaw.help](https://easyclaw.help) for subscription details.
