OpenClaw Upgrade & Rollback on a Leased Cloud Mac (2026 Runbook)

On a 24/7 leased Apple Silicon cloud Mac in Hong Kong, Japan, Korea, Singapore, or the United States, OpenClaw upgrades are not “click update in a browser.” You own the process: launchd plists, optional Docker Compose, ~/.openclaw state, and whatever wrapper scripts your team added. This runbook gives a repeatable upgrade path and a fast rollback when a release breaks the gateway, tool routing, or environment resolution. Pair it with Docker vs native npm, env & API keys in launchd, and cron-style launchd helpers.

Why You Need an Explicit Rollback Story

• Breaking CLI flags — upstream may rename subcommands between minor versions.
• Gateway port contracts — automation assumes a fixed listener; a bump can move defaults.
• Mixed install modes — half Docker, half npm on the same host creates ghost binaries unless you standardize.

Pre-Upgrade Backup Checklist

Artifact	Why
~/.openclaw (entire tree)	Configs, local caches, .env if used
LaunchAgent plist(s)	PATH, EnvironmentVariables, WorkingDirectory
Docker Compose file + pinned image digest	Reproducible rollback to exact layer

Example archive (adjust user and path):

tar czf ~/openclaw-backup-$(date +%Y%m%d-%H%M).tgz ~/.openclaw

npm Global vs Docker: Two Upgrade Surfaces

Mode	Upgrade lever	Rollback lever
Native npm	Reinstall global package at target version	Reinstall previous semver; restore ~/.openclaw
Docker / Compose	docker compose pull + up	Pin old image tag or digest in compose file

Ordered Upgrade Steps

1. Quiesce — stop LaunchAgent or docker compose down so files are not mid-write.
2. Backup — tarball ~/.openclaw; copy plists out of ~/Library/LaunchAgents/ if customized.
3. Apply — npm path or image bump; do not delete backup until green.
4. Reload — launchctl bootstrap / kickstart or compose up -d.

Health Checks Before You Declare Victory

• openclaw --version (native) or docker compose exec equivalent
• Gateway port responds (per your install guide baseline)
• One minimal tool or chat invocation that hits your real API keys — validates env precedence

Rollback Procedure

1. Stop services again.
2. Restore ~/.openclaw from tarball: extract to a temp dir, verify contents, then atomic swap.
3. Re-pin npm package or Docker image to last good version.
4. Reload launchd / Compose; re-run the same health trio.

Bottom line: treat OpenClaw on a leased Mac like any other production daemon: backup → upgrade → verify → rollback path tested once a quarter. Need a stable host? See Apple Silicon nodes and SSH setup.