2026 OpenClaw Major Upgrade Playbook: Post–2026.3.22 Breaking Changes, Doctor Fixes, Plugin SDK Migration & OPENCLAW_* Environment Variable Map
The 2026.3.22 line moves configuration, plugins, and runtime probes behind stricter contracts. This guide walks through a reproducible remote-Mac SSH session: upgrade, run doctor, migrate custom plugins to the Plugin SDK, and reconcile OPENCLAW_* variables so headless automation keeps working.
What usually breaks after 2026.3.22
Teams hit three clusters of failures: stale launchd/LaunchAgent environments that never see new variables, custom extensions that still target the pre-SDK hook surface, and “silent” misconfigurations that older builds tolerated. If you are new to the stack, What is OpenClaw? Why it’s the Perfect Match for Private Mac mini Hosting explains the hosting model this playbook assumes.
- Doctor gates: health checks now fail closed when plugin manifests or API profiles are incomplete.
- Plugin ABI: legacy
extensions/*.jsentrypoints without a declared SDK version are skipped or error loudly. - Environment namespace: deprecated names are removed from the default search path; only the
OPENCLAW_*family is guaranteed stable across minor releases.
Reproducible remote Mac SSH checklist
Run everything in a single interactive SSH session first. Non-interactive CI shells often omit your profile, which is exactly where macOS services and cron jobs lose variables.
ssh user@your-mac— prefer a dedicated automation user with a known home directory.- Confirm shell:
echo $SHELLand load the same file your daemon uses (~/.zprofile/~/.bash_profile). - Pin the runtime: record
openclaw --version(or your package manager equivalent) before and after upgrade. - Upgrade in place (npm, install script, or tarball—match how the machine was originally provisioned), then open a new SSH session before running doctor.
- Export or source
OPENCLAW_*variables in the same file your LaunchAgentProgramArgumentswrapper sources.
For provider keys and multi-model wiring after the upgrade, see 2026 OpenClaw Multi-Model & API Keys in Practice: MiniMax, Qwen Provider Wiring + Remote Mac SSH FAQ.
Doctor: expected fixes and ordering
Treat openclaw doctor (or the documented health subcommand for your distribution) as the source of truth. Run it twice: once before applying automatic migrations, once after.
Typical remediation sequence
- Resolve “missing manifest” for plugins—each extension needs SDK version, permissions, and entry module path.
- Repair API profile files: base URL, default model id, and secret references must align with the new schema.
- Re-link data directories if the upgrade relocated state under
~/.openclaw(adjust to your install docs). - Re-run doctor until the report is clean; only then restart launchd services.
Plugin SDK migration (practical cutover)
Move each custom integration to a Plugin SDK package: declare sdk version, export the lifecycle hooks the runtime expects (activate, tool registration, teardown), and pin dependencies in the plugin’s own package.json if you ship Node-based tools.
- Copy legacy logic into
src/index.ts(or.js) behind the SDK’s adapter types. - Replace direct filesystem assumptions with the injected workspace handle from the host.
- Add integration tests that run headlessly over SSH—same user, same env file—as your production agent.
OPENCLAW_* environment variable map (cheat sheet)
Names below follow the 2026 unified prefix. Values are examples; substitute your own secrets and paths. Deprecated aliases are noted so you can grep old launchd plists.
| Variable | Role | Example / notes |
|---|---|---|
OPENCLAW_HOME |
State & config root | ~/.openclaw — replaces scattered OPENCLAW_CONFIG_DIR-only layouts |
OPENCLAW_API_PROFILE |
Default LLM profile id | production-east |
OPENCLAW_LOG_LEVEL |
Daemon verbosity | info / debug for post-upgrade investigations |
OPENCLAW_PLUGIN_PATH |
Extra plugin roots | Colon-separated list; SDK packages must sit under declared roots |
OPENCLAW_DISABLE_TELEMETRY |
Privacy switch | 1 on regulated hosts |
OPENCLAW_SSH_BIND |
Reverse tunnel / local bind | 127.0.0.1:18765 — align with firewall rules on the Mac mini |
After editing env files, validate with launchctl kickstart -k gui/$(id -u)/com.your.openclaw (adjust label) or restart the user agent from System Settings — always from the same macOS user that owns the OpenClaw data directory.
Rollback posture
Keep a tarball of OPENCLAW_HOME and your previous binary or npm prefix. If doctor cannot reconcile state, restore the directory and reinstall the prior version, then file a minimal repro plugin that fails the SDK manifest check — that artifact accelerates upstream fixes.
Why a remote Mac mini still wins for this upgrade path
OpenClaw upgrades are sensitive to long-lived processes and consistent POSIX environments. macOS gives you a native Unix userland, predictable paths for LaunchAgents, and Apple Silicon performance without the thermal noise of a laptop running 24/7. A Mac mini M4 idles at very low power while keeping SSH, doctor runs, and plugin builds ready the moment you connect—ideal when you are iterating through breaking migrations.
Gatekeeper, SIP, and FileVault also reduce the attack surface compared with typical Windows automation hosts, and the unified memory architecture keeps multi-tool agent workloads responsive. If you want the stack from this article on hardware that is built to stay on, Mac mini M4 remains one of the most cost-effective dedicated nodes; explore SSHMac plans on the home page to pair it with a managed remote-Mac workflow.