Validate Codex app-server command overrides (#84417)

TurboTheTurtle · clawsweeper[bot] · Takhoffman · web-flow · commit 03125c8e132d · 2026-05-22T05:39:02.000Z
Summary: - The PR rejects Codex app-server command overrides that embed Node/package-manager inline arguments, adds matching doctor diagnostics, regression tests, and a changelog entry. - Reproducibility: yes. for the scoped malformed override path: current main passes the combined command strin ... ix resolver/doctor live output. I did not establish a live Windows npm-global managed-startup reproduction. Automerge notes: - PR branch already contained follow-up commit before automerge: Validate Codex app-server command overrides Validation: - ClawSweeper review passed for head 966bcd6. - Required merge gates passed before the squash merge. Prepared head SHA: 966bcd6 Review: #84417 (comment) Co-authored-by: Andy Ye <35905412+TurboTheTurtle@users.noreply.github.com> Co-authored-by: clawsweeper <274271284+clawsweeper[bot]@users.noreply.github.com> Co-authored-by: clawsweeper[bot] <274271284+clawsweeper[bot]@users.noreply.github.com> Approved-by: takhoffman Co-authored-by: takhoffman <781889+takhoffman@users.noreply.github.com>
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -24,6 +24,7 @@ Docs: https://docs.openclaw.ai
 
 ### Fixes
 
+- Codex app-server: reject command overrides that embed Node or package-manager arguments and point users to `appServer.args`, so Windows startup avoids shell parsing failures. (#84417) Thanks @TurboTheTurtle.
 - Agents/Copilot: drop unsafe GitHub Copilot Responses reasoning replay items before send so Telegram direct sessions no longer fail on overlong replay IDs. Fixes #85197. (#85198) Thanks @galiniliev.
 - UI: add accessible tooltips to the topbar color-mode buttons so System, Light, and Dark choices are labeled on hover and focus. (#85227) Thanks @amknight.
 - fix: constrain Windows task script names [AI]. (#85064) Thanks @pgondhi987.
diff --git a/extensions/codex/src/app-server/config.test.ts b/extensions/codex/src/app-server/config.test.ts
@@ -619,6 +619,38 @@ allowed_sandbox_modes = ["read-only", "workspace-write"]
     );
   });
 
+  it("rejects Codex app-server command overrides that include inline arguments", () => {
+    expect(() =>
+      resolveRuntimeForTest({
+        pluginConfig: {
+          appServer: {
+            command: "node C:\\Users\\me\\.openclaw\\npm\\node_modules\\@openai\\codex\\bin\\codex.js",
+          },
+        },
+      }),
+    ).toThrow(
+      "plugins.entries.codex.config.appServer.command must be only the Codex app-server executable path",
+    );
+    expect(() =>
+      resolveRuntimeForTest({
+        pluginConfig: {},
+        env: {
+          OPENCLAW_CODEX_APP_SERVER_BIN:
+            "node C:\\Users\\me\\.openclaw\\npm\\node_modules\\@openai\\codex\\bin\\codex.js",
+        },
+      }),
+    ).toThrow("OPENCLAW_CODEX_APP_SERVER_BIN must be only the Codex app-server executable path");
+  });
+
+  it("preserves executable paths that contain spaces", () => {
+    const runtime = resolveRuntimeForTest({
+      pluginConfig: { appServer: { command: "C:\\Program Files\\OpenAI Codex\\codex.exe" } },
+      env: {},
+    });
+
+    expect(runtime.start.command).toBe("C:\\Program Files\\OpenAI Codex\\codex.exe");
+  });
+
   it("resolves Computer Use setup from plugin config and environment fallbacks", () => {
     expect(
       resolveCodexComputerUseConfig({
diff --git a/extensions/codex/src/app-server/config.ts b/extensions/codex/src/app-server/config.ts
@@ -1,6 +1,7 @@
 import { createHmac, randomBytes } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { hostname as readHostName } from "node:os";
+import { detectWindowsSpawnCommandInlineArgs } from "openclaw/plugin-sdk/windows-spawn";
 import { z } from "zod";
 import type { CodexSandboxPolicy, CodexServiceTier } from "./protocol.js";
 
@@ -305,6 +306,27 @@ export function isCodexSandboxExecServerEnabled(pluginConfig?: unknown): boolean
   return readCodexPluginConfig(pluginConfig).appServer?.experimental?.sandboxExecServer === true;
 }
 
+function assertCodexAppServerCommandHasNoInlineArgs(params: {
+  command: string;
+  source: CodexAppServerCommandSource;
+}): void {
+  const inlineArgs = detectWindowsSpawnCommandInlineArgs(params.command);
+  if (!inlineArgs) {
+    return;
+  }
+  const sourceLabel =
+    params.source === "env"
+      ? "OPENCLAW_CODEX_APP_SERVER_BIN"
+      : "plugins.entries.codex.config.appServer.command";
+  const argsLabel =
+    params.source === "env"
+      ? "OPENCLAW_CODEX_APP_SERVER_ARGS"
+      : "plugins.entries.codex.config.appServer.args";
+  throw new Error(
+    `${sourceLabel} must be only the Codex app-server executable path; "${inlineArgs.executable}" was configured with inline arguments "${inlineArgs.arguments}". Move those arguments to ${argsLabel}, or remove the override to use the managed Codex startup path.`,
+  );
+}
+
 export function resolveCodexPluginsPolicy(pluginConfig?: unknown): ResolvedCodexPluginsPolicy {
   const config = readCodexPluginConfig(pluginConfig).codexPlugins;
   const configured = config !== undefined;
@@ -356,6 +378,9 @@ export function resolveCodexAppServerRuntimeOptions(
     : envCommand
       ? "env"
       : "managed";
+  if (commandSource === "config" || commandSource === "env") {
+    assertCodexAppServerCommandHasNoInlineArgs({ command, source: commandSource });
+  }
   const args = resolveArgs(config.args, env.OPENCLAW_CODEX_APP_SERVER_ARGS);
   const headers = normalizeHeaders(config.headers);
   const clearEnv = normalizeStringList(config.clearEnv);
diff --git a/extensions/codex/src/app-server/transport-stdio.test.ts b/extensions/codex/src/app-server/transport-stdio.test.ts
@@ -88,6 +88,19 @@ describe("resolveCodexAppServerSpawnInvocation", () => {
       windowsHide: true,
     });
   });
+
+  it("rejects Windows Codex app-server commands that include inline script arguments", () => {
+    expect(() =>
+      resolveCodexAppServerSpawnInvocation(
+        startOptions("node C:\\Users\\me\\.openclaw\\npm\\node_modules\\@openai\\codex\\bin\\codex.js"),
+        {
+          platform: "win32",
+          env: {},
+          execPath: "C:\\node\\node.exe",
+        },
+      ),
+    ).toThrow("Windows spawn command must be an executable path only");
+  });
 });
 
 describe("resolveCodexAppServerSpawnEnv", () => {
diff --git a/src/commands/doctor/shared/codex-route-warnings.test.ts b/src/commands/doctor/shared/codex-route-warnings.test.ts
@@ -134,6 +134,34 @@ describe("collectCodexRouteWarnings", () => {
     expect(warnings).toStrictEqual([]);
   });
 
+  it("warns when Codex app-server command includes inline arguments", () => {
+    const warnings = collectCodexRouteWarnings({
+      cfg: {
+        plugins: {
+          entries: {
+            codex: {
+              enabled: true,
+              config: {
+                appServer: {
+                  command:
+                    "node C:\\Users\\me\\.openclaw\\npm\\node_modules\\@openai\\codex\\bin\\codex.js",
+                },
+              },
+            },
+          },
+        },
+      } as unknown as OpenClawConfig,
+    });
+
+    expect(warnings).toStrictEqual([
+      [
+        "- Codex app-server command override includes inline arguments.",
+        '- plugins.entries.codex.config.appServer.command: "node C:\\Users\\me\\.openclaw\\npm\\node_modules\\@openai\\codex\\bin\\codex.js" starts with "node" and embeds "C:\\Users\\me\\.openclaw\\npm\\node_modules\\@openai\\codex\\bin\\codex.js". The command field must be only the executable path.',
+        "- Remove the override to use managed Codex startup, or move script/options to plugins.entries.codex.config.appServer.args.",
+      ].join("\n"),
+    ]);
+  });
+
   it("warns when Codex runtime routes are configured while the Codex plugin is disabled", () => {
     const warnings = collectCodexRouteWarnings({
       cfg: {
diff --git a/src/commands/doctor/shared/codex-route-warnings.ts b/src/commands/doctor/shared/codex-route-warnings.ts
@@ -13,6 +13,7 @@ import { resolveAllAgentSessionStoreTargetsSync } from "../../../config/sessions
 import type { SessionEntry } from "../../../config/sessions/types.js";
 import type { AgentRuntimePolicyConfig } from "../../../config/types.agents-shared.js";
 import type { OpenClawConfig } from "../../../config/types.openclaw.js";
+import { detectWindowsSpawnCommandInlineArgs } from "../../../plugin-sdk/windows-spawn.js";
 import { normalizeAgentId } from "../../../routing/session-key.js";
 
 type CodexRouteHit = {
@@ -2427,6 +2428,29 @@ function formatDisabledCodexPluginWarning(params: {
   ].join("\n");
 }
 
+function collectCodexAppServerCommandWarnings(cfg: OpenClawConfig): string[] {
+  const plugins = asMutableRecord(cfg.plugins);
+  const entries = asMutableRecord(plugins?.entries);
+  const codex = asMutableRecord(entries?.codex);
+  const config = asMutableRecord(codex?.config);
+  const appServer = asMutableRecord(config?.appServer);
+  const command = typeof appServer?.command === "string" ? appServer.command.trim() : "";
+  if (!command) {
+    return [];
+  }
+  const inlineArgs = detectWindowsSpawnCommandInlineArgs(command);
+  if (!inlineArgs) {
+    return [];
+  }
+  return [
+    [
+      "- Codex app-server command override includes inline arguments.",
+      `- plugins.entries.codex.config.appServer.command: "${command}" starts with "${inlineArgs.executable}" and embeds "${inlineArgs.arguments}". The command field must be only the executable path.`,
+      "- Remove the override to use managed Codex startup, or move script/options to plugins.entries.codex.config.appServer.args.",
+    ].join("\n"),
+  ];
+}
+
 export function collectCodexRouteWarnings(params: {
   cfg: OpenClawConfig;
   env?: NodeJS.ProcessEnv;
@@ -2458,6 +2482,7 @@ export function collectCodexRouteWarnings(params: {
       ignoreLegacyAgentRuntimePins,
     });
   const warnings: string[] = [];
+  warnings.push(...collectCodexAppServerCommandWarnings(params.cfg));
   if (hits.length > 0) {
     warnings.push(
       [
diff --git a/src/plugin-sdk/windows-spawn.test.ts b/src/plugin-sdk/windows-spawn.test.ts
@@ -12,6 +12,33 @@ const { createTempDir } = createPluginSdkTestHarness({
 });
 
 describe("resolveWindowsSpawnProgram", () => {
+  it("rejects node command strings that include inline entrypoint arguments on Windows", () => {
+    expect(() =>
+      resolveWindowsSpawnProgram({
+        command: "node C:\\Users\\me\\.openclaw\\npm\\node_modules\\@openai\\codex\\bin\\codex.js",
+        platform: "win32",
+        env: {},
+        execPath: "C:\\node\\node.exe",
+      }),
+    ).toThrow("Windows spawn command must be an executable path only");
+  });
+
+  it("allows executable paths with spaces on Windows", () => {
+    const resolved = resolveWindowsSpawnProgram({
+      command: "C:\\Program Files\\OpenAI Codex\\codex.exe",
+      platform: "win32",
+      env: {},
+      execPath: "C:\\node\\node.exe",
+    });
+
+    expect(resolved).toEqual({
+      command: "C:\\Program Files\\OpenAI Codex\\codex.exe",
+      leadingArgv: [],
+      resolution: "direct",
+      windowsHide: undefined,
+    });
+  });
+
   it("fails closed by default for unresolved windows wrappers", async () => {
     const dir = await createTempDir("openclaw-windows-spawn-test-");
     const shimPath = path.join(dir, "wrapper.cmd");
diff --git a/src/plugin-sdk/windows-spawn.ts b/src/plugin-sdk/windows-spawn.ts
@@ -48,6 +48,27 @@ export type ResolveWindowsSpawnProgramCandidateParams = Omit<
   ResolveWindowsSpawnProgramParams,
   "allowShellFallback"
 >;
+export type WindowsSpawnCommandInlineArgs = {
+  executable: string;
+  arguments: string;
+};
+
+const INLINE_ARGUMENT_EXECUTABLES = new Set([
+  "node",
+  "node.exe",
+  "npm",
+  "npm.cmd",
+  "npm.exe",
+  "npx",
+  "npx.cmd",
+  "npx.exe",
+  "pnpm",
+  "pnpm.cmd",
+  "pnpm.exe",
+  "yarn",
+  "yarn.cmd",
+  "yarn.exe",
+]);
 
 function isFilePath(candidate: string): boolean {
   try {
@@ -57,6 +78,49 @@ function isFilePath(candidate: string): boolean {
   }
 }
 
+function readCommandToken(command: string): { token: string; rest: string } | null {
+  const trimmed = command.trim();
+  if (!trimmed) {
+    return null;
+  }
+  if (trimmed.startsWith('"')) {
+    const closeIndex = trimmed.indexOf('"', 1);
+    if (closeIndex <= 0) {
+      return null;
+    }
+    return {
+      token: trimmed.slice(1, closeIndex),
+      rest: trimmed.slice(closeIndex + 1).trim(),
+    };
+  }
+  const match = trimmed.match(/^(\S+)\s+(.+)$/);
+  if (!match) {
+    return null;
+  }
+  return {
+    token: match[1] ?? "",
+    rest: (match[2] ?? "").trim(),
+  };
+}
+
+export function detectWindowsSpawnCommandInlineArgs(
+  command: string,
+): WindowsSpawnCommandInlineArgs | null {
+  const parsed = readCommandToken(command);
+  if (!parsed?.rest) {
+    return null;
+  }
+  const normalizedToken = parsed.token.replace(/\\/g, "/");
+  const executable = normalizeLowercaseStringOrEmpty(path.posix.basename(normalizedToken));
+  if (!INLINE_ARGUMENT_EXECUTABLES.has(executable)) {
+    return null;
+  }
+  return {
+    executable: parsed.token,
+    arguments: parsed.rest,
+  };
+}
+
 /** Resolve a Windows command name through PATH and PATHEXT so wrapper inspection sees the real file. */
 export function resolveWindowsExecutablePath(command: string, env: NodeJS.ProcessEnv): string {
   if (command.includes("/") || command.includes("\\") || path.isAbsolute(command)) {
@@ -214,6 +278,12 @@ export function resolveWindowsSpawnProgramCandidate(
       resolution: "direct",
     };
   }
+  const inlineArgs = detectWindowsSpawnCommandInlineArgs(params.command);
+  if (inlineArgs) {
+    throw new Error(
+      `Windows spawn command must be an executable path only; "${inlineArgs.executable}" was configured with inline arguments "${inlineArgs.arguments}". Put arguments in the caller's args array instead.`,
+    );
+  }
 
   const resolvedCommand = resolveWindowsExecutablePath(params.command, env);
   const ext = normalizeLowercaseStringOrEmpty(path.extname(resolvedCommand));
