OpenClaw Watcher 🛡️

AI-powered automated health monitoring and self-healing CLI tool for OpenClaw Gateway.

🌟 What is OpenClaw Watcher?

OpenClaw Watcher is a CLI tool that automatically monitors your OpenClaw Gateway and uses AI (Claude Code or Kimi Code) to directly diagnose and fix issues when they occur. No more manual interventions or 3am wake-up calls!

Key Features

• 🔍 Automated Health Monitoring: Continuous health checks of your OpenClaw Gateway
• 🤖 AI-Powered Repair: AI directly fixes issues using complete tool capabilities
• ⚡ Iterative Fixing: AI keeps trying until the problem is resolved
• 🔒 Secure Config Management: Automatic Git tracking with sensitive data protection
• 📊 Complete Audit Trail: Full history of all AI repairs in files

🚀 Quick Start

Prerequisites

• Node.js >= 22
• OpenClaw Gateway installed
• Claude Code CLI or Kimi Code CLI (at least one)

# Install Claude Code CLI (recommended)
# https://github.com/anthropics/claude-code

# OR install Kimi Code CLI
# https://platform.moonshot.cn/docs/code

Installation & Setup

# Initialize (interactive setup)
npx openclaw-watcher init

The interactive setup will guide you through:

1. OpenClaw configuration directory
2. Gateway URL and port
3. Health check settings
4. AI provider selection
5. Git repository initialization

Start Monitoring

# Start monitoring
npx openclaw-watcher start

Check Status

# View current status
npx openclaw-watcher status

🎓 Advanced Usage

Run as System Service (systemd)

# Create service file
sudo vim /etc/systemd/system/openclaw-watcher.service

[Unit]
Description=OpenClaw Watcher
After=network.target

[Service]
Type=simple
User=openclaw
WorkingDirectory=/path/to/project
ExecStart=/usr/bin/npx openclaw-watcher start
Restart=always

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable openclaw-watcher
sudo systemctl start openclaw-watcher

Multiple Instances

# Instance 1
cd ~/project-1
npx openclaw-watcher init  # Configure for instance 1
npx openclaw-watcher start

# Instance 2
cd ~/project-2
npx openclaw-watcher init  # Configure for instance 2
npx openclaw-watcher start

📖 Full Documentation

🎯 How It Works

┌─────────────────┐
│  Health Check   │  Every 30s (configurable)
└────────┬────────┘
         │ Fails 3x (configurable)
         ▼
┌─────────────────┐
│    Triggered    │  Claude/Kimi Code CLI
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│    Diagnosis    │  Read configs, logs, status
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   AI Repairs    │  Edit files, run commands
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   AI Verifies   │  Restart, check status
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Git Commit     │  Auto-commit changes
└────────┬────────┘
         │ (if GitHub sync enabled)
         ▼
┌─────────────────┐
│  GitHub Push    │  Best-effort, never blocks
└─────────────────┘

🔒 Security Features

Safe Configuration Management

OpenClaw Watcher creates two configuration files:

• openclaw.json - Real config with secrets (NOT tracked in Git)
• openclaw.safe.json - Template with redacted secrets (tracked in Git)

Example:

// openclaw.json (real, gitignored)
{
  "apiKey": "sk-ant-api03-xxx-real-key-xxx",
  "token": "actual-secret-token"
}

// openclaw.safe.json (tracked in Git)
{
  "apiKey": "<YOUR_API_KEY_HERE>",
  "token": "<YOUR_TOKEN_HERE>"
}

Pre-commit Hook

Automatically prevents:

• ❌ Committing openclaw.json
• ❌ Committing actual API keys/tokens in openclaw.safe.json
• ❌ Accidental sensitive data leaks

Automatic Git Workflow

Every AI repair:

1. ✅ Updates openclaw.safe.json from openclaw.json
2. ✅ Redacts all sensitive data
3. ✅ Runs security checks
4. ✅ Commits to Git with detailed message

📋 CLI Commands

init - Initialize

npx openclaw-watcher init [options]

Options:

• --no-git - Skip Git repository initialization

start - Start Monitoring

npx openclaw-watcher start [options]

Options:

• -d, --daemon - Run as daemon process

status - Show Status

npx openclaw-watcher status

Shows:

• Current configuration
• Repair history
• Last repair details

config - Manage Config

npx openclaw-watcher config [options]

Options:

• -s, --show - Display current configuration
• -e, --edit - Edit configuration file

🛠️ Configuration

After initialization, config and logs are stored in ~/.openclaw-watcher/ (customizable via WATCHER_HOME env var):

{
  "monitor": {
    "gatewayUrl": "http://localhost:18789",
    "healthEndpoint": "/health",
    "checkInterval": 30000,
    "failureThreshold": 3
  },
  "ai": {
    "provider": "claude",
    "timeout": 300000
  },
  "recovery": {
    "useGitTracking": true,
    "useGitHubCli": false,
    "openclawConfigPath": "~/.openclaw",
    "maxRecoveryRetries": 3,
    "recoveryCooldownMs": 300000
  }
}

📊 Example Scenario

Problem: Gateway Crashes

1. Health check fails 3 times consecutively
2. AI is triggered
3. AI reads error logs: "Port 18789 already in use"
4. AI diagnoses: Port conflict
5. AI fixes: Changes port to 10003 in openclaw.json
6. AI restarts: openclaw gateway restart
7. AI verifies: Gateway is now healthy
8. System commits: Updates openclaw.safe.json, commits to Git

Git Commit Message

[AutoFix] Gateway failed to start - Port conflict

Root Cause: Port 18789 was already in use by another process
Fix Applied: Changed gateway port from 18789 to 10003 in openclaw.json


Files Modified:
- openclaw.json: Updated port configuration

Commands Executed:
- openclaw gateway restart

Applied by: AI Auto-Fix System

🌐 Git Repository

Watcher manages the entire ~/.openclaw directory as a Git repository — not just repair history, but also agent configurations and any tracked files. Sensitive data (API keys, sessions, cache) is automatically excluded via .gitignore.

~/.openclaw/
├── .git/
│   └── hooks/
│       └── pre-commit              # Security hook
├── .gitignore                      # Git ignore rules
├── README.md                       # Auto-generated docs
├── openclaw.json                   # Real config (NOT tracked)
├── openclaw.safe.json              # Safe template (tracked)
├── agents/*/agent/auth-profiles.json  # API keys (NOT tracked)
├── agents/*/sessions/              # Session history (NOT tracked)
├── memory/*.sqlite                 # Vector index (NOT tracked)
└── cache/                          # Cache (NOT tracked)

.gitignore Coverage

The auto-generated .gitignore excludes the following files and directories, organized by category:

Sensitive Credentials & Keys — Never commit!

| Pattern | Reason | | -------------------- | ------------------------------------------------------- | | openclaw.json | Main config containing API keys and tokens | | credentials/ | Credential store directory | | .env | Environment variables (may contain secrets) | | *.key | Private key files | | auth-profiles.json | Authentication profiles (matched at any depth) | | oauth.json | OAuth tokens and client secrets | | pre-key-*.json | Pre-shared key files |

Runtime Status, Cache & Temporary Files

| Pattern | Reason | | -------------------- | ------------------------------------------------------- | | update-check.json | Runtime update-check state | | canvas/ | Canvas workspace data | | workspace/ | Workspace runtime data | | cache/ | Temporary cache files | | tmp/ | Temporary files | | cron/runs/ | Cron execution logs | | *.bak | Backup files (e.g. openclaw.json.bak) | | *.backup | Backup files | | *.tmp | Temporary files | | *.jsonl | Runtime logs, cron run records, etc. | | *.log | Log files |

Agent Data (Privacy & Size)

| Pattern | Reason | | ----------------------------------- | ------------------------------------------------ | | agents/*/agent/auth-profiles.json | Agent API keys and credentials | | agents/*/sessions/ | Session history — large and may contain PII | | agents/*/memory/ | Long/short-term memory vectors and embeddings | | memory/*.sqlite | Vector index / memory databases (large) |

System & Dependencies

| Pattern | Reason | | -------------------- | ------------------------------------------------------- | | .DS_Store | macOS Finder metadata | | Thumbs.db | Windows thumbnail cache | | node_modules | npm/pnpm dependency directory |

GitHub Sync (Optional)

You can optionally push the repository to a private GitHub repo using the GitHub CLI:

# During init, answer "Yes" to "Sync repair history to GitHub?"
npx openclaw-watcher init

Requirements: gh CLI installed and authenticated (gh auth login).

run in teminal:

gh auth login

How it works:

• During init: creates a private GitHub repo and pushes the initial commit
• During monitoring: auto-pushes to GitHub after each repair commit (best-effort — push failures never block recovery)

If gh is not installed or not authenticated during init, the setup warns and continues — you can always configure GitHub sync later.

View Repair History

cd ~/.openclaw
git log --oneline --grep="\[AutoFix\]"

Rollback a Bad Fix

cd ~/.openclaw
git log --oneline -5
git revert <commit-hash>
openclaw gateway restart

❓ FAQ

Q: What if AI can't fix the issue?

A: The system has built-in retry protection:

• Max retries: After 3 consecutive failed recovery attempts (configurable via maxRecoveryRetries), the system stops retrying and logs a warning requesting manual intervention.
• Cooldown: After each recovery attempt (success or failure), a 5-minute cooldown period (configurable via recoveryCooldownMs) prevents rapid-fire retries.
• Fallback: If the primary AI provider (e.g. Claude) fails, the system automatically tries the fallback provider (e.g. Kimi) before counting it as a failure.

All attempts are logged in detail for manual investigation.

Q: Is it safe to let AI modify configs?

A: Yes! All changes are:

• ✅ Committed to Git (easy rollback)
• ✅ Verified after fixing
• ✅ Logged in detail
• ✅ Protected by pre-commit hooks

Q: Can I review changes before they're applied?

A: Currently no - AI applies fixes immediately. However, all changes are in Git, so you can review and rollback if needed.

Q: Does it work with other services besides OpenClaw?

A: Currently designed specifically for OpenClaw. Contributions welcome for other services!

🤝 Contributing

Issues and Pull Requests are welcome!

📄 License

MIT License

🔗 Links

• OpenClaw Documentation
• Claude Code CLI
• Kimi Code CLI