Upgrade Guard 🔄

🇨🇳 中文文档

Never lose a working OpenClaw to a bad upgrade again.

Born from 7 cascading failures during a single version jump.

The gateway crashed, Telegram disconnected, plugins broke, models vanished — and the AI agent that caused it was also dead, so nobody could fix it remotely.

This skill makes upgrades safe.

The Problem

OpenClaw upgrades can break in ways that are invisible until it's too late:

• Plugin renames — clawdbot.plugin.json → openclaw.plugin.json
• Dependency breaks — SDK module paths change, exports shift
• Config schema changes — new required fields, removed fields
• Model name changes — dot vs hyphen format
• Channel config wipes — silent removal during migration

A single git pull && pnpm install can trigger all of these simultaneously.

Quick Start

# Install
clawdhub install upgrade-guard
# or: git clone https://github.com/jzOcb/upgrade-guard

# Before upgrading: snapshot your working system
bash scripts/upgrade-guard.sh snapshot

# Check what's coming
bash scripts/upgrade-guard.sh check

# Safe upgrade (auto-rollback on failure)
bash scripts/upgrade-guard.sh upgrade

# Something broke? Emergency rollback
bash scripts/upgrade-guard.sh rollback

Commands

| Command | What it does | |---|---| | snapshot | Save current state (version, config, plugins, deps, symlinks) | | check | Pre-flight validation (disk, git, config, breaking changes) | | upgrade | Full safe upgrade: snapshot → check → pull → install → build → verify | | upgrade --dry-run | Preview without changing anything | | verify | Post-upgrade checks (plugins, channels, model, gateway, logs) | | rollback | Emergency restore to last snapshot | | status | Show current state vs snapshots |

What It Checks

Pre-upgrade:

• Snapshot exists
• Config file valid
• Git repo clean
• Disk space sufficient
• Breaking change signals in incoming commits

Post-upgrade:

• Plugin files renamed/removed (detects clawdbot↔openclaw renames)
• Config still valid, channels still configured
• Model still set
• No broken symlinks
• Gateway starts and responds
• No errors in recent logs

Use With config-guard

| | config-guard | upgrade-guard | |---|---|---| | Config validation | ✅ | ❌ | | Plugin renames | ❌ | ✅ | | Dependency breaks | ❌ | ✅ | | Version tracking | ❌ | ✅ | | Git state management | ❌ | ✅ | | Full system rollback | ❌ | ✅ |

Best used together: config-guard for config edits, upgrade-guard for version upgrades.

Watchdog — OS-Level Self-Healing

The real "fix it without you" piece. Runs as a systemd timer, independent of the AI agent and gateway.

# Install (checks every 60 seconds)
bash scripts/watchdog.sh install

# Manual check
bash scripts/watchdog.sh check

# Status
bash scripts/watchdog.sh status

Recovery strategy:

• Failures 1-2 → log and wait
• Failure 3 → restart gateway
• Failure 6+ → full rollback to last snapshot

Survives: gateway crash, AI agent death, server reboots.

Requirements

• bash 4+, python3, curl, git, pnpm or npm

🛡️ Part of the AI Agent Security Suite

| Tool | What It Prevents | |------|-----------------| | agent-guardrails | AI rewrites validated code, leaks secrets, bypasses standards | | config-guard | AI writes malformed config, crashes gateway | | upgrade-guard | Version upgrades break dependencies, no rollback | | token-guard | Runaway token costs, budget overruns | | process-guardian | Background processes die silently, no auto-recovery |

📖 Read the full story: I audited my own AI agent system and found it full of holes

License

MIT

🛡️ Part of the OpenClaw Security Suite

| Guard | Purpose | Protects Against | |-------|---------|------------------| | agent-guardrails | Pre-commit hooks + secret detection | Code leaks, unsafe commits | | config-guard | Config validation + auto-rollback | Gateway crashes from bad config | | upgrade-guard | Safe upgrades + watchdog | Update failures, cascading breaks | | token-guard | Usage monitoring + cost alerts | Budget overruns, runaway costs |

📚 Full writeup: 4-Layer Defense System for AI Agents