fix(nodes): stop advertising a disabled browser proxy (#103894)

steipete · web-flow · commit e1934d968e43 · 2026-07-10T20:06:53.000+01:00
* fix(nodes): hide disabled browser proxy capability

* chore: defer node fix changelog to release

* chore: ratchet plugin SDK surface budget
diff --git a/docs/plugins/sdk-entrypoints.md b/docs/plugins/sdk-entrypoints.md
@@ -144,6 +144,11 @@ export default definePluginEntry({
 - `configSchema` can be a function for lazy evaluation. OpenClaw resolves and
   memoizes the schema on first access, so expensive schema builders only run
   once.
+- A `nodeHostCommands` descriptor can define `isAvailable({ config, env })`.
+  Returning `false` omits that command and its capability from the headless
+  node's Gateway declaration. OpenClaw evaluates it against the node-local
+  startup config; command handlers should still validate availability when
+  invoked.
 
 ## `defineChannelPluginEntry`
 
diff --git a/extensions/browser/index.test.ts b/extensions/browser/index.test.ts
@@ -115,6 +115,19 @@ describe("browser plugin", () => {
     expect(browserPluginNodeHostCommands).toHaveLength(1);
     expect(browserPluginNodeHostCommands[0]?.command).toBe("browser.proxy");
     expect(browserPluginNodeHostCommands[0]?.cap).toBe("browser");
+    expect(browserPluginNodeHostCommands[0]?.isAvailable?.({ config: {}, env: {} })).toBe(true);
+    expect(
+      browserPluginNodeHostCommands[0]?.isAvailable?.({
+        config: { browser: { enabled: false } },
+        env: {},
+      }),
+    ).toBe(false);
+    expect(
+      browserPluginNodeHostCommands[0]?.isAvailable?.({
+        config: { nodeHost: { browserProxy: { enabled: false } } },
+        env: {},
+      }),
+    ).toBe(false);
     expect(typeof browserPluginNodeHostCommands[0]?.handle).toBe("function");
     expect(browserSecurityAuditCollectors).toHaveLength(1);
   });
diff --git a/extensions/browser/plugin-registration.ts b/extensions/browser/plugin-registration.ts
@@ -142,6 +142,8 @@ export const browserPluginNodeHostCommands: OpenClawPluginNodeHostCommand[] = [
   {
     command: "browser.proxy",
     cap: "browser",
+    isAvailable: ({ config }) =>
+      config.browser?.enabled !== false && config.nodeHost?.browserProxy?.enabled !== false,
     handle: async (paramsJSON) => {
       const { runBrowserProxyCommand } = await loadBrowserRegistrationRuntimeModule();
       return await runBrowserProxyCommand(paramsJSON);
diff --git a/scripts/plugin-sdk-surface-report.mjs b/scripts/plugin-sdk-surface-report.mjs
@@ -195,7 +195,7 @@ export function readPluginSdkSurfaceBudgets(env = process.env) {
     ),
     publicExports: readPluginSdkSurfaceBudgetEnv(
       "OPENCLAW_PLUGIN_SDK_MAX_PUBLIC_EXPORTS",
-      10490,
+      10492,
       env,
     ),
     publicFunctionExports: readPluginSdkSurfaceBudgetEnv(
diff --git a/src/node-host/plugin-node-host.test.ts b/src/node-host/plugin-node-host.test.ts
@@ -7,6 +7,8 @@ import {
   listRegisteredNodeHostCapsAndCommands,
 } from "./plugin-node-host.js";
 
+const availabilityContext = { config: {}, env: {} };
+
 afterEach(() => {
   resetPluginRuntimeStateForTest();
 });
@@ -48,12 +50,50 @@ describe("plugin node-host registry", () => {
     ];
     setActivePluginRegistry(registry);
 
-    expect(listRegisteredNodeHostCapsAndCommands()).toEqual({
+    expect(listRegisteredNodeHostCapsAndCommands(availabilityContext)).toEqual({
       caps: ["browser", "photos"],
       commands: ["browser.inspect", "browser.proxy", "photos.proxy"],
     });
   });
 
+  it("omits commands and capabilities unavailable in the node-local config", () => {
+    const registry = createEmptyPluginRegistry();
+    registry.nodeHostCommands = [
+      {
+        pluginId: "browser",
+        pluginName: "Browser",
+        command: {
+          command: "browser.proxy",
+          cap: "browser",
+          isAvailable: ({ config }) => config.browser?.enabled !== false,
+          handle: vi.fn(async () => "{}"),
+        },
+        source: "test",
+      },
+      {
+        pluginId: "photos",
+        pluginName: "Photos",
+        command: {
+          command: "photos.proxy",
+          cap: "photos",
+          handle: vi.fn(async () => "{}"),
+        },
+        source: "test",
+      },
+    ];
+    setActivePluginRegistry(registry);
+
+    expect(
+      listRegisteredNodeHostCapsAndCommands({
+        config: { browser: { enabled: false } },
+        env: {},
+      }),
+    ).toEqual({
+      caps: ["photos"],
+      commands: ["photos.proxy"],
+    });
+  });
+
   it("dispatches plugin-declared node-host commands", async () => {
     const handle = vi.fn(async (paramsJSON?: string | null) => paramsJSON ?? "");
     const registry = createEmptyPluginRegistry();
diff --git a/src/node-host/plugin-node-host.ts b/src/node-host/plugin-node-host.ts
@@ -6,6 +6,7 @@
  */
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { getActivePluginRegistry } from "../plugins/runtime.js";
+import type { OpenClawPluginNodeHostCommandAvailabilityContext } from "../plugins/types.js";
 import { createLazyRuntimeModule } from "../shared/lazy-runtime.js";
 
 const loadPluginRegistryLoaderModule = createLazyRuntimeModule(
@@ -26,14 +27,21 @@ export async function ensureNodeHostPluginRegistry(params: {
 }
 
 /** List registered node-host capabilities and command ids in deterministic order. */
-export function listRegisteredNodeHostCapsAndCommands(): {
+export function listRegisteredNodeHostCapsAndCommands(
+  context: OpenClawPluginNodeHostCommandAvailabilityContext,
+): {
   caps: string[];
   commands: string[];
 } {
   const registry = getActivePluginRegistry();
   const caps = new Set<string>();
   const commands = new Set<string>();
   for (const entry of registry?.nodeHostCommands ?? []) {
+    // Availability belongs to the node-local plugin. Gateway policy still keeps
+    // the command registered so a differently configured remote node can expose it.
+    if (entry.command.isAvailable?.(context) === false) {
+      continue;
+    }
     if (entry.command.cap) {
       caps.add(entry.command.cap);
     }
diff --git a/src/node-host/runner.ts b/src/node-host/runner.ts
@@ -255,7 +255,7 @@ export async function runNodeHost(opts: NodeHostRunOptions): Promise<void> {
 
   const cfg = getRuntimeConfig();
   await ensureNodeHostPluginRegistry({ config: cfg, env: process.env });
-  const pluginNodeHost = listRegisteredNodeHostCapsAndCommands();
+  const pluginNodeHost = listRegisteredNodeHostCapsAndCommands({ config: cfg, env: process.env });
   const { token, password } = await resolveNodeHostGatewayCredentials({
     config: cfg,
     env: process.env,
diff --git a/src/plugin-sdk/plugin-entry.ts b/src/plugin-sdk/plugin-entry.ts
@@ -27,6 +27,8 @@ export type OpenClawPluginHttpRouteHandler =
   import("../plugins/types.js").OpenClawPluginHttpRouteHandler;
 export type OpenClawPluginNodeHostCommand =
   import("../plugins/types.js").OpenClawPluginNodeHostCommand;
+export type OpenClawPluginNodeHostCommandAvailabilityContext =
+  import("../plugins/types.js").OpenClawPluginNodeHostCommandAvailabilityContext;
 export type OpenClawPluginNodeInvokePolicy =
   import("../plugins/types.js").OpenClawPluginNodeInvokePolicy;
 export type OpenClawPluginNodeInvokePolicyContext =
diff --git a/src/plugins/types.ts b/src/plugins/types.ts
@@ -2223,10 +2223,19 @@ export type OpenClawPluginReloadRegistration = {
   noopPrefixes?: string[];
 };
 
+export type OpenClawPluginNodeHostCommandAvailabilityContext = {
+  /** Node-local configuration used to build this host's Gateway declaration. */
+  config: OpenClawConfig;
+  /** Node-host process environment. */
+  env: NodeJS.ProcessEnv;
+};
+
 export type OpenClawPluginNodeHostCommand = {
   command: string;
   cap?: string;
   dangerous?: boolean;
+  /** Return false to omit this command and capability from the node declaration. */
+  isAvailable?: (context: OpenClawPluginNodeHostCommandAvailabilityContext) => boolean;
   handle: (paramsJSON?: string | null) => Promise<string>;
 };
 

Original file line number	Diff line number	Diff line change
`@@ -142,6 +142,8 @@ export const browserPluginNodeHostCommands: OpenClawPluginNodeHostCommand[] = [`
`142`	`142`	`{`
`143`	`143`	`command: "browser.proxy",`
`144`	`144`	`cap: "browser",`
	`145`	`+ isAvailable: ({ config }) =>`
	`146`	`+ config.browser?.enabled !== false && config.nodeHost?.browserProxy?.enabled !== false,`
`145`	`147`	`handle: async (paramsJSON) => {`
`146`	`148`	`const { runBrowserProxyCommand } = await loadBrowserRegistrationRuntimeModule();`
`147`	`149`	`return await runBrowserProxyCommand(paramsJSON);`