fix(plugins): narrow optional tool cold loads

steipete · steipete · commit baadd74b6bb5 · 2026-05-04T00:41:01.000+01:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -72,7 +72,7 @@ Docs: https://docs.openclaw.ai
 - Doctor/plugins: reset stale `plugins.slots.memory` and `plugins.slots.contextEngine` references during `doctor --fix`, so cleanup of missing plugin config does not leave unrecoverable slot owners behind. Fixes #76550 and #76551. Thanks @vincentkoc.
 - Docs/WhatsApp: merge the duplicate top-level `web` objects in the gateway channel config example so copy-pasted WhatsApp config keeps both `web.whatsapp` and reconnect settings. Fixes #76619. Thanks @WadydX.
 - Plugins/Anthropic: expose Claude thinking profiles from the bundled provider-policy artifact so non-runtime callers keep Opus 4.7 `adaptive`, `xhigh`, and `max` instead of downgrading to `high`. Fixes #76779. Thanks @tomascupr and @iAbhi001.
-- Plugins/tools: honor `tools.alsoAllow` as an optional plugin tool discovery hint without treating its internal allow-all default as permission to load every optional plugin tool. Fixes #76616.
+- Plugins/tools: honor `tools.alsoAllow` as an optional plugin tool discovery hint without treating its internal allow-all default as permission to load every manifest-marked optional plugin tool. Fixes #76616.
 - Discord/native commands: skip slash-command registration and cleanup REST calls when `channels.discord.commands.native=false`, letting low-power gateways start without waiting on disabled native-command lifecycle requests. Fixes #76202. Thanks @vincentkoc.
 - CLI/plugins: reject unowned command roots such as `openclaw foo` before managed proxy startup and full plugin CLI runtime loading while preserving manifest-owned and CLI-metadata-owned plugin commands. Fixes #75287. Thanks @neilofneils404.
 - CLI/message: skip local configured-channel plugin preload for explicit gateway-owned message actions, letting normalized CLI delivery delegate to the gateway without initializing channel runtime in the short-lived CLI process. Fixes #75477.
diff --git a/docs/plugins/building-plugins.md b/docs/plugins/building-plugins.md
@@ -252,6 +252,11 @@ plugin manifest:
 {
   "contracts": {
     "tools": ["my_tool", "workflow_tool"]
+  },
+  "toolMetadata": {
+    "workflow_tool": {
+      "optional": true
+    }
   }
 }
 ```
@@ -260,6 +265,9 @@ OpenClaw captures and caches the validated descriptor from the registered tool,
 so plugins do not duplicate `description` or schema data in the manifest. The
 manifest contract only declares ownership and discovery; execution still calls
 the live registered tool implementation.
+Set `toolMetadata.<tool>.optional: true` for tools registered with
+`api.registerTool(..., { optional: true })` so OpenClaw can avoid loading that
+plugin runtime until the tool is explicitly allowlisted.
 
 Users enable optional tools in config:
 
diff --git a/extensions/diffs/openclaw.plugin.json b/extensions/diffs/openclaw.plugin.json
@@ -8,6 +8,11 @@
   "contracts": {
     "tools": ["diffs"]
   },
+  "toolMetadata": {
+    "diffs": {
+      "optional": true
+    }
+  },
   "skills": ["./skills"],
   "uiHints": {
     "viewerBaseUrl": {
diff --git a/extensions/llm-task/openclaw.plugin.json b/extensions/llm-task/openclaw.plugin.json
@@ -8,6 +8,11 @@
   "contracts": {
     "tools": ["llm-task"]
   },
+  "toolMetadata": {
+    "llm-task": {
+      "optional": true
+    }
+  },
   "configSchema": {
     "type": "object",
     "additionalProperties": false,
diff --git a/extensions/lobster/openclaw.plugin.json b/extensions/lobster/openclaw.plugin.json
@@ -8,6 +8,11 @@
   "contracts": {
     "tools": ["lobster"]
   },
+  "toolMetadata": {
+    "lobster": {
+      "optional": true
+    }
+  },
   "configSchema": {
     "type": "object",
     "additionalProperties": false,
diff --git a/src/plugins/manifest-registry.test.ts b/src/plugins/manifest-registry.test.ts
@@ -1382,6 +1382,7 @@ describe("loadPluginManifestRegistry", () => {
       },
       toolMetadata: {
         image_generate: {
+          optional: true,
           authSignals: [
             {
               provider: "openai-codex",
@@ -1450,6 +1451,7 @@ describe("loadPluginManifestRegistry", () => {
     });
     expect(registry.plugins[0]?.toolMetadata).toEqual({
       image_generate: {
+        optional: true,
         authSignals: [
           {
             provider: "openai-codex",
diff --git a/src/plugins/manifest-tool-availability.ts b/src/plugins/manifest-tool-availability.ts
@@ -215,6 +215,10 @@ function toolMetadataPasses(params: {
   env: NodeJS.ProcessEnv;
   hasAuthForProvider?: (providerId: string) => boolean;
 }): boolean {
+  const authSignals = listToolAuthSignals(params.metadata);
+  if (!params.metadata.configSignals?.length && authSignals.length === 0) {
+    return true;
+  }
   if (
     params.metadata.configSignals?.some((signal) =>
       manifestConfigSignalPasses({
@@ -226,7 +230,7 @@ function toolMetadataPasses(params: {
   ) {
     return true;
   }
-  for (const signal of listToolAuthSignals(params.metadata)) {
+  for (const signal of authSignals) {
     if (
       !manifestProviderBaseUrlGuardPasses({
         config: params.config,
diff --git a/src/plugins/manifest.ts b/src/plugins/manifest.ts
@@ -458,7 +458,9 @@ export type PluginManifestCapabilityProviderMetadata = {
   configSignals?: PluginManifestCapabilityProviderConfigSignal[];
 };
 
-export type PluginManifestToolMetadata = PluginManifestCapabilityProviderMetadata;
+export type PluginManifestToolMetadata = PluginManifestCapabilityProviderMetadata & {
+  optional?: boolean;
+};
 
 export type PluginManifestProviderAuthChoice = {
   /** Provider id owned by this manifest entry. */
@@ -715,6 +717,22 @@ function normalizeCapabilityProviderConfigSignals(
   return signals.length > 0 ? signals : undefined;
 }
 
+function normalizeCapabilityProviderMetadataEntry(
+  rawMetadata: Record<string, unknown>,
+): PluginManifestCapabilityProviderMetadata | undefined {
+  const aliases = normalizeTrimmedStringList(rawMetadata.aliases);
+  const authProviders = normalizeTrimmedStringList(rawMetadata.authProviders);
+  const authSignals = normalizeCapabilityProviderAuthSignals(rawMetadata.authSignals);
+  const configSignals = normalizeCapabilityProviderConfigSignals(rawMetadata.configSignals);
+  const metadata = {
+    ...(aliases.length > 0 ? { aliases } : {}),
+    ...(authProviders.length > 0 ? { authProviders } : {}),
+    ...(authSignals ? { authSignals } : {}),
+    ...(configSignals ? { configSignals } : {}),
+  } satisfies PluginManifestCapabilityProviderMetadata;
+  return Object.keys(metadata).length > 0 ? metadata : undefined;
+}
+
 function normalizeCapabilityProviderMetadata(
   value: unknown,
 ): Record<string, PluginManifestCapabilityProviderMetadata> | undefined {
@@ -727,18 +745,33 @@ function normalizeCapabilityProviderMetadata(
     if (!providerId || isBlockedObjectKey(providerId) || !isRecord(rawMetadata)) {
       continue;
     }
-    const aliases = normalizeTrimmedStringList(rawMetadata.aliases);
-    const authProviders = normalizeTrimmedStringList(rawMetadata.authProviders);
-    const authSignals = normalizeCapabilityProviderAuthSignals(rawMetadata.authSignals);
-    const configSignals = normalizeCapabilityProviderConfigSignals(rawMetadata.configSignals);
+    const metadata = normalizeCapabilityProviderMetadataEntry(rawMetadata);
+    if (metadata) {
+      normalized[providerId] = metadata;
+    }
+  }
+  return Object.keys(normalized).length > 0 ? normalized : undefined;
+}
+
+function normalizePluginToolMetadata(
+  value: unknown,
+): Record<string, PluginManifestToolMetadata> | undefined {
+  if (!isRecord(value)) {
+    return undefined;
+  }
+  const normalized: Record<string, PluginManifestToolMetadata> = Object.create(null);
+  for (const [rawToolName, rawMetadata] of Object.entries(value)) {
+    const toolName = normalizeOptionalString(rawToolName) ?? "";
+    if (!toolName || isBlockedObjectKey(toolName) || !isRecord(rawMetadata)) {
+      continue;
+    }
+    const providerMetadata = normalizeCapabilityProviderMetadataEntry(rawMetadata);
     const metadata = {
-      ...(aliases.length > 0 ? { aliases } : {}),
-      ...(authProviders.length > 0 ? { authProviders } : {}),
-      ...(authSignals ? { authSignals } : {}),
-      ...(configSignals ? { configSignals } : {}),
-    } satisfies PluginManifestCapabilityProviderMetadata;
+      ...providerMetadata,
+      ...(rawMetadata.optional === true ? { optional: true } : {}),
+    } satisfies PluginManifestToolMetadata;
     if (Object.keys(metadata).length > 0) {
-      normalized[providerId] = metadata;
+      normalized[toolName] = metadata;
     }
   }
   return Object.keys(normalized).length > 0 ? normalized : undefined;
@@ -1596,7 +1629,7 @@ export function loadPluginManifest(
   const musicGenerationProviderMetadata = normalizeCapabilityProviderMetadata(
     raw.musicGenerationProviderMetadata,
   );
-  const toolMetadata = normalizeCapabilityProviderMetadata(raw.toolMetadata);
+  const toolMetadata = normalizePluginToolMetadata(raw.toolMetadata);
   const configContracts = normalizeManifestConfigContracts(raw.configContracts);
   const channelConfigs = normalizeChannelConfigs(raw.channelConfigs);
 
diff --git a/src/plugins/tools.optional.test.ts b/src/plugins/tools.optional.test.ts
diff --git a/src/plugins/tools.ts b/src/plugins/tools.ts

Original file line number	Diff line number	Diff line change
`@@ -252,6 +252,11 @@ plugin manifest:`
`252`	`252`	`{`
`253`	`253`	`"contracts": {`
`254`	`254`	`"tools": ["my_tool", "workflow_tool"]`
	`255`	`+ },`
	`256`	`+ "toolMetadata": {`
	`257`	`+ "workflow_tool": {`
	`258`	`+ "optional": true`
	`259`	`+ }`
`255`	`260`	`}`
`256`	`261`	`}`
`257`	`262`	```
`@@ -260,6 +265,9 @@ OpenClaw captures and caches the validated descriptor from the registered tool,`
`260`	`265`	so plugins do not duplicate `description` or schema data in the manifest. The
`261`	`266`	`manifest contract only declares ownership and discovery; execution still calls`
`262`	`267`	`the live registered tool implementation.`
	`268`	+Set `toolMetadata.<tool>.optional: true` for tools registered with
	`269`	+`api.registerTool(..., { optional: true })` so OpenClaw can avoid loading that
	`270`	`+plugin runtime until the tool is explicitly allowlisted.`
`263`	`271`
`264`	`272`	`Users enable optional tools in config:`
`265`	`273`