$cd ../troubleshooting/
CRITICAL📦 Installation
Dual Install: Shadowed openclaw Binary — Wrong Version Runs
// You upgraded OpenClaw but `openclaw --version` still shows an old build, doctor fixes never stick, or gateway behavior matches a release you thought you removed. This almost always means two global installs exist — commonly `sudo npm i -g openclaw` under /usr/local/bin plus a user-level install under ~/.npm-global or nvm — and your shell resolves the wrong one first. The shadowed binary is silent: commands succeed, but they run stale code. This unofficial guide shows how to map every copy on disk, pick one install strategy, fix PATH precedence, and reinstall cleanly to the user prefix OpenClaw docs recommend.
diagnose.sh
🔍 Is This Your Issue?
?`openclaw --version` shows an older release than you just installed
?`which -a openclaw` lists two or more paths (e.g. /usr/local/bin and ~/.npm-global/bin)
?Fixes from `openclaw doctor` or upgrades never appear in runtime behavior
?You previously ran both `sudo npm i -g openclaw` and a normal-user global install
?Gateway logs reference features missing from the version you expect
diagnose_paths.sh
✅ Fix 1 — Map Every openclaw Binary on Disk
Map all binaries before changing anything
# List every openclaw on PATH which -a openclaw # Bash: show all resolved names type -a openclaw # Compare versions at each path /usr/local/bin/openclaw --version 2>/dev/null ~/.npm-global/bin/openclaw --version 2>/dev/null # Show npm global roots npm prefix -g sudo npm prefix -g 2>/dev/null
Confirm duplicate npm installs and active binary
# Check both npm global trees npm list -g openclaw --depth=0 sudo npm list -g openclaw --depth=0 2>/dev/null # See what your shell actually runs hash -r # bash: clear command cache command -v openclaw openclaw --version
uninstall_dupes.sh
✅ Fix 2 — Remove the Duplicate Install Path
Uninstall both trees — config in ~/.openclaw is safe
# Remove user-level global copy npm uninstall -g openclaw # Remove system-wide sudo copy (if present) sudo npm uninstall -g openclaw # Verify nothing left on PATH which -a openclaw || echo "no openclaw on PATH — good"
Manual cleanup if npm uninstall leaves broken symlinks
# Optional: delete stale symlinks manually sudo rm -f /usr/local/bin/openclaw rm -f ~/.npm-global/bin/openclaw # Clear shell hash table hash -r # Confirm clean slate which -a openclaw
reinstall_clean.sh
✅ Fix 3 — Fix PATH Order & Reinstall to User Prefix
User prefix wins over /usr/local/bin when PATH is ordered correctly
# Standard user prefix (recommended) npm config set prefix "$HOME/.npm-global" mkdir -p "$HOME/.npm-global/bin" # Add to ~/.bashrc or ~/.zshrc — npm bin FIRST export PATH="$HOME/.npm-global/bin:$PATH" # Reload shell source ~/.bashrc # or ~/.zshrc
One path, one version — then restart services
# Fresh install to user prefix npm i -g openclaw@latest # Verify single binary which -a openclaw openclaw --version openclaw doctor # Restart gateway if running openclaw gateway restart
💡 Pro Tip: One Global Strategy Only
Pick either user-level npm global (recommended) OR system-wide sudo install — never both. After cleanup, `which -a openclaw` should return exactly one path. Pin your npm prefix in ~/.npmrc so future `npm i -g` never lands in a second location.
🛡️ Prevention Checklist
- • Never mix `sudo npm i -g openclaw` with a user-level global install — choose one prefix and stick to it
- • After any install, run `which -a openclaw` and `openclaw --version` before restarting gateway or running doctor
- • Put your npm global bin (from `npm prefix -g`/bin) ahead of /usr/local/bin in ~/.bashrc or ~/.zshrc
- • If you use nvm/fnm, ensure the version manager init runs in non-interactive shells (systemd, cron, SSH)
- • Document your chosen install path in a README on the host so future-you does not sudo-install again
❓ FAQ
Q1. How do I know I have a shadowed binary?
Run `which -a openclaw` (or `type -a openclaw` in bash). If you see two or more paths — e.g. /usr/local/bin/openclaw and /home/you/.npm-global/bin/openclaw — your shell uses whichever appears first in $PATH. Compare `openclaw --version` with ` /usr/local/bin/openclaw --version` and the user-path binary separately. Mismatched versions confirm shadowing. Also check `npm list -g openclaw` run as your user vs `sudo npm list -g openclaw`; both showing an install is a red flag.
Q2. Should I keep the sudo install or the user-level install?
Community practice on Linux VPS and Mac Mini aligns with user-level global install without sudo: `npm config set prefix ~/.npm-global` then add that bin dir to PATH. Sudo installs write to /usr/local and are easy to forget when you later `npm i -g` as your normal user. If you already have a working user prefix, remove the sudo copy. Only keep a system-wide install if you deliberately manage one service account and never install as your login user.
Q3. I removed the old binary but openclaw still shows the wrong version in systemd.
The gateway service may call an absolute path or inherit a minimal PATH from systemd/launchd. Inspect `~/.config/systemd/user/openclaw-gateway.service` (or your plist) for ExecStart= and Environment=PATH=. Update the unit to use the correct binary path or export the full PATH including your npm global bin. Then `systemctl --user daemon-reload && systemctl --user restart openclaw-gateway`. Interactive shell fixes do not automatically fix daemon environments.
Q4. Can nvm cause the same problem?
Yes. nvm installs Node and global packages per Node version. If you installed openclaw under Node 22 but systemd runs Node 20, or your login shell loads nvm but cron does not, you get different binaries. Run `node -v` and `which openclaw` in the same context as the gateway (e.g. `systemctl --user show-environment`). Consider fnm/nvm with a default alias, or install openclaw via the official install script that targets a stable path.
Q5. Will uninstalling break my ~/.openclaw config?
No. Config, sessions, and channel auth live under ~/.openclaw/ and are independent of which global binary you invoke. Uninstalling removes only the CLI/gateway package from npm's global tree. After reinstalling the correct version, `openclaw doctor` should see the same config. Back up ~/.openclaw/openclaw.json before major cleanup if you want extra safety.
Q6. What is the cleanest reinstall procedure?
1) Note current config path. 2) `npm uninstall -g openclaw` as user AND `sudo npm uninstall -g openclaw` to clear both trees. 3) Verify `which -a openclaw` returns nothing. 4) Set prefix: `npm config set prefix ~/.npm-global`. 5) Add export PATH="$HOME/.npm-global/bin:$PATH" to shell rc. 6) `npm i -g openclaw@latest`. 7) Confirm single path and version, then restart gateway. Official repo: github.com/openclaw/openclaw.