easyclaw 0.1.0

Autonomous doctor and personal trainer for OpenClaw agents

EasyClaw

Autonomous doctor and personal trainer for OpenClaw 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 13 built-in patterns
• Self-Healing — 11 built-in remediations for common failures (OOM, crashes, stale locks, DNS, rate limits)
• 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

curl -sL easyclaw.help/install | bash

Or via pip:

pip install easyclaw

Or Docker:

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

# 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:

# 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 for subscription details.