Upgrade

OpenClaw Safe Upgrade

Single atomic command. Auto-rollbacks on ANY failure. Survives the gateway restart it triggers.

Script

# 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)

1. Cgroup escape: re-execs via systemd-run --user --scope so gateway stop can't kill the script
2. Pre-flight: version check, disk space, breaking changes
3. Backup: installation tarball, config, cron jobs, acpx customizations
4. npm i -g openclaw@latest
5. Restore acpx config (ACP agent customizations survive upgrades)
6. Gateway restart (process-isolated: stop + start, survives script's own lifecycle)
7. Wait for gateway health (configurable timeout) → auto-rollback if fails
8. Wait for WhatsApp reconnect (non-fatal timeout)
9. Verify: correct version + cron count preserved → auto-rollback if fails
10. 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

1. Run --check first. Review output with the user.
2. Inform user: "Launching upgrade — I'll go offline during gateway restart."
3. Run the upgrade:

   _UPGRADE_FORCE_ESCAPE=1 bash skills/upgrade/scripts/safe-upgrade.sh
   

   Do NOT pipe the output (no | tee, no 2>&1 | cat). The script writes to /tmp/upgrade-live.log.
4. The current session will end when the gateway restarts. This is expected.
5. After restart, the new session checks:
   • ~/.openclaw/upgrade-result.json for status
   • /tmp/upgrade-live.log for live output
   • success: report to user, update any version references
   • rolled_back: tell user what went wrong (reason in result file)
   • No result file + backup at ~/.openclaw/upgrade-backups/current/: script was killed — run --rollback
6. Full forensic log at ~/.openclaw/upgrade-last.log.

What Gets Backed Up

• OpenClaw installation tarball
• Config (openclaw.json)
• Cron jobs (jobs.json)
• acpx user config (~/.acpx/config.json) if present
• Metadata (from/to version, timestamp, cron count)

Backup location: ~/.openclaw/upgrade-backups/current/

Result File

~/.openclaw/upgrade-result.json:

{
    "status": "success|rolled_back|rollback_failed|no_change|blocked",
    "from_version": "2026.3.2",
    "to_version": "2026.3.7",
    "message": "...",
    "timestamp": "...",
    "log": "~/.openclaw/upgrade-last.log"
}

Why Cgroup Escape?

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
• Rollback restores the EXACT previous state: install + config + crons + acpx
• --check is safe to run anytime, changes nothing
• The script auto-detects gateway port from config (no hardcoded defaults)
• Optional hooks: if golden-snapshot.sh or service-quick-check.py exist in your workspace, they're used; otherwise silently skipped