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