$cd ../troubleshooting/
High📦 Installation
Gateway Crashes After Upgrade — Stale Paths in openclaw.json
// Major OpenClaw upgrades (especially Clawdbot → OpenClaw renames and npm global path changes) leave sourcePath and installPath in ~/.openclaw/openclaw.json pointing at directories that no longer exist. The gateway service starts, immediately exits, and logs ENOENT or 'install path invalid'. openclaw doctor --fix rewrites these keys to match the current binary location.
diagnose.sh
🔍 Is This Your Issue?
?Gateway exits immediately after openclaw gateway start or systemctl restart
?Logs mention ENOENT, install path invalid, or sourcePath not found
?openclaw.json still references clawdbot, old nvm version paths, or deleted home directories
doctor_fix.sh
✅ Fix 1 — Run openclaw doctor --fix (Fastest)
Preferred fix — backs up config before writing
# Inspect current paths vs binary openclaw doctor # Auto-fix stale paths and schema drift openclaw doctor --fix # Verify gateway openclaw gateway restart openclaw gateway status
openclaw.json
✅ Fix 2 — Manually Update Paths in openclaw.json
installPath = directory containing package.json for openclaw
# Find live install location
which openclaw
# e.g. /home/you/.nvm/versions/node/v22.4.0/bin/openclaw
# Edit ~/.openclaw/openclaw.json
{
"installPath": "/home/you/.nvm/versions/node/v22.4.0/lib/node_modules/openclaw",
"sourcePath": null
}
openclaw gateway restartgateway_install.sh
✅ Fix 3 — Reinstall Gateway Service
Regenerates service with current binary path
# Linux systemd openclaw gateway stop openclaw gateway uninstall openclaw gateway install systemctl --user daemon-reload systemctl --user restart openclaw-gateway # macOS openclaw gateway install --force # Windows (elevated once for task) openclaw gateway install
💡 Pro Tip: Backup Config Before Every Upgrade
Copy ~/.openclaw/openclaw.json to openclaw.json.bak before npm update -g openclaw. If the gateway fails to start, diff the backup against the new file — stale path keys are usually the only breaking change.
🛡️ Prevention checklist
- • Run openclaw doctor (without --fix) after every upgrade — read warnings before they become crashes
- • Avoid hand-editing sourcePath/installPath unless you symlink a custom checkout
- • When migrating machines, rsync ~/.openclaw/ but re-run doctor --fix on the new host
- • Keep npm prefix stable (see Windows EACCES guide) so installPath does not drift silently
- • Document your gateway install method (systemd vs launchd vs Scheduled Task) in a README note
❓ FAQ
Q1. What are sourcePath and installPath used for?
installPath is the directory containing the running openclaw CLI and bundled assets. sourcePath (when set) points at a git checkout used for dev plugins or local patches. The gateway validates both on startup so skills, default configs, and auto-update hooks resolve correctly. Stale values cause immediate startup failure rather than silent misrouting.
Q2. Why didn't npm update -g fix the paths automatically?
npm replaces the package under your global prefix but does not edit user config in ~/.openclaw/. Path keys are written once during openclaw setup or gateway install and persist across upgrades. doctor --fix compares the live binary location (which npm did update) against config and patches the mismatch.
Q3. Is it safe to delete sourcePath entirely?
If you are not developing OpenClaw from source, yes — remove sourcePath or set it null and rely on installPath only. Leaving a dead sourcePath to an old Clawdbot clone is a common post-migration footgun. Production installs need only installPath pointing at the global npm tree or nvm slot.
Q4. doctor --fix changed other settings — is that normal?
doctor may also normalize schema version, migrate renamed keys, and refresh gateway.auth placeholders. Review the diff: openclaw doctor --fix --dry-run when available, or backup first. Path fixes are the critical part; accept benign migrations unless they touch secrets you rotated manually.
Q5. Gateway still crashes after Fix 1 — what next?
Check logs: journalctl --user -u openclaw-gateway -n 50 (Linux) or openclaw gateway logs. Look for a different ENOENT (skills dir, channel auth). Re-run Fix 3 to regenerate the service unit. Confirm which openclaw binary the service invokes — a shadowed old binary in /usr/local/bin is a separate issue (see dual-install guide).
Q6. I'm on Docker — do I need this guide?
Bind-mounted ~/.openclaw/openclaw.json inside containers can carry host paths like /home/user/.nvm/... that do not exist in the container filesystem. Either mount consistent paths, set installPath inside the container (e.g. /app), or let the entrypoint run doctor --fix on boot.