OpenClaw 2026 cloud Mac version upgrade troubleshooting: disk preflight, launchd stale job cleanup, and update restart health checklist

Unlike first-time install and onboard or launchd token troubleshooting, this piece focuses on the Gateway already running, need a rolling upgrade path: you SSH into a rented cloud Mac, run openclaw update, expect to return to production within minutes, and instead land in a launchd restart loop.

In on-call postmortems, these five pain points are routinely underestimated:

• plugin-runtime-deps ENOSPC: 2026.4.24 and nearby versions extract bundled dependencies into ~/.openclaw/plugin-runtime-deps during upgrade. When disk headroom is insufficient, the operation fails mid-flight while Gateway may still display ready but is actually unhealthy (see openclaw#71835).
• stale ai.openclaw.update.* jobs: after beta upgrades, launchd may retain updater jobs that repeatedly trigger Gateway restarts with exit 127, causing gateway status --deep probe failures (see openclaw#81859).
• mixed-version false-ready: the CLI updates while the Gateway process remains on an old build, or plugins fail to load without blocking the success message, leaving remote client Health Check in pending state.
• multiple Node install paths: from 2026.5.20 onward, openclaw update tries to use the Node that hosts the Gateway service. If Homebrew Node and fnm Node coexist on the machine, restart may switch to the wrong binary.
• lease and window pressure: on daily or weekly rented instances, an ENOSPC mid-upgrade leaves almost no time to decide between temporary expansion or a second parallel node; buffer should be planned in the lease term matrix ahead of time.

Memory line for on-call: df first, then update, deep status, doctor clears jobs, health 200 before you sign off. Skipping disk preflight or stale job cleanup turns a ten-minute upgrade into hours of rework.

Before you press openclaw update, align storage, compute, and time window in one table so you are not clicking expand in the console mid-upgrade.

If you also run the WeChat ClawBot channel, pause new QR binding during the upgrade window. After Gateway restart health passes, run openclaw gateway restart and reconnect the channel.

Before upgrading, assert disk and staging directories with a non-interactive script so on-call does not get paged at midnight.

df -h / | awk 'NR==2{print "avail="$4,"use="$5}'
du -sh ~/.openclaw/plugin-runtime-deps 2>/dev/null || echo "no staging yet"
launchctl list | grep -E 'openclaw\.(gateway|update)'
openclaw --version
openclaw gateway status --json | head -c 400

• Citable: plugin-runtime-deps path — default ~/.openclaw/plugin-runtime-deps; override with OPENCLAW_PLUGIN_STAGE_DIR to point at a separate volume. Reserve ≥ 8–15 GB contiguous free space for a major upgrade (depends on installed plugin count).
• Citable: typical ENOSPC log — failed to install bundled runtime deps: Error: ENOSPC: no space left on device. Do not rerun update repeatedly; expand first or rm -rf incomplete staging, then retry.
• Citable: root volume alert threshold — production should keep root volume usage below 80% long term. Above 85%, OpenClaw upgrades and Xcode cache writes significantly increase failure rates.

1. Backup config and token snapshot: cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak.$(date +%Y%m%d); record current openclaw --version and gateway status --deep JSON.
2. Run preflight script: confirm root volume free ≥ 15 GB; no abnormally large staging directory; list openclaw-related jobs in launchd.
3. Update in low-traffic window: openclaw update (or npm update -g openclaw / brew upgrade openclaw, consistent with your install path); watch the restart health section in CLI output.
4. deep status probe: openclaw gateway status --deep; Connectivity probe should be ok. If stale updater job is reported, clean per the next section before kickstart.
5. doctor and health HTTP: openclaw doctor; curl -sf -H "Authorization: Bearer token $(openclaw config get gateway.auth.token)" http://127.0.0.1:18789/health should return 200.
6. Register version baseline: write CLI and Gateway hello versions into change log; on the pricing page evaluate whether plugin cache growth warrants long-term 1 TB; restore remote client pairing tests.

openclaw update
openclaw gateway status --deep
openclaw doctor
curl -sf http://127.0.0.1:18789/health
launchctl kickstart -k gui/$(id -u)/ai.openclaw.gateway

From 2026.5.20 onward, openclaw update still attempts restart health when CLI and Gateway have a one-version protocol skew, and prefers the Node that hosts the Gateway service for subsequent commands, reducing the chance of update succeeded but Gateway runs on wrong Node.

When gateway status --deep reports connectivity failed and launchctl list shows high RunCount on ai.openclaw.update.*, follow official diagnostics to clean stale updater jobs first, then repair the LaunchAgent.

In mixed-version scenarios, do not trust CLI printed ready alone: restart health and plugin load results are the source of truth. If repeated gateway restart fails, run openclaw gateway install --force during a maintenance window to rebuild the LaunchAgent, then run openclaw doctor again.

Binding OpenClaw upgrades to a home Mac or sleep-prone laptop stacks system updates and disk fragmentation on top of upgrade risk. Hosting on oversubscribed VPS or non-macOS cannot follow Apple channel and native launchd paths. Teams that need repeatable update, second-scale disk expansion, and dedicated bare-metal compute usually get the calmest path by following this six-step upgrade on JEXCLOUD multi-region cloud Mac hosts, and leaving buffer via 1 TB / 2 TB expansion or M4 Pro parallel nodes before ENOSPC: roughly two-minute provisioning and project-elastic lease terms. See the JEXCLOUD pricing page for plans.