🩺 OpenClaw Doctor

Autonomous DevOps agent for diagnosing and fixing OpenClaw Gateway issues.

Uses an AI-powered REPL loop (observe → think → act → verify) with function calling to autonomously identify and resolve problems.

Features

• REPL Loop — AI agent iteratively diagnoses and fixes issues (up to 20 iterations)
• 12 Built-in Tools — gateway status, logs, systemd journal, resource monitoring, channel probes, shell commands, doc fetching, process management, Telegram notifications
• 5 Modes — auto, check (read-only), problem-specific, interactive REPL, watchdog
• Safety First — dangerous commands blocked, config never modified without approval, diagnoses before acting
• Telegram Notifications — sends alerts when issues are found/fixed
• OpenClaw Skill — installable as a native OpenClaw skill

Quick Start

Requirements

• Python 3.10+
• OpenClaw CLI (openclaw) in PATH
• OpenAI API key

Install

pip install openai

# Option 1: Run directly
python3 scripts/openclaw-doctor.py --check

# Option 2: Install as OpenClaw skill
openclaw skills install openclaw-doctor.skill

Set your API key

export OPENAI_API_KEY="sk-..."

Usage

# Full auto-diagnosis + fix
python3 scripts/openclaw-doctor.py

# Check only (read-only, no changes)
python3 scripts/openclaw-doctor.py --check

# Fix a specific problem
python3 scripts/openclaw-doctor.py --problem "Telegram не доставляет сообщения"

# Interactive REPL
python3 scripts/openclaw-doctor.py --interactive

# Watchdog mode (continuous monitoring + auto-fix)
python3 scripts/openclaw-doctor.py --watch

# Use a different model
python3 scripts/openclaw-doctor.py --model gpt-4.1

How It Works

┌─────────────────────────────────────────┐
│           OpenClaw Doctor               │
│                                         │
│  ┌─────────┐    ┌───────┐    ┌───────┐  │
│  │ OBSERVE │───→│ THINK │───→│  ACT  │  │
│  │ (tools) │    │ (LLM) │    │(tools)│  │
│  └────▲────┘    └───────┘    └───┬───┘  │
│       │                         │       │
│       │    ┌────────┐           │       │
│       └────│ VERIFY │←──────────┘       │
│            │(tools) │                   │
│            └────────┘                   │
└─────────────────────────────────────────┘

The AI agent (GPT-5.2 by default) decides which tools to call at each step. It can:

1. Check gateway status and RPC probe
2. Read and filter logs by severity
3. Inspect system resources (RAM, disk, CPU)
4. Probe channel connectivity (Telegram, etc.)
5. Read systemd journal for crash details
6. Run diagnostic shell commands
7. Fetch OpenClaw documentation for troubleshooting
8. Kill zombie processes (Chrome/Playwright)
9. Restart the gateway (with verification)
10. Send Telegram notifications

Tools

Tool	Description	Mutating
check_gateway	Gateway status + RPC probe	No
get_logs	Gateway logs with level filter	No
run_doctor	openclaw doctor config check	No
check_resources	RAM, disk, CPU, top processes, ports	No
check_channels	Channel probe (Telegram etc.)	No
systemd_journal	systemd unit journal	No
read_config	Read openclaw.json	No
fetch_docs	Fetch docs.openclaw.ai page	No
run_command	Shell command (dangerous blocked)	Maybe
restart_gateway	systemctl restart + verify	Yes
kill_zombie_processes	Kill hung processes by pattern	Yes
notify_telegram	Send Telegram notification	No

Configuration

Environment Variable	Default	Description
OPENAI_API_KEY	—	OpenAI API key (required)
DOCTOR_MODEL	gpt-5.2	AI model for diagnosis
DOCTOR_MAX_ITERATIONS	20	Max REPL loop iterations
DOCTOR_WATCH_INTERVAL	30	Watchdog check interval (seconds)
TG_BOT_TOKEN	—	Telegram bot token for notifications
TG_CHAT_ID	—	Telegram chat ID for notifications

Common Issues It Can Fix

Issue	Detection	Auto-Fix
Zombie Chrome processes	ps aux | grep chrome	Kill + restart
OOM kill	dmesg, journal	Clean cache + restart
Port conflict (EADDRINUSE)	ss -tlnp	Kill conflicting process
Disk full	df -h	Clean old logs
Channel disconnect	openclaw channels status	Probe + report
Config errors after upgrade	openclaw doctor	Report (no auto-modify)

Project Structure

openclaw-doctor/
├── README.md
├── SKILL.md                    # OpenClaw skill metadata
├── scripts/
│   └── openclaw-doctor.py      # Main agent
└── references/
    └── common-issues.md        # Known issues reference

As an OpenClaw Skill

This project is also an OpenClaw skill. When installed, OpenClaw will automatically use it when you ask about gateway diagnostics or health checks.

# Install the skill
openclaw skills install openclaw-doctor.skill

# Then just ask your agent:
# "проверь здоровье gateway"
# "почему Telegram не работает"
# "почисти зомби-процессы"

License

MIT

Credits

Built for OpenClaw — the open-source AI gateway.