System Maintenance

Complete maintenance system for OpenClaw with unified architecture, filesystem governance, and cross-platform design

Security Scan

The skill's stated maintenance functionality matches many of the actions in its files, but there are important inconsistencies and risky actions (crontab modification, file-deletion commands, missing scripts and malformed code) that warrant caution before installing or running it.

Purpose & Capability

The skill claims a full maintenance system and the code/instructions show maintenance tasks (monitoring, log cleanup, backups, cron install). However the SKILL.md references many shell scripts (scripts/*.sh) and a scripts/ directory that are not present in the package manifest. The package contains entry.js which invokes those scripts and other paths that don't exist in this bundle, indicating the published package is incomplete or mispackaged.

Instruction Scope

SKILL.md instructs users/agents to clone a repo, chmod and run several installer and maintenance scripts, and to install cron tasks. entry.js executes shell commands via child_process.execSync, performs deletions (find ... -delete on /tmp paths), runs curl against localhost:18789, reads disk/workspace sizes, and writes to crontab. These actions are within a maintenance skill's scope but are potentially destructive/persistent — and the instructions assume scripts exist that are not bundled here. The SKILL.md is also permissive about installing/running remote install scripts (bash scripts), which increases risk.

Install Mechanism

There is no formal install spec; this is effectively instruction-only. SKILL.md suggests git-clone or a bunx clawhub install that would pull content from GitHub — running the recommended git/one-click install would execute shell installers referenced in the repo. Because the package as published is missing the scripts directory, the instructions will either fail or prompt the user to fetch/execute code from the remote GitHub. Executing remote install scripts without inspection is higher risk.

Credentials

The skill does not request environment variables or external credentials. The code touches local system resources (/tmp, ~/.openclaw/workspace, crontab) and queries localhost endpoints; these are consistent with a system maintenance purpose and do not demand unrelated credentials.

Persistence & Privilege

The skill (and SKILL.md) explicitly installs cron jobs and instructs running installer scripts that create persistent scheduled tasks and backups. The package metadata does not set always:true, but the capability to modify system crontab and install long-running maintenance scripts means the skill will create persistence on the host when used — be aware this persists beyond the agent process.

What to consider before installing

Do not run installer scripts or the package's maintenance scripts without manual review. Specific steps to reduce risk: - Inspect the upstream GitHub repo linked in SKILL.md (https://github.com/jazzqi/openclaw-system-maintenance) and verify the scripts/ directory and install scripts exist and are what you expect. - Do not run install-maintenance-system.sh or any other installer as root; open the script first and review its contents. - Verify the scripts that would be placed into crontab before installing; back up your current crontab (crontab -l > crontab.bak) so you can restore it. - The published package here lacks the referenced scripts and entry.js contains duplicated/malformed sections (uses fs without requiring it and has multiple CLI blocks). Ask the author to publish a complete, consistent package or provide the scripts inline. - If you want to test: run inside an isolated VM or container, and run monitoring/cleanup scripts in --dry-run/test modes first (SKILL.md indicates some scripts support --dry-run/--test). - If you need this capability, prefer installing from the verified upstream repo (after review) rather than blindly running recommended one-click installers.

📖 Layer 1: Immediate Value (30-Second Overview)

What You Get

The System Maintenance Skill provides a complete, unified maintenance solution for OpenClaw systems. It includes real-time monitoring, automated cleanup, log management, and health reporting - all in a modular, easy-to-maintain architecture.

Key Benefits:

• ✅ Automated monitoring every 5 minutes
• ✅ Auto-recovery of failed services
• ✅ 50% reduction in cron tasks
• ✅ Full backup and one-click rollback
• ✅ Weekly optimization reports

Core Value: Replaces fragmented maintenance scripts with a professional, unified system maintenance solution.

🚀 Layer 2: Quick Start (5-Minute Setup)

Installation

Method 1: ClawHub Install (Recommended)

bunx clawhub@latest install system-maintenance

Method 2: GitHub Clone

git clone https://github.com/jazzqi/openclaw-system-maintenance.git \
  ~/.openclaw/skills/system-maintenance
cd ~/.openclaw/skills/system-maintenance
chmod +x scripts/*.sh

One-Click Setup

bash scripts/install-maintenance-system.sh

Verification

# Check cron tasks
crontab -l | grep -i openclaw

# Test monitoring
bash scripts/real-time-monitor.sh --test

# Quick health check
bash scripts/daily-maintenance.sh --quick-check

🏗️ Layer 3: Architecture & Components

Maintenance Schedule

Frequency	Task	Description	Script
Every 5 min	Real-time Monitoring	Gateway monitoring & auto-recovery	real-time-monitor.sh
Daily 2:00 AM	Log Management	Log cleanup, rotation, compression	log-management.sh
Daily 3:30 AM	Daily Maintenance	Comprehensive cleanup & health checks	daily-maintenance.sh
Sunday 3:00 AM	Weekly Optimization	Deep system analysis & reporting	weekly-optimization.sh

Core Functions

🏗️ Unified Architecture

• Modulardesign with 5 core scripts
• Configuration-driven management
• Safe migration from old systems
• Professional directory layout

⏱️ Smart Monitoring & Recovery

• Real-time gateway monitoring
• Automatic service recovery
• Health scoring system (0-100)
• Resource tracking (CPU, memory, disk)
• macOS compatibility

📊 Professional Reporting

• Weekly optimization reports (Markdown)
• Execution summaries
• Optimization suggestions
• Performance metrics tracking

🛡️ Safety & Reliability

• Complete backup system
• One-click rollback
• Error recovery with graceful handling
• Security checks for sensitive info
• Proper permission management

🔄 Maintenance Automation

• Log rotation & cleanup
• Temporary file cleanup
• Daily health checks
• Automatic .learnings/ updates

📚 Layer 4: Resources & Reference

File Structure

system-maintenance/
├── 📄 entry.js                 # Skill entry point
├── 📄 package.json             # NPM configuration
├── 📄 SKILL.md                 # This file
├── 🛠️  scripts/                # Core scripts
│   ├── weekly-optimization.sh      # Weekly deep optimization
│   ├── real-time-monitor.sh        # Real-time monitoring (5 min)
│   ├── log-management.sh           # Log cleanup & rotation
│   ├── daily-maintenance.sh        # Daily maintenance (3:30 AM)
│   ├── install-maintenance-system.sh # Installation tool
│   └── check-before-commit.sh      # Pre-commit quality check
├── 📚  examples/               # Examples & templates
│   ├── setup-guide.md              # Quick setup guide
│   ├── migration-guide.md          # Safe migration guide
│   ├── final-status-template.md    # Status report template
│   └── optimization-suggestions.md # Optimization suggestions
├── 📝  docs/                   # Additional documentation
│   ├── FILE_SYSTEM_GOVERNANCE.md   # FS Governance Standard
│   └── cross-platform-architecture.md
└── 📁 assets/                  # Static resources
    └── README.md

Command Reference

Real-time Monitor

# Test mode (no actual operations)
bash scripts/real-time-monitor.sh --test

# Force execution
bash scripts/real-time-monitor.sh --force

# View status
bash scripts/real-time-monitor.sh --status

Log Management

# Dry run (preview changes)
bash scripts/log-management.sh --dry-run

# Manual rotation
bash scripts/log-management.sh --rotate

# Cleanup only
bash scripts/log-management.sh --cleanup

Daily Maintenance

# Quick health check only
bash scripts/daily-maintenance.sh --quick-check

# Full maintenance cycle
bash scripts/daily-maintenance.sh --full

# Skip backup (emergency mode)
bash scripts/daily-maintenance.sh --no-backup

Weekly Optimization

# Generate report only (no optimization)
bash scripts/weekly-optimization.sh --report-only

# Analysis only (no changes)
bash scripts/weekly-optimization.sh --analyze-only

# Full optimization cycle
bash scripts/weekly-optimization.sh --optimize

Version History

Version	Date	Changes
1.3.2	2026-03-16	Reorganized SKILL.md with progressive disclosure; cleaned up backup files
1.3.1	2026-03-16	Added FS Governance; improved error handling
1.3.0	2026-03-12	Archival version, initial ClawHub release

🔧 Layer 5: Advanced Configuration

Customization Options

• Configuration file: scripts/config.json
• Monitoring intervals: Adjust in real-time-monitor.sh
• Log policies: Modify in log-management.sh
• Health thresholds: Configure in health check scripts

Integration Points

• System Status API: Emergency endpoints
• Logging Forwarding: External log aggregation
• Metrics Export: Prometheus/Grafana compatible
• Webhook Notifications: Slack, Discord, email

Security Features

• Encrypted Backups: Optional GPG encryption
• Access Controls: File permission management
• Audit Logging: All maintenance actions logged
• Secrets Management: Integration with vault systems

🛠️ Usage Examples

Quick Health Check

# Run all health checks in sequence
bash scripts/daily-maintenance.sh --quick-check
bash scripts/log-management.sh --status
bash scripts/real-time-monitor.sh --status

Emergency Recovery

# Force restore from latest backup
bash scripts/install-maintenance-system.sh --restore-latest

# Manual service restart
pkill -f openclaw-gateway && openclaw gateway start

Performance Tuning

# Adjust monitoring frequency (edit config)
# Default: 5 minutes, can be set to 1-60 minutes
# Example: Set to 2 minutes for critical systems

🤝 Contributing

Please read CONTRIBUTING.md before submitting pull requests.

📜 License

MIT License - see LICENSE file for details.

---

Built with ❤️ for the OpenClaw community