From 1ff1fbe6824b41f331a87361263ef69fbfbf7c25 Mon Sep 17 00:00:00 2001
From: "clawsweeper[bot]" <274271284+clawsweeper[bot]@users.noreply.github.com>
Date: Wed, 29 Apr 2026 22:28:15 -0700
Subject: [PATCH] fix(plugins): honor runtime deps fallback install option

Co-authored-by: openclaw-clawsweeper[bot] <280122609+openclaw-clawsweeper[bot]@users.noreply.github.com>
---
 .../capability-provider-runtime.test.ts       | 32 +++++++++++--
 src/plugins/capability-provider-runtime.ts    | 48 +++++++++++--------
 2 files changed, 56 insertions(+), 24 deletions(-)

diff --git a/src/plugins/capability-provider-runtime.test.ts b/src/plugins/capability-provider-runtime.test.ts
index be4dbfeb770..b6b0d1ad96c 100644
--- a/src/plugins/capability-provider-runtime.test.ts
+++ b/src/plugins/capability-provider-runtime.test.ts
@@ -103,7 +103,6 @@ function expectBundledCompatLoadPath(params: {
     config: params.enablementCompat,
     onlyPluginIds: ["openai"],
     activate: false,
-    installBundledRuntimeDeps: false,
   });
 }
 
@@ -409,7 +408,6 @@ describe("resolvePluginCapabilityProviders", () => {
       }),
       onlyPluginIds: ["microsoft"],
       activate: false,
-      installBundledRuntimeDeps: false,
     });
   });
 
@@ -584,7 +582,6 @@ describe("resolvePluginCapabilityProviders", () => {
       config: expect.anything(),
       onlyPluginIds: [],
       activate: false,
-      installBundledRuntimeDeps: false,
     });
   });
 
@@ -629,6 +626,33 @@ describe("resolvePluginCapabilityProviders", () => {
       config: compatConfig,
       onlyPluginIds: ["google"],
       activate: false,
+    });
+  });
+
+  it("honors explicit bundled runtime dependency install opt-out for fallback snapshots", () => {
+    const cfg = { plugins: { allow: ["custom-plugin"] } } as OpenClawConfig;
+    const enablementCompat = {
+      plugins: {
+        allow: ["custom-plugin", "openai"],
+        entries: { openai: { enabled: true } },
+      },
+    };
+    setBundledCapabilityFixture("mediaUnderstandingProviders");
+    mocks.withBundledPluginEnablementCompat.mockReturnValue(enablementCompat);
+    mocks.withBundledPluginVitestCompat.mockReturnValue(enablementCompat);
+
+    expectNoResolvedCapabilityProviders(
+      resolvePluginCapabilityProviders({
+        key: "mediaUnderstandingProviders",
+        cfg,
+        installBundledRuntimeDeps: false,
+      }),
+    );
+
+    expect(mocks.resolveRuntimePluginRegistry).toHaveBeenCalledWith({
+      config: enablementCompat,
+      onlyPluginIds: ["openai"],
+      activate: false,
       installBundledRuntimeDeps: false,
     });
   });
@@ -653,7 +677,6 @@ describe("resolvePluginCapabilityProviders", () => {
       config: expect.anything(),
       onlyPluginIds: [],
       activate: false,
-      installBundledRuntimeDeps: false,
     });
   });
 
@@ -791,7 +814,6 @@ describe("resolvePluginCapabilityProviders", () => {
       config: enablementCompat,
       onlyPluginIds: ["google"],
       activate: false,
-      installBundledRuntimeDeps: false,
     });
   });
 });
diff --git a/src/plugins/capability-provider-runtime.ts b/src/plugins/capability-provider-runtime.ts
index 548847f0130..96a5cff82a6 100644
--- a/src/plugins/capability-provider-runtime.ts
+++ b/src/plugins/capability-provider-runtime.ts
@@ -4,7 +4,7 @@ import {
   withBundledPluginEnablementCompat,
   withBundledPluginVitestCompat,
 } from "./bundled-compat.js";
-import { resolveRuntimePluginRegistry } from "./loader.js";
+import { resolveRuntimePluginRegistry, type PluginLoadOptions } from "./loader.js";
 import { loadPluginManifestRegistryForPluginRegistry } from "./plugin-registry.js";
 import type { PluginRegistry } from "./registry-types.js";
 
@@ -85,6 +85,22 @@ function resolveCapabilityProviderConfig(params: {
   });
 }
 
+function createCapabilityProviderFallbackLoadOptions(params: {
+  compatConfig?: OpenClawConfig;
+  pluginIds: string[];
+  installBundledRuntimeDeps?: boolean;
+}): PluginLoadOptions {
+  const loadOptions: PluginLoadOptions = {
+    ...(params.compatConfig === undefined ? {} : { config: params.compatConfig }),
+    onlyPluginIds: params.pluginIds,
+    activate: false,
+  };
+  if (params.installBundledRuntimeDeps === false) {
+    loadOptions.installBundledRuntimeDeps = false;
+  }
+  return loadOptions;
+}
+
 function findProviderById<K extends CapabilityProviderRegistryKey>(
   entries: PluginRegistry[K],
   providerId: string,
@@ -203,6 +219,7 @@ export function resolvePluginCapabilityProvider<K extends CapabilityProviderRegi
   key: K;
   providerId: string;
   cfg?: OpenClawConfig;
+  installBundledRuntimeDeps?: boolean;
 }): CapabilityProviderForKey<K> | undefined {
   const activeRegistry = resolveRuntimePluginRegistry();
   const activeProvider = findProviderById(activeRegistry?.[params.key] ?? [], params.providerId);
@@ -224,15 +241,11 @@ export function resolvePluginCapabilityProvider<K extends CapabilityProviderRegi
     cfg: params.cfg,
     pluginIds,
   });
-  const loadOptions =
-    compatConfig === undefined
-      ? { onlyPluginIds: pluginIds, activate: false, installBundledRuntimeDeps: false }
-      : {
-          config: compatConfig,
-          onlyPluginIds: pluginIds,
-          activate: false,
-          installBundledRuntimeDeps: false,
-        };
+  const loadOptions = createCapabilityProviderFallbackLoadOptions({
+    compatConfig,
+    pluginIds,
+    installBundledRuntimeDeps: params.installBundledRuntimeDeps,
+  });
   const registry = resolveRuntimePluginRegistry(loadOptions);
   return findProviderById(registry?.[params.key] ?? [], params.providerId);
 }
@@ -240,6 +253,7 @@ export function resolvePluginCapabilityProvider<K extends CapabilityProviderRegi
 export function resolvePluginCapabilityProviders<K extends CapabilityProviderRegistryKey>(params: {
   key: K;
   cfg?: OpenClawConfig;
+  installBundledRuntimeDeps?: boolean;
 }): CapabilityProviderForKey<K>[] {
   const activeRegistry = resolveRuntimePluginRegistry();
   const activeProviders = activeRegistry?.[params.key] ?? [];
@@ -272,15 +286,11 @@ export function resolvePluginCapabilityProviders<K extends CapabilityProviderReg
     cfg: params.cfg,
     pluginIds,
   });
-  const loadOptions =
-    compatConfig === undefined
-      ? { onlyPluginIds: pluginIds, activate: false, installBundledRuntimeDeps: false }
-      : {
-          config: compatConfig,
-          onlyPluginIds: pluginIds,
-          activate: false,
-          installBundledRuntimeDeps: false,
-        };
+  const loadOptions = createCapabilityProviderFallbackLoadOptions({
+    compatConfig,
+    pluginIds,
+    installBundledRuntimeDeps: params.installBundledRuntimeDeps,
+  });
   const registry = resolveRuntimePluginRegistry(loadOptions);
   const loadedProviders = registry?.[params.key] ?? [];
   if (params.key !== "memoryEmbeddingProviders") {