Safe OpenClaw upgrade with instant rollback. Use when user says "upgrade openclaw", "update openclaw", "check for updates", or any request to upgrade/update the OpenClaw installation. NOT for config changes (use gateway config.patch). NOT for skill updates (use clawhub).
Single atomic command. Auto-rollbacks on ANY failure. Survives the gateway restart it triggers.
Script
bash
# From an agent session — ALWAYS set escape flag (ensures script survives gateway restart)
_UPGRADE_FORCE_ESCAPE=1 bash skills/upgrade/scripts/safe-upgrade.sh
# Force upgrade even if already on latest
_UPGRADE_FORCE_ESCAPE=1 bash skills/upgrade/scripts/safe-upgrade.sh --force
# Safe read-only checks (no escape needed)
bash skills/upgrade/scripts/safe-upgrade.sh --check # Pre-flight only
bash skills/upgrade/scripts/safe-upgrade.sh --rollback # Manual rollback
What Happens (one command, 10 steps)
Cgroup escape: re-execs via systemd-run --user --scope so gateway stop can't kill the script
Pre-flight: version check, disk space, breaking changes
Gateway restart (process-isolated: stop + start, survives script's own lifecycle)
Wait for gateway health (configurable timeout) → auto-rollback if fails
Wait for WhatsApp reconnect (non-fatal timeout)
Verify: correct version + cron count preserved → auto-rollback if fails
Record result → optional golden snapshot → cleanup backup
If ANY critical check fails, the script automatically rolls back — restores install, config, crons, and acpx. Trap handler catches unexpected exits during critical phases.
Agent Workflow
Run --check first. Review output with the user.
Inform user: "Launching upgrade — I'll go offline during gateway restart."
OpenClaw runs as a systemd service. When an agent runs this script, the script is a child process inside the service's cgroup. systemctl stop sends SIGKILL to ALL processes in the cgroup — including the upgrade script. SIGKILL cannot be caught (no trap handler fires).
The script detects this and re-execs itself via systemd-run --user --scope into its own transient systemd scope. The parent process exits immediately — no pipes, no tee, no connections back to the gateway cgroup. This is why piping output is forbidden.
Important Notes
Never run gateway update.run directly — always use this script
Always set _UPGRADE_FORCE_ESCAPE=1 when running from an agent session
acpx customizations are auto-preserved across upgrades