fix: clarify exec node routing guidance

Author: steipete

CHANGELOG.md

@@ -51,6 +51,7 @@ Docs: https://docs.openclaw.ai
 
 - Security: preserve restrictive plugin-only tool allowlists, require owner access for `/allowlist add` and `/allowlist remove`, fail closed when `before_tool_call` hooks crash, block browser SSRF redirect bypasses earlier, and keep non-interactive auth-choice inference scoped to bundled and already-trusted plugins. (#58476, #59836, #59822, #58771, #59120) Thanks @eleqtrizit and @pgondhi987.
 - Auto-reply: unify reply lifecycle ownership across preflight compaction, session rotation, CLI-backed runs, and gateway restart handling so `/stop` and same-session overlap checks target the right active turn and restart-interrupted turns return the restart notice instead of being silently dropped. (#61267) Thanks @dutifulbob.
+- Exec/remote skills: stop advertising `exec host=node` when the current exec policy cannot route to a node, and clarify blocked exec-host override errors with both the requested host and allowed config path.
 - Agents/Claude CLI/security: clear inherited Claude Code config-root and plugin-root env overrides like `CLAUDE_CONFIG_DIR` and `CLAUDE_CODE_PLUGIN_*`, so OpenClaw-launched Claude CLI runs cannot be silently pointed at an alternate Claude config/plugin tree with different hooks, plugins, or auth context. Thanks @vincentkoc.
 - Agents/Claude CLI/security: clear inherited Claude Code provider-routing and managed-auth env overrides, and mark OpenClaw-launched Claude CLI runs as host-managed, so Claude CLI backdoor sessions cannot be silently redirected to proxy, Bedrock, Vertex, Foundry, or parent-managed token contexts. Thanks @vincentkoc.
 - Agents/Claude CLI/security: force host-managed Claude CLI backdoor runs to `--setting-sources user`, even under custom backend arg overrides, so repo-local `.claude` project/local settings, hooks, and plugin discovery do not silently execute inside non-interactive OpenClaw sessions. Thanks @vincentkoc.

src/agents/agent-command.ts

@@ -65,6 +65,7 @@ import { updateSessionStoreAfterAgentRun } from "./command/session-store.js";
 import { resolveSession } from "./command/session.js";
 import type { AgentCommandIngressOpts, AgentCommandOpts } from "./command/types.js";
 import { DEFAULT_MODEL, DEFAULT_PROVIDER } from "./defaults.js";
+import { canExecRequestNode } from "./exec-defaults.js";
 import { AGENT_LANE_SUBAGENT } from "./lanes.js";
 import { LiveSessionModelSwitchError } from "./live-model-switch.js";
 import { loadModelCatalog } from "./model-catalog.js";
@@ -508,7 +509,16 @@ async function agentCommandInternal(
     const skillsSnapshot = needsSkillsSnapshot
       ? buildWorkspaceSkillSnapshot(workspaceDir, {
           config: cfg,
-          eligibility: { remote: getRemoteSkillEligibility() },
+          eligibility: {
+            remote: getRemoteSkillEligibility({
+              advertiseExecNode: canExecRequestNode({
+                cfg,
+                sessionEntry,
+                sessionKey,
+                agentId: sessionAgentId,
+              }),
+            }),
+          },
           snapshotVersion: skillsSnapshotVersion,
           skillFilter,
           agentId: sessionAgentId,

src/agents/bash-tools.exec-runtime.test.ts

@@ -126,7 +126,9 @@ describe("resolveExecTarget", () => {
         elevatedRequested: false,
         sandboxAvailable: true,
       }),
-    ).toThrow("exec host not allowed");
+    ).toThrow(
+      "exec host not allowed (requested gateway; configured host is auto; set tools.exec.host=gateway or auto to allow this override).",
+    );
   });
 
   it("allows per-call host=sandbox override when configured host is auto", () => {
@@ -153,7 +155,9 @@ describe("resolveExecTarget", () => {
         elevatedRequested: false,
         sandboxAvailable: false,
       }),
-    ).toThrow("exec host not allowed");
+    ).toThrow(
+      "exec host not allowed (requested gateway; configured host is node; set tools.exec.host=gateway or auto to allow this override).",
+    );
   });
 
   it("allows explicit auto request when configured host is auto", () => {
@@ -180,7 +184,9 @@ describe("resolveExecTarget", () => {
         elevatedRequested: false,
         sandboxAvailable: true,
       }),
-    ).toThrow("exec host not allowed");
+    ).toThrow(
+      "exec host not allowed (requested auto; configured host is gateway; set tools.exec.host=auto to allow this override).",
+    );
   });
 
   it("allows exact node matches", () => {

src/agents/bash-tools.exec-runtime.ts

@@ -259,9 +259,17 @@ export function resolveExecTarget(params: {
       sandboxAvailable: params.sandboxAvailable,
     })
   ) {
+    const allowedConfig = Array.from(
+      new Set(
+        requestedTarget === "gateway" && !params.sandboxAvailable
+          ? ["gateway", "auto"]
+          : [renderExecTargetLabel(requestedTarget), "auto"],
+      ),
+    ).join(" or ");
     throw new Error(
       `exec host not allowed (requested ${renderExecTargetLabel(requestedTarget)}; ` +
-        `configure tools.exec.host=${renderExecTargetLabel(requestedTarget)} to allow).`,
+        `configured host is ${renderExecTargetLabel(configuredTarget)}; ` +
+        `set tools.exec.host=${allowedConfig} to allow this override).`,
     );
   }
   const selectedTarget = requestedTarget ?? configuredTarget;

src/agents/exec-defaults.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from "vitest";
+import type { SessionEntry } from "../config/sessions.js";
+import { resolveExecDefaults } from "./exec-defaults.js";
+
+describe("resolveExecDefaults", () => {
+  it("does not advertise node routing when exec host is pinned to gateway", () => {
+    expect(
+      resolveExecDefaults({
+        cfg: {
+          tools: {
+            exec: {
+              host: "gateway",
+            },
+          },
+        },
+        sandboxAvailable: false,
+      }).canRequestNode,
+    ).toBe(false);
+  });
+
+  it("keeps node routing available when exec host is auto", () => {
+    expect(
+      resolveExecDefaults({
+        cfg: {
+          tools: {
+            exec: {
+              host: "auto",
+            },
+          },
+        },
+        sandboxAvailable: true,
+      }),
+    ).toMatchObject({
+      host: "auto",
+      effectiveHost: "sandbox",
+      canRequestNode: true,
+    });
+  });
+
+  it("honors session-level exec host overrides", () => {
+    const sessionEntry = {
+      execHost: "node",
+    } as SessionEntry;
+    expect(
+      resolveExecDefaults({
+        cfg: {
+          tools: {
+            exec: {
+              host: "gateway",
+            },
+          },
+        },
+        sessionEntry,
+        sandboxAvailable: false,
+      }).canRequestNode,
+    ).toBe(true);
+  });
+});

src/agents/exec-defaults.ts

@@ -0,0 +1,110 @@
+import type { OpenClawConfig } from "../config/config.js";
+import type { SessionEntry } from "../config/sessions.js";
+import type { ExecAsk, ExecHost, ExecSecurity, ExecTarget } from "../infra/exec-approvals.js";
+import { resolveAgentConfig, resolveSessionAgentId } from "./agent-scope.js";
+import { isRequestedExecTargetAllowed, resolveExecTarget } from "./bash-tools.exec-runtime.js";
+import { resolveSandboxRuntimeStatus } from "./sandbox/runtime-status.js";
+
+type ResolvedExecConfig = {
+  host?: ExecTarget;
+  security?: ExecSecurity;
+  ask?: ExecAsk;
+  node?: string;
+};
+
+function resolveExecConfigState(params: {
+  cfg?: OpenClawConfig;
+  sessionEntry?: SessionEntry;
+  agentId?: string;
+  sessionKey?: string;
+}): {
+  cfg: OpenClawConfig;
+  host: ExecTarget;
+  agentExec?: ResolvedExecConfig;
+  globalExec?: ResolvedExecConfig;
+} {
+  const cfg = params.cfg ?? {};
+  const resolvedAgentId =
+    params.agentId ??
+    resolveSessionAgentId({
+      sessionKey: params.sessionKey,
+      config: cfg,
+    });
+  const globalExec = cfg.tools?.exec;
+  const agentExec = resolvedAgentId
+    ? resolveAgentConfig(cfg, resolvedAgentId)?.tools?.exec
+    : undefined;
+  const host =
+    (params.sessionEntry?.execHost as ExecTarget | undefined) ??
+    (agentExec?.host as ExecTarget | undefined) ??
+    (globalExec?.host as ExecTarget | undefined) ??
+    "auto";
+  return {
+    cfg,
+    host,
+    agentExec,
+    globalExec,
+  };
+}
+
+export function canExecRequestNode(params: {
+  cfg?: OpenClawConfig;
+  sessionEntry?: SessionEntry;
+  agentId?: string;
+  sessionKey?: string;
+}): boolean {
+  const { host } = resolveExecConfigState(params);
+  return isRequestedExecTargetAllowed({
+    configuredTarget: host,
+    requestedTarget: "node",
+  });
+}
+
+export function resolveExecDefaults(params: {
+  cfg?: OpenClawConfig;
+  sessionEntry?: SessionEntry;
+  agentId?: string;
+  sessionKey?: string;
+  sandboxAvailable?: boolean;
+}): {
+  host: ExecTarget;
+  effectiveHost: ExecHost;
+  security: ExecSecurity;
+  ask: ExecAsk;
+  node?: string;
+  canRequestNode: boolean;
+} {
+  const { cfg, host, agentExec, globalExec } = resolveExecConfigState(params);
+  const sandboxAvailable =
+    params.sandboxAvailable ??
+    (params.sessionKey
+      ? resolveSandboxRuntimeStatus({
+          cfg,
+          sessionKey: params.sessionKey,
+        }).sandboxed
+      : false);
+  const resolved = resolveExecTarget({
+    configuredTarget: host,
+    elevatedRequested: false,
+    sandboxAvailable,
+  });
+  return {
+    host,
+    effectiveHost: resolved.effectiveHost,
+    security:
+      (params.sessionEntry?.execSecurity as ExecSecurity | undefined) ??
+      agentExec?.security ??
+      globalExec?.security ??
+      "deny",
+    ask:
+      (params.sessionEntry?.execAsk as ExecAsk | undefined) ??
+      agentExec?.ask ??
+      globalExec?.ask ??
+      "on-miss",
+    node: params.sessionEntry?.execNode ?? agentExec?.node ?? globalExec?.node,
+    canRequestNode: isRequestedExecTargetAllowed({
+      configuredTarget: host,
+      requestedTarget: "node",
+    }),
+  };
+}

src/agents/sandbox/context.ts

@@ -9,6 +9,7 @@ import {
 import { DEFAULT_BROWSER_EVALUATE_ENABLED } from "../../plugin-sdk/browser-profiles.js";
 import { defaultRuntime } from "../../runtime.js";
 import { resolveUserPath } from "../../utils.js";
+import { canExecRequestNode } from "../exec-defaults.js";
 import { syncSkillsToWorkspace } from "../skills.js";
 import { DEFAULT_AGENT_WORKSPACE_DIR } from "../workspace.js";
 import { requireSandboxBackendFactory } from "./backend.js";
@@ -58,7 +59,15 @@ async function ensureSandboxWorkspaceLayout(params: {
           targetWorkspaceDir: sandboxWorkspaceDir,
           config: params.config,
           agentId: params.agentId,
-          eligibility: { remote: getRemoteSkillEligibility() },
+          eligibility: {
+            remote: getRemoteSkillEligibility({
+              advertiseExecNode: canExecRequestNode({
+                cfg: params.config,
+                sessionKey: rawSessionKey,
+                agentId: params.agentId,
+              }),
+            }),
+          },
         });
       } catch (error) {
         const message = error instanceof Error ? error.message : JSON.stringify(error);

src/auto-reply/reply/commands-system-prompt.test.ts

@@ -25,6 +25,7 @@ vi.mock("../../agents/skills/refresh.js", () => ({
 }));
 
 vi.mock("../../agents/agent-scope.js", () => ({
+  resolveAgentConfig: vi.fn(() => undefined),
   resolveSessionAgentIds: vi.fn(() => ({ sessionAgentId: "main" })),
 }));
 

src/auto-reply/reply/commands-system-prompt.ts

@@ -1,6 +1,7 @@
 import type { AgentTool } from "@mariozechner/pi-agent-core";
 import { resolveSessionAgentIds } from "../../agents/agent-scope.js";
 import { resolveBootstrapContextForRun } from "../../agents/bootstrap-files.js";
+import { canExecRequestNode } from "../../agents/exec-defaults.js";
 import { resolveDefaultModelForAgent } from "../../agents/model-selection.js";
 import type { EmbeddedContextFile } from "../../agents/pi-embedded-helpers.js";
 import { createOpenClawCodingTools } from "../../agents/pi-tools.js";
@@ -38,23 +39,32 @@ export async function resolveCommandsSystemPromptBundle(
     sessionKey: params.sessionKey,
     sessionId: params.sessionEntry?.sessionId,
   });
+  const sandboxRuntime = resolveSandboxRuntimeStatus({
+    cfg: params.cfg,
+    sessionKey: params.ctx.SessionKey ?? params.sessionKey,
+  });
   const skillsSnapshot = (() => {
     try {
       return buildWorkspaceSkillSnapshot(workspaceDir, {
         config: params.cfg,
         agentId: sessionAgentId,
-        eligibility: { remote: getRemoteSkillEligibility() },
+        eligibility: {
+          remote: getRemoteSkillEligibility({
+            advertiseExecNode: canExecRequestNode({
+              cfg: params.cfg,
+              sessionEntry: params.sessionEntry,
+              sessionKey: params.sessionKey,
+              agentId: sessionAgentId,
+            }),
+          }),
+        },
         snapshotVersion: getSkillsSnapshotVersion(workspaceDir),
       });
     } catch {
       return { prompt: "", skills: [], resolvedSkills: [] };
     }
   })();
   const skillsPrompt = skillsSnapshot.prompt ?? "";
-  const sandboxRuntime = resolveSandboxRuntimeStatus({
-    cfg: params.cfg,
-    sessionKey: params.ctx.SessionKey ?? params.sessionKey,
-  });
   const tools = (() => {
     try {
       return createOpenClawCodingTools({