fix(exec): protect pathPrepend against posix login-shell RC overrides (#81403)

medns · odysseus0 · web-flow · commit b77f36fb1cbd · 2026-05-21T13:19:41.000-07:00
Merged via squash. Prepared head SHA: 874fa90 Co-authored-by: medns <1575008+medns@users.noreply.github.com> Co-authored-by: odysseus0 <8635094+odysseus0@users.noreply.github.com> Reviewed-by: @odysseus0
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -53,6 +53,7 @@ Docs: https://docs.openclaw.ai
 - Auth/OAuth: skip the refresh adapter when a stored OAuth credential has no refresh token so agent turns fail fast on missing-key instead of waiting on the 120s refresh timeout. Thanks @romneyda.
 - Auth/Codex: load legacy OAuth sidecar credentials in the embedded runner's secrets-runtime auth loaders so Telegram replies, cron-triggered turns, and other isolated sub-agent lanes can reach the existing #83312 refresh-and-rewrite migration instead of failing with `No API key found for provider "openai-codex"` until the user runs `openclaw doctor`. Thanks @Totalsolutionsync and @romneyda.
 - Codex/failover: classify `deactivated_workspace` as a permanent auth failure so configured fallback models can advance when a Codex workspace is deactivated. (#55893) Thanks @litang9.
+- Exec: keep configured `tools.exec.pathPrepend` entries ahead of user shell startup PATH changes on POSIX gateway runs. (#81403) Thanks @medns.
 
 ## 2026.5.20
 
diff --git a/docs/tools/exec.md b/docs/tools/exec.md
@@ -133,6 +133,7 @@ Example:
   rejected for host execution. The daemon itself still runs with a minimal `PATH`:
   - macOS: `/opt/homebrew/bin`, `/usr/local/bin`, `/usr/bin`, `/bin`
   - Linux: `/usr/local/bin`, `/usr/bin`, `/bin`
+    - To prevent user shell configuration (like `~/.zshenv` or `/etc/zshenv`) from overriding priority paths during startup, `tools.exec.pathPrepend` entries are securely prepended to the final `PATH` inside the shell command right before execution.
 - `host=sandbox`: runs `sh -lc` (login shell) inside the container, so `/etc/profile` may reset `PATH`.
   OpenClaw prepends `env.PATH` after profile sourcing via an internal env var (no shell interpolation);
   `tools.exec.pathPrepend` applies here too.
diff --git a/src/agents/bash-tools.exec-host-gateway.ts b/src/agents/bash-tools.exec-host-gateway.ts
@@ -52,6 +52,7 @@ export type ProcessGatewayAllowlistParams = {
   command: string;
   workdir: string;
   env: Record<string, string>;
+  pathPrepend?: string[];
   requestedEnv?: Record<string, string>;
   pty: boolean;
   timeoutSec?: number;
@@ -663,6 +664,7 @@ export async function processGatewayAllowlist(
           execCommand: enforcedCommand,
           workdir: params.workdir,
           env: params.env,
+          pathPrepend: params.pathPrepend,
           sandbox: undefined,
           containerWorkdir: null,
           usePty: params.pty,
diff --git a/src/agents/bash-tools.exec-runtime.test.ts b/src/agents/bash-tools.exec-runtime.test.ts
@@ -687,3 +687,88 @@ describe("buildExecExitOutcome", () => {
     expect(outcome.reason).toContain("Do not rely on shell backgrounding");
   });
 });
+
+describe("runExecProcess POSIX command wrapper", () => {
+  it("wraps command with PATH export if OPENCLAW_PREPEND_PATH is present", async () => {
+    if (process.platform === "win32") {
+      return;
+    }
+
+    supervisorMock.spawn.mockResolvedValueOnce({
+      runId: "mock-run",
+      startedAtMs: Date.now(),
+      wait: async () => ({
+        reason: "exit",
+        exitCode: 0,
+        exitSignal: null,
+        durationMs: 0,
+        stdout: "",
+        stderr: "",
+        timedOut: false,
+        noOutputTimedOut: false,
+      }),
+      cancel: vi.fn(),
+    });
+
+    const run = await runExecProcess({
+      command: "echo test",
+      workdir: "/tmp",
+      env: { PATH: "/usr/bin" },
+      pathPrepend: ["/custom/bin", "/opt/bin"],
+      usePty: false,
+      warnings: [],
+      maxOutput: 1000,
+      pendingMaxOutput: 1000,
+      notifyOnExit: false,
+      timeoutSec: null,
+    });
+
+    expect(supervisorMock.spawn).toHaveBeenCalledTimes(1);
+    const spawnCall = supervisorMock.spawn.mock.calls[0][0];
+
+    const commandStr = spawnCall.argv.join(" ");
+    expect(commandStr).toContain('export PATH="${OPENCLAW_PREPEND_PATH}${PATH:+:$PATH}"; unset OPENCLAW_PREPEND_PATH; echo test');
+  });
+
+  it("does not wrap command on Windows", async () => {
+    if (process.platform !== "win32") {
+      return;
+    }
+
+    supervisorMock.spawn.mockResolvedValueOnce({
+      runId: "mock-run",
+      startedAtMs: Date.now(),
+      wait: async () => ({
+        reason: "exit",
+        exitCode: 0,
+        exitSignal: null,
+        durationMs: 0,
+        stdout: "",
+        stderr: "",
+        timedOut: false,
+        noOutputTimedOut: false,
+      }),
+      cancel: vi.fn(),
+    });
+
+    const run = await runExecProcess({
+      command: "echo test",
+      workdir: "C:\\tmp",
+      env: { Path: "C:\\Windows\\System32" },
+      pathPrepend: ["C:\\custom\\bin"],
+      usePty: false,
+      warnings: [],
+      maxOutput: 1000,
+      pendingMaxOutput: 1000,
+      notifyOnExit: false,
+      timeoutSec: null,
+    });
+
+    expect(supervisorMock.spawn).toHaveBeenCalledTimes(1);
+    const spawnCall = supervisorMock.spawn.mock.calls[0][0];
+
+    const commandStr = spawnCall.argv.join(" ");
+    expect(commandStr).not.toContain("export PATH=");
+    expect(commandStr).toContain("echo test");
+  });
+});
diff --git a/src/agents/bash-tools.exec-runtime.ts b/src/agents/bash-tools.exec-runtime.ts
@@ -10,7 +10,7 @@ import {
 } from "../infra/exec-approvals.js";
 import { requestHeartbeat } from "../infra/heartbeat-wake.js";
 import { isDangerousHostInheritedEnvVarName } from "../infra/host-env-security.js";
-import { findPathKey, mergePathPrepend } from "../infra/path-prepend.js";
+import { findPathKey, mergePathPrepend, removePathPrepend } from "../infra/path-prepend.js";
 import { enqueueSystemEvent } from "../infra/system-events.js";
 import { resolveEventSessionKey, scopedHeartbeatWakeOptions } from "../routing/session-key.js";
 import { isSubagentSessionKey } from "../sessions/session-key-utils.js";
@@ -578,13 +578,45 @@ export function buildExecRuntimeErrorOutcome(params: {
   };
 }
 
+/**
+ * Apply PATH prepends inside the shell command.
+ * This ensures our paths take precedence even if user RC files (e.g. ~/.zshenv)
+ * prepend their own entries to PATH during shell startup.
+ */
+function wrapPosixCommandWithPathPrepend(command: string, env: Record<string, string>, pathPrepend?: string[]): string {
+  if (process.platform === "win32") {
+    return command;
+  }
+
+  if (!pathPrepend || pathPrepend.length === 0) {
+    return command;
+  }
+
+  // Strip prepended entries from the base env.PATH to avoid duplicate segments.
+  // The wrapper will re-apply them after shell startup.
+  const pathKey = findPathKey(env);
+  const currentPath = env[pathKey];
+  if (currentPath) {
+    const newPath = removePathPrepend(currentPath, pathPrepend);
+    if (newPath !== undefined) {
+      env[pathKey] = newPath;
+    }
+  }
+
+  // Pass the prepend string safely via a temporary environment variable.
+  env.OPENCLAW_PREPEND_PATH = pathPrepend.join(path.delimiter);
+
+  return `export PATH="\${OPENCLAW_PREPEND_PATH}\${PATH:+:$PATH}"; unset OPENCLAW_PREPEND_PATH; ${command}`;
+}
+
 export async function runExecProcess(opts: {
   command: string;
   // Execute this instead of `command` (which is kept for display/session/logging).
   // Used to sanitize safeBins execution while preserving the original user input.
   execCommand?: string;
   workdir: string;
   env: Record<string, string>;
+  pathPrepend?: string[];
   sandbox?: BashSandboxConfig;
   containerWorkdir?: string | null;
   usePty: boolean;
@@ -762,11 +794,15 @@ export async function runExecProcess(opts: {
       };
     }
     const { shell, args: shellArgs } = getShellConfig();
-    const childArgv = [shell, ...shellArgs, execCommand];
+    
+    // Wrap the command to enforce PATH prepend precedence over shell RC overrides.
+    const commandWithPathPrepend = wrapPosixCommandWithPathPrepend(execCommand, shellRuntimeEnv, opts.pathPrepend);
+
+    const childArgv = [shell, ...shellArgs, commandWithPathPrepend];
     if (opts.usePty) {
       return {
         mode: "pty" as const,
-        ptyCommand: execCommand,
+        ptyCommand: commandWithPathPrepend,
         childFallbackArgv: childArgv,
         env: shellRuntimeEnv,
         stdinMode: "pipe-open" as const,
diff --git a/src/agents/bash-tools.exec.ts b/src/agents/bash-tools.exec.ts
@@ -1560,6 +1560,7 @@ export function createExecTool(
           command: params.command,
           workdir,
           env,
+          pathPrepend: defaultPathPrepend,
           requestedEnv: params.env,
           pty: params.pty === true && !sandbox,
           timeoutSec: params.timeout,
@@ -1614,6 +1615,7 @@ export function createExecTool(
         execCommand: execCommandOverride,
         workdir,
         env,
+        pathPrepend: defaultPathPrepend,
         sandbox,
         containerWorkdir,
         usePty,
diff --git a/src/agents/bash-tools.test.ts b/src/agents/bash-tools.test.ts
@@ -104,7 +104,12 @@ vi.mock("../process/supervisor/index.js", () => {
   };
 
   const immediate = () => new Promise<void>((resolve) => setImmediate(resolve));
-  const readEnvPath = (env?: NodeJS.ProcessEnv) => env?.PATH ?? env?.Path ?? "";
+  const readPathKey = (env?: NodeJS.ProcessEnv) =>
+    env && "Path" in env && !("PATH" in env) ? "Path" : "PATH";
+  const readEnvPath = (env?: NodeJS.ProcessEnv) => env?.[readPathKey(env)] ?? "";
+  const writeEnvPath = (env: NodeJS.ProcessEnv, value: string) => {
+    env[readPathKey(env)] = value;
+  };
   const extractCommand = (input: SpawnInput) => input.ptyCommand ?? input.argv?.at(-1) ?? "";
   const splitCommands = (command: string) => {
     const commands: string[] = [];
@@ -116,7 +121,18 @@ vi.mock("../process/supervisor/index.js", () => {
     }
     return commands;
   };
-  const stdoutForSegment = (segment: string, env?: NodeJS.ProcessEnv) => {
+  const applySegmentShellEffects = (segment: string, env: NodeJS.ProcessEnv) => {
+    if (segment === 'export PATH="${OPENCLAW_PREPEND_PATH}${PATH:+:$PATH}"') {
+      const prepend = env.OPENCLAW_PREPEND_PATH ?? "";
+      const current = readEnvPath(env);
+      writeEnvPath(env, `${prepend}${current ? `:${current}` : ""}`);
+      return;
+    }
+    if (segment === "unset OPENCLAW_PREPEND_PATH") {
+      delete env.OPENCLAW_PREPEND_PATH;
+    }
+  };
+  const stdoutForSegment = (segment: string, env: NodeJS.ProcessEnv) => {
     if (segment === "echo $PATH" || segment === "Write-Output $env:PATH") {
       return `${readEnvPath(env)}\n`;
     }
@@ -129,10 +145,15 @@ vi.mock("../process/supervisor/index.js", () => {
     return "";
   };
 
-  const commandOutput = (command: string, env?: NodeJS.ProcessEnv) =>
-    splitCommands(command)
-      .map((segment) => stdoutForSegment(segment, env))
+  const commandOutput = (command: string, env?: NodeJS.ProcessEnv) => {
+    const shellEnv = { ...env };
+    return splitCommands(command)
+      .map((segment) => {
+        applySegmentShellEffects(segment, shellEnv);
+        return stdoutForSegment(segment, shellEnv);
+      })
       .join("");
+  };
 
   return {
     getProcessSupervisor: () => ({
@@ -845,6 +866,23 @@ describe("exec PATH handling", () => {
       expect(index).toBeLessThan(baseIndex);
     }
   });
+
+  it("protects POSIX prepended paths from shell startup overrides", async () => {
+    if (isWin) {
+      return;
+    }
+    process.env.PATH = "/evil/bin:/usr/bin";
+    const tool = createTestExecTool({ pathPrepend: ["/custom/bin"] });
+
+    const result = await executeExecCommand(tool, COMMAND_PRINT_PATH);
+
+    const text = readNormalizedTextContent(result.content);
+    const entries = text.split(path.delimiter);
+
+    // Simulate a shell startup file prepending /evil/bin before the command runs.
+    // The exec wrapper must still restore configured pathPrepend entries to the front.
+    expect(entries).toEqual(["/custom/bin", "/evil/bin", "/usr/bin"]);
+  });
 });
 
 describe("findPathKey", () => {
diff --git a/src/infra/path-prepend.test.ts b/src/infra/path-prepend.test.ts
@@ -5,6 +5,7 @@ import {
   findPathKey,
   mergePathPrepend,
   normalizePathPrepend,
+  removePathPrepend,
 } from "./path-prepend.js";
 
 const env = (value: Record<string, string>) => value;
@@ -106,4 +107,50 @@ describe("path prepend helpers", () => {
     applyPathPrepend(env, prepend, opts);
     expect(env).toEqual(expected);
   });
+
+  describe("removePathPrepend", () => {
+    it("returns the existing path if prepend is empty", () => {
+      expect(removePathPrepend("/usr/bin:/bin", [])).toBe("/usr/bin:/bin");
+    });
+
+    it("returns undefined if existing is undefined", () => {
+      expect(removePathPrepend(undefined, ["/custom/bin"])).toBeUndefined();
+    });
+
+    it("removes prepended entries globally from the existing path", () => {
+      // Normal case
+      expect(
+        removePathPrepend(
+          pathLine("/custom/bin", "/opt/bin", "/usr/bin", "/bin"),
+          ["/custom/bin", "/opt/bin"]
+        )
+      ).toBe(pathLine("/usr/bin", "/bin"));
+
+      // Tampered case (entries exist later in the path)
+      expect(
+        removePathPrepend(
+          pathLine("/plugin/bin", "/custom/bin", "/opt/bin", "/usr/bin", "/bin"),
+          ["/custom/bin", "/opt/bin"]
+        )
+      ).toBe(pathLine("/plugin/bin", "/usr/bin", "/bin"));
+
+      // Duplicate case (natural path contains duplicate of prepended entry)
+      // Since removePathPrepend now uses global filtering, it will remove all instances.
+      expect(
+        removePathPrepend(
+          pathLine("/custom/bin", "/opt/bin", "/usr/bin", "/custom/bin", "/bin"),
+          ["/custom/bin", "/opt/bin"]
+        )
+      ).toBe(pathLine("/usr/bin", "/bin"));
+    });
+
+    it("handles whitespace and blank entries safely", () => {
+      expect(
+        removePathPrepend(
+          pathLine(" /custom/bin ", " ", "/usr/bin"),
+          ["  /custom/bin  ", ""]
+        )
+      ).toBe("/usr/bin");
+    });
+  });
 });
diff --git a/src/infra/path-prepend.ts b/src/infra/path-prepend.ts
@@ -57,6 +57,27 @@ export function mergePathPrepend(existing: string | undefined, prepend: string[]
   return merged.join(path.delimiter);
 }
 
+export function removePathPrepend(
+  existing: string | undefined,
+  prepend: string[],
+): string | undefined {
+  if (!existing || prepend.length === 0) {
+    return existing;
+  }
+
+  const prependEntries = new Set<string>(
+    prepend.map((part) => part.trim()).filter(Boolean),
+  );
+
+  const remaining: string[] = (existing ?? "")
+    .split(path.delimiter)
+    .map((part) => part.trim())
+    .filter(Boolean)
+    .filter((part) => !prependEntries.has(part));
+
+  return remaining.join(path.delimiter);
+}
+
 export function applyPathPrepend(
   env: Record<string, string>,
   prepend: string[] | undefined,
