openclaw - 💡(How to fix) Fix [Feature]: Content-keyed bundled-runtime-deps cache (or env-var bypass) for multi-install-location setups [1 comments, 2 participants]

Summary

The bundled-runtime-deps cache directory under ~/.openclaw/plugin-runtime-deps/ (or $STATE_DIRECTORY/plugin-runtime-deps/) is keyed by openclaw-<version>-<sha256(realpath(packageRoot))[:12]>. This path-based keying breaks cache reuse for multi-install-location setups where the same openclaw version is installed at different absolute realpaths (production slot vs custom build vs source-checkout dev install).

In our setup, when we promote a verified-identical installation to a new on-disk location (a "slot" pattern with a current symlink), the path-keyed cache misses. prestageGatewayBundledRuntimeDeps then runs synchronously before the gateway HTTP listener opens, performing an npm install of all bundled deps for the new path. That install can take minutes for the multi-hundred-MB dependency tree (@aws-sdk/*, @google/genai, @grammyjs/*, etc), well beyond reasonable startup budgets.

Reproduction (in our environment, 2026.4.27)

1. openclaw is installed at /opt/.../node_modules/openclaw (real dir). First start populates ~/.openclaw/plugin-runtime-deps/openclaw-2026.4.27-c27ae31043c7/ (~1.2GB).
2. We cp -a the install to /var/.../installs/openclaw/slots/npm-2026.4.27/, then atomically swap lib/node_modules/openclaw → installs/openclaw/current → slots/npm-2026.4.27 (two-symlink chain).
3. On next restart, path.resolve(packageRoot) returns the slot's realpath. Cache key becomes openclaw-2026.4.27-39cf11acc292. That directory does not exist (or only contains partial state from prior failed attempts).
4. scanBundledPluginRuntimeDeps reports missing.length > 0. prestageGatewayBundledRuntimeDeps calls repairBundledRuntimeDepsInstallRootAsync which performs npm install synchronously — taking minutes — before the HTTP listener opens.
5. Smoke probes that hit /healthz with reasonable budgets (we use 120s) fail. We auto-rollback the migration.

Source pointers (2026.4.27 dist)

• Path-hash key: dist/bundled-runtime-root-D11Fl_T4.js:589

  function createPathHash(value) {
    return createHash("sha256").update(path.resolve(value)).digest("hex").slice(0, 12);
  }

• Pre-startup staging: dist/server.impl-BoLlD_Zm.js:4839 — prestageGatewayBundledRuntimeDeps
• The cache content is not path-specific in any load-bearing way:
  • scanBundledPluginRuntimeDeps's hasDependencySentinel checks for installed deps via node_modules/<dep>/package.json content. Content-based.
  • .openclaw-runtime-mirror.json per extension stores sourceRoot + sourceFingerprint. The fingerprint is content-based (sha256 of source files); a cp -a of a populated cache dir into a different keyed dir validates clean against the post-symlink-swap source path.
• Confirmed empirically: cp -a openclaw-VER-LIVEHASH/ openclaw-VER-SLOTHASH/ results in missing.length === 0 on next startup, and prestageGatewayBundledRuntimeDeps returns early without re-installing.

What we'd ideally like

Two options, in order of preference:

Option A — content-keyed cache

Replace createPathHash(realpath) with a hash of the package's content (e.g. sha256 of the bundled-plugin manifest or a stable subset of dist/extensions/*/package.json files). The same openclaw version installed at different paths but with byte-identical contents would share one cache directory. This eliminates the multi-install-location friction entirely.

Option B — env-var bypass

If full content-keying is too invasive, a simple opt-in env var (OPENCLAW_RUNTIME_DEPS_CACHE_KEY=<explicit-key> or OPENCLAW_RUNTIME_DEPS_CACHE_BY_VERSION=1) that overrides the path-based hash with a stable value — typically just <version> — would let setups like ours opt into version-only keying. Less universal but minimally invasive.

Workaround we currently use

In our migration script, we cp -a the live install's cache directory to the new slot's expected cache path before the symlink swap. This is correct (we verified it byte-by-byte) but adds ~30s-2min to the migration window and double-uses disk temporarily. We document it in our spec as an explicit step until upstream lands a sanctioned solution.

Why this matters beyond our setup

Multi-install-location patterns are common:

• Slot-based atomic upgrades (this issue's scenario)
• Source-build dev installs running alongside an npm-install prod
• Homebrew + npm side-by-side (reportedly hits #75250's adjacent symptom)
• Docker bind-mounts where the in-container path differs from the host path

In each case the cache pays a fresh-install cost on every install-path change, even when the content hasn't changed. Content-keying would naturally deduplicate.

Happy to PR a content-keyed implementation if there's interest. Want to confirm direction before investing in the change.