Already on an older OpenClaw and planning to upgrade to 2026.3.x but worried about config compatibility? 2026.3.x changed the default config logic (e.g. tools.profile, ACP dispatch), so old tutorials may no longer apply. This guide explains why to migrate, pre-upgrade must-dos (backup and checks), the 5-step migration flow (install/upgrade → onboard wizard → API and permissions → daemon → verify), plus common pitfalls—permission rollback, port conflicts, environment variables—and tips for VNC remote Mac, so you can avoid headaches and get it right the first time.
① Why migrate to 2026.3.x? Old tutorials and main changes
2026.3.x tightened security and defaults: on fresh installs tools.profile defaults to messaging (chat/session tools only). If you rely on file read/write or terminal execution, you’ll see “no permission” after upgrading. ACP dispatch is enabled by default and can change multi-agent routing; plugin HTTP registration also changed. So reusing old config or copying old tutorials often leads to broken behavior after upgrade.
| Change | Old / common state | 2026.3.x default / recommendation |
|---|---|---|
| tools.profile | Unset or coding/full | New install defaults to messaging; set to coding or full when you need read/write/execute |
| acp.dispatch | Often unset | Enabled by default; disable if you only want /acp without auto-routing |
| Plugin HTTP registration | registerHttpHandler etc. | Registration behavior changed; check plugin code and docs |
② Pre-upgrade must-dos: backup, version check, dependency check
Do these three before upgrading to avoid failed upgrades or losing config with no way to roll back.
Back up config and workspace
Copy ~/.openclaw/openclaw.json and ~/.openclaw/workspace/ to a safe location. When moving to a new machine, copy both, then run openclaw doctor and openclaw gateway restart.
Version and dependencies
Confirm Node version (20+ recommended); run openclaw doctor for migration and fixes; run openclaw config validate to check config syntax.
Check current tools and ACP
Run openclaw config get tools to see current profile; if using ACP, confirm acp.dispatch.enabled matches what you want.
③ 5-step migration: install/upgrade → onboard wizard → API and permissions → daemon → verify
Step 1: Upgrade to 2026.3.x via npm install -g openclaw@latest or the official install script.
Step 2: Run openclaw onboard to enter the config wizard; choose usage (personal/team), install type (QuickStart etc.), and AI model/API (OpenAI/Claude/third-party) as prompted.
Step 3: In ~/.openclaw/openclaw.json set or confirm tools.profile to coding (normal file and run) or full; to turn off ACP auto-routing set acp.dispatch.enabled: false.
Step 4: If using daemon/LaunchAgent, run openclaw onboard --install-daemon or follow docs to configure the daemon, and ensure plist/env has correct PATH and API-related variables.
Step 5: Run openclaw gateway restart, then openclaw health to confirm the service is up; on a remote Mac we recommend connecting via VNC and doing a full run to ensure no permission dialogs are left pending.
④ Common pitfalls: permission rollback, port conflicts, environment variables, VNC remote Mac
Permission rollback: If you see “no read/write/execute permission” after upgrade, tools.profile is likely set to messaging; change it to coding or full and restart the gateway.
Port conflicts: If a port is in use, use lsof -i :port to find the process, then stop it or change the config to use another port.
Environment variables: When starting via launchd or PM2, set PATH and API-related variables explicitly in the plist or ecosystem config; otherwise the interactive terminal may work but the background service can fail.
VNC remote Mac: Always connect via VNC for upgrade and first-time authorization so you can handle system permission and Keychain dialogs. After upgrade you can use SSH for automation. Upgrading over SSH only can leave dialogs unclickable and the process stuck.
openclaw doctor after upgrade to apply migration and fixes; when moving to a new machine, copy both ~/.openclaw/ and ~/.openclaw/workspace/ to keep config, channel state, and credentials.⑤ FAQ: rollback, multi-instance, and links to our deployment/troubleshooting articles
How do I roll back? If you have a backup of openclaw.json and workspace, restore them, install the old npm version, and restart the service; without a backup you’ll need to reconfigure for the new behavior.
How do I migrate multiple instances? Each instance has its own config directory; back up and upgrade each one separately and verify, and watch port and profile settings.
Related articles on this site: For install or runtime errors see our OpenClaw Common Errors & Troubleshooting guide; for handling authorization dialogs on remote Mac see OpenClaw VNC Approval & Security Isolation; for environment choice see OpenClaw v2026.3.7 environment selection.
Why upgrading OpenClaw on a remote Mac is easier with VNC
2026.3.x migration involves several “first run” steps and possible system permission and Keychain dialogs. Over SSH alone you can’t click those dialogs, so the process can get stuck halfway. On a VNC remote Mac you can complete onboard, handle dialogs, and check openclaw health and logs like on a local machine, so the upgrade path is clear and debugging is faster. To avoid repeated “won’t start after upgrade” or “permissions don’t match” issues, do the upgrade and verification on a VNCMac remote Mac node, then use SSH for day-to-day automation if you like—often the most reliable and time-saving approach.