PR #70852: fix(plugins): stage bundled-plugin runtime-dep install outside the plugin root

• Repository: openclaw/openclaw
• Author: simonemacario
• State: closed | merged: True
• Link: https://github.com/openclaw/openclaw/pull/70852

Description (problem / solution / changelog)

Summary

Fixes gateway-startup plugin-runtime-dep install failure on packaged (Docker image, npm global) installs of 2026.4.22 where every bundled plugin whose package.json still contains a workspace:* dep fails with:

npm error code EUNSUPPORTEDPROTOCOL
npm error Unsupported URL Type "workspace:": workspace:*

Reported in #70844 (Docker image, EUNSUPPORTEDPROTOCOL at install step); same root cause as #70701, #70756, #70773, #70818, #70839 (npm global, downstream Cannot find package 'openclaw' from plugin-runtime-deps/… at ESM import).

Root cause

ensureBundledPluginRuntimeDeps in src/plugins/bundled-runtime-deps.ts already filters workspace: specs from the CLI argument list (normalizeInstallableRuntimeDepVersion, parseInstallableRuntimeDep). But the install step is spawnSync("npm", ["install", ...specs], { cwd: installExecutionRoot }), and installExecutionRoot defaults to installRoot. When installRoot === pluginRoot (the packaged case where the plugin dir is writable and no external stage is configured), npm reads the plugin's own package.json as the project manifest and tries to resolve its workspace:* deps — failing the whole batch regardless of what was passed on the CLI.

Evidence: upstream/main carries workspace:* declarations in 106 extensions/*/package.json (predominantly "@openclaw/plugin-sdk": "workspace:*"). The 18 plugins that fail in the Docker repro are exactly the subset that declare such entries as runtime deps (dependencies / optionalDependencies).

The npm-global variants in #70701 / #70756 / #70773 / #70818 / #70839 hit a related but different surface: resolveBundledRuntimeDependencyInstallRoot resolves to an external stage dir (clean manifest), so npm install succeeds but the resulting node_modules/ tree does not satisfy the filtered-out workspace packages, and the subsequent ESM import of openclaw fails at plugin load. Same defect class, different failure point.

Fix

Activate the existing isolated-execution-root + replaceNodeModulesDir machinery for the packaged case too. When installRoot === pluginRoot and we are not in the source-checkout cache-dir path, stage the install inside <installRoot>/.openclaw-install-stage (minimal generated package.json) and move the produced node_modules/ back to the plugin root as before.

+const isPluginRootInstall =
+  path.resolve(installRoot) === path.resolve(params.pluginRoot);
+const sourceCheckoutCacheStage =
+  cacheDir &&
+  isPluginRootInstall &&
+  resolveSourceCheckoutBundledPluginPackageRoot(params.pluginRoot)
+    ? cacheDir
+    : undefined;
 const installExecutionRoot =
-  cacheDir &&
-  path.resolve(installRoot) === path.resolve(params.pluginRoot) &&
-  resolveSourceCheckoutBundledPluginPackageRoot(params.pluginRoot)
-    ? cacheDir
-    : undefined;
+  sourceCheckoutCacheStage ??
+  (isPluginRootInstall ? path.join(installRoot, PLUGIN_ROOT_INSTALL_STAGE_DIR) : undefined);

No change to the existing workspace: filter, no new surface, no change to external stage or source-checkout semantics.

Shape note

@steipete flagged in #70138 that runtime-dep repair belongs at gateway/plugin startup (not npm pack postinstall). This change keeps that contract — it only widens when the existing stage/move is activated; the repair still runs through ensureBundledPluginRuntimeDeps called from src/plugins/loader.ts:2190. It does not reintroduce the eager-install shape that was closed in #70650.

Validation

• pnpm exec vitest run --config test/vitest/vitest.plugins.config.ts src/plugins/bundled-runtime-deps.test.ts — 31/31 (includes 1 new regression test: stages plugin-root install when the plugin's own package.json declares workspace:* deps)
• pnpm exec vitest run --config test/vitest/vitest.plugins.config.ts src/plugins/ — 43/43 across 8 test files
• pnpm exec tsgo --noEmit -p tsconfig.core.json — clean
• pnpm exec tsgo --noEmit -p tsconfig.core.test.json — clean
• pnpm exec oxlint src/plugins/bundled-runtime-deps.ts src/plugins/bundled-runtime-deps.test.ts — 0 warnings, 0 errors
• node scripts/check-src-extension-import-boundary.mjs --json — []
• node scripts/check-sdk-package-extension-import-boundary.mjs --json — []

I did not run codex review --base origin/main because I do not have Codex CLI access locally; happy to run Codex review in a later iteration if a maintainer provides guidance.

Test plan

• Build ghcr.io/openclaw/openclaw:<this-branch> and verify gateway startup against an existing ~/.openclaw that was pre-populated from 2026.4.15, reproducing the repro in #70844 from a clean state.
• Smoke: verify <pluginRoot>/node_modules/ is populated after gateway start and the .openclaw-install-stage/ sub-directory is cleaned up / idempotent across restarts.
• Spot-check that source-checkout dev flow (pnpm dev in the monorepo) still uses the cache-dir stage (not .openclaw-install-stage/) so no regression on contributor ergonomics.
• Cross-check with reporters on #70701 / #70756 / #70773 / #70818 / #70839 that the downstream Cannot find package 'openclaw' symptom also resolves.

AI assistance

This PR was AI-assisted with Claude Code (Opus 4.7). All code paths changed here were read end-to-end by me; the diagnosis against src/plugins/loader.ts:2190 and src/plugins/bundled-runtime-deps.ts is documented in the linked issue #70844 comment thread.

Testing degree: fully tested for the touched bundled-plugin runtime-dep install-staging surface.

I understand the code path changed here: packaged bundled plugins now stage their runtime-dep install one directory below pluginRoot so npm never reads the plugin's workspace:*-containing manifest during install; the existing replaceNodeModulesDir helper moves the produced node_modules/ back to pluginRoot after install succeeds.

Closes #70844

Changed files

• CHANGELOG.md (modified, +1/-1)
• scripts/e2e/bundled-channel-runtime-deps-docker.sh (modified, +2/-1)
• src/plugins/bundled-runtime-deps.test.ts (modified, +96/-0)
• src/plugins/bundled-runtime-deps.ts (modified, +69/-34)
• src/plugins/loader.test.ts (modified, +34/-27)
• src/plugins/loader.ts (modified, +2/-1)