openclaw - 💡(How to fix) Fix Bug: update dev-channel switch can leave npm-global openclaw as source checkout symlink [2 comments, 2 participants]

Summary

On a normal npm-global OpenClaw install, the updater can appear to switch from package mode to git/source mode and run a global install against the git checkout path. On this host that left the global package root as a symlink:

~/.npm-global/lib/node_modules/openclaw -> ../../../../../opt/openclaw-source

That broke the gateway after a later update because systemd/CLI executed stale source-checkout code while plugins/config expected the newer package layout.

Evidence from affected host

• Bad symlink timestamp: Apr 26, 2026 around 21:53 CDT.
• Same window had source-build/update activity:
  • pnpm tooling under ~/.local/share/pnpm/.tools around 21:42
  • /opt/openclaw-source/node_modules populated around 21:46-21:52
  • /opt/openclaw-source/dist and dist-runtime written around 21:52-21:53
• No npm debug log was found for the 21:40-22:10 window, so this does not look like a normal standalone npm install -g openclaw.
• Before repair, the service entrypoint resolved through the global npm path into /opt/openclaw-source.
• Manual repair was to replace the symlink with a real package install: npm install -g [email protected], then regenerate/repair service state.

Suspected mechanism

In the update CLI source, when requestedChannel === "dev" && installKind !== "git", the update path switches package installs to a git checkout. The code path then uses the git checkout as the install spec for the global install:

src/cli/update-cli/update-command.ts
switchToGit = requestedChannel === "dev" && installKind !== "git"
updateRoot = resolveGitInstallDir()
ensureGitCheckout(updateRoot)
runGatewayUpdate({ cwd: updateRoot, argv1: undefined, channel: ... })
globalInstallArgs(installTarget, updateRoot)

For npm, that is effectively:

npm i -g /opt/openclaw-source

On this host that resulted in the global package root being a symlink to the source checkout.

Expected behavior

A normal npm-global install should not silently become a global symlink to a mutable git/source checkout. If dev-channel switching is intentional, the updater/status/doctor should make that explicit and ensure the service/plugin runtime cannot end up in a mixed stale-source/package state.

Suggested fixes

• openclaw update should not leave global node_modules/openclaw as a symlink to the source checkout unless explicitly requested and clearly reported.
• openclaw update --json should return a failing exit code when it reports status: "skipped" for dirty git/source state, or callers should otherwise have a reliable failure signal.
• openclaw status / doctor should flag when a package install's global root resolves to a git checkout/source tree.
• Post-update verification should assert the service entrypoint, package root, plugin sidecar roots, and reported install kind agree.

Impact

High for package-installed gateways: a later update/restart can fail hard because the service executes stale source-checkout code while the rest of the runtime expects the current npm package/plugin layout.