openclaw - 💡(How to fix) Fix codex-cli backend can't spawn 'codex' on Windows (npm-global .cmd shim, ENOENT) — runtime doesn't use the bundled resolveWindowsSpawnProgram helper

Summary

On Windows, agents configured with agentRuntime.id: "codex-cli" (or "codex") fail every turn with:

GatewayClientRequestError: Error: spawn codex ENOENT: code=ENOENT

Reproduced on openclaw 2026.5.7 and 2026.5.12 (same root cause, confirmed by reading dist/cli-backend-D4q7sZcK.js in 5.12).

Environment

• OS: Windows 11 Pro 10.0.26200
• Node: 24.x (from C:\Program Files\nodejs\node.exe)
• openclaw: 2026.5.12 (f066dd2)
• codex CLI: 0.129.0 via npm i -g @openai/codex → C:\Users\<user>\AppData\Roaming\npm\codex.cmd (no .exe form ships)
• Gateway runs as Windows scheduled task launched from ~/.openclaw/gateway.cmd
• PATH includes %APPDATA%\npm at gateway startup; where codex from the gateway process resolves both codex and codex.cmd correctly

Root cause

dist/cli-backend-D4q7sZcK.js declares:

config: {
  command: "codex",
  args: ["exec", "--json", "--color", "never", "--sandbox", "workspace-write", "-c", "service_tier=\"fast\"", "--skip-git-repo-check"],
  ...
}

The runtime that consumes this config calls Node's native child_process.spawn("codex", argv, opts) without shell: true and without routing through resolveWindowsSpawnProgram from dist/windows-spawn-CGcgEkMZ.js (same bundle).

On Windows, npm-global CLIs ship as .cmd shims that Node cannot exec without one of:

1. shell: true (cli-backend doesn't set this)
2. An .exe form on PATH (codex doesn't ship one)
3. Parsing the .cmd shim and spawning the underlying node <entry.js> directly — which is exactly what resolveWindowsSpawnProgram does, and exactly what dist/acp-cli-*.js:298 uses for the ACP runtime

Result: the codex-cli backend has the helper available next to it in the bundle but never calls it.

Reproduction

1. npm i -g @openai/codex (Windows)
2. openclaw agents add codex-ops --workspace ~/.openclaw/workspaces/codex-ops --non-interactive
3. Edit ~/.openclaw/openclaw.json to add "agentRuntime": { "id": "codex-cli" } to the new agent's list entry
4. openclaw gateway restart
5. openclaw agent --agent codex-ops --message "hi" --json --timeout 60

Observe spawn codex ENOENT: code=ENOENT despite where codex resolving correctly from the same environment.

Suggested fix

At the codex-cli backend's spawn site, route through:

import { resolveWindowsSpawnProgram, materializeWindowsSpawnProgram } from "<...>/windows-spawn.js";

const program = resolveWindowsSpawnProgram({
  command: backendConfig.command,      // "codex"
  env: process.env,
  execPath: process.execPath,
  packageName: "@openai/codex",
  allowShellFallback: true,            // safety net for unusual installs
});
const invocation = materializeWindowsSpawnProgram(program, backendConfig.args);
const child = spawn(invocation.command, invocation.args, { shell: invocation.shell, windowsHide: invocation.windowsHide, ... });

This is exactly the pattern acp-cli-BLDZ-qJE.js:297-310 uses for the ACP runtime — and it works correctly on Windows. Applying it to the codex-cli (and presumably claude-cli, gemini-cli) backends would resolve this.

Related — separate but adjacent

@openclaw/codex plugin (alternate path via agentRuntime.id: "codex") fails to load on this openclaw version with: Cannot find module 'plugin-sdk/root-alias.cjs/json-schema-runtime'. Looks like plugin/core version drift. Worth checking the latest published plugin against current core's exported plugin-sdk surface.

Impact

Windows users can't use codex-cli (or any cli-backend that ships only .cmd shims) as an agent runtime via openclaw at all. The fallback paths are all hacky (build a custom .exe wrapper around codex.cmd, or bypass openclaw entirely).

Happy to PR the fix if there's appetite — the helper is right there, just needs to be wired up at three or four call sites.