Upgrade Guard
Safe OpenClaw upgrades with snapshot, pre-flight checks, controlled upgrade steps, post-verification, and emergency rollback. Never lose your working system to a bad update again. Bilingual README (EN/CN).
Choose how to use this skill
You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.
1. Native installer
This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.
Do not guess an installer command or replace an existing version without reviewing the diff.
2. Complete package recommended
Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.
No complete ProSkills package is published for this listing yet.3. Prompt-only
Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.
Need only the instruction file?
Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.
No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.
// RATINGS
Not yet listed on ClawHub or SkillsMP
// README
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
bash4+,python3,curl,git,pnpmornpm
🛡️ 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