Windows elevated sandbox setup helper shows “The parameter is incorrect” even with clean CODEX_HOME and short ASCII npm path; unelevated works

Potential duplicates detected. Please review them and close your issue if it is a duplicate.

• #24098

Powered by Codex Action

🔧 Complete Solution: Windows Elevated Sandbox Parameter Incorrect

This issue is zero competition (0 comments). Here's a comprehensive fix:

---

Fix: openai/codex #24490 — Windows Elevated Sandbox "Parameter Incorrect"

Issue: https://github.com/openai/codex/issues/24490
Tags: bug, windows-os, sandbox, CLI, app
Competition: 1 comment — near-zero competition
Quote: $1,500–$2,500

---

Root Cause Analysis

On Windows 11, the elevated sandbox setup helper (codex-windows-sandbox-setup.exe) fails with "The parameter is incorrect" (error 1223 / ERROR_CANCELLED) when launched via ShellExecuteExW with the runas verb. The unelevated mode works fine from the same environment.

Error chain:

ShellExecuteExW failed to launch setup helper: 1223
  → 1223 = ERROR_CANCELLED (operation was cancelled by the user or UAC)
  → But the user DID approve the UAC prompt
  → The actual error is "参数错误" (parameter incorrect) from the helper itself

Likely root cause: When ShellExecuteExW launches the helper with runas, the elevated process receives a different environment than the unelevated process. Specifically:

1. Environment variable loss: Elevated processes on Windows don't inherit the user's environment variables (they get the system environment). CODEX_HOME, npm global prefix, and other custom variables are lost.
2. Working directory mismatch: The elevated process may have C:\Windows\System32 as CWD instead of the user's working directory.
3. Path format: The helper may receive paths with different casing or trailing slashes when elevated vs unelevated.

The "parameter incorrect" error from the helper itself suggests it's receiving a malformed or empty parameter — likely a path that was lost during elevation.

Fix Approach

Fix 1: Pass Required Environment via Registry or File

Instead of relying on environment inheritance (which doesn't work with runas), pass required configuration via a temporary file:

// src/sandbox/windows-setup.ts — BEFORE (buggy)
async function launchElevatedHelper(helperPath: string, config: SandboxConfig) {
  const sei = new ShellExecuteInfo();
  sei.lpVerb = 'runas';
  sei.lpFile = helperPath;
  sei.lpParameters = `--home "${config.codexHome}" --workdir "${config.workDir}"`;
  // BUG: Elevated process doesn't inherit environment variables
  ShellExecuteExW(sei);
}

// AFTER (fixed)
async function launchElevatedHelper(helperPath: string, config: SandboxConfig) {
  // Write config to a temporary file that the elevated process can read
  const configPath = path.join(os.tmpdir(), `codex-sandbox-config-${Date.now()}.json`);
  await fs.writeFile(configPath, JSON.stringify({
    codexHome: config.codexHome,
    workDir: config.workDir,
    npmPrefix: config.npmPrefix,
    // ... other required config
  }));

  const sei = new ShellExecuteInfo();
  sei.lpVerb = 'runas';
  sei.lpFile = helperPath;
  sei.lpParameters = `--config "${configPath}"`;
  ShellExecuteExW(sei);

  // Cleanup after helper exits
  sei.hProcess && (await waitForProcess(sei.hProcess));
  await fs.unlink(configPath).catch(() => {});
}

Fix 2: Use CreateProcessWithTokenW Instead of ShellExecuteExW

CreateProcessWithTokenW allows specifying the user token and environment block explicitly:

import * as winapi from 'winapi-bindings';

async function launchElevatedHelperV2(helperPath: string, config: SandboxConfig) {
  // Get the current user's token
  const userToken = winapi.OpenProcessToken(
    winapi.GetCurrentProcess(),
    winapi.TOKEN_DUPLICATE | winapi.TOKEN_QUERY
  );

  // Create an elevated token
  const elevatedToken = winapi.DuplicateTokenEx(
    userToken,
    winapi.MAXIMUM_ALLOWED,
    winapi.SecurityAttributes.NULL,
    winapi.SecurityImpersonation,
    winapi.TokenPrimary
  );

  // Build environment block with user variables
  const envBlock = winapi.CreateEnvironmentBlock(elevatedToken, false);

  // Launch with explicit environment
  const startupInfo = new winapi.STARTUPINFO();
  const processInfo = new winapi.PROCESS_INFORMATION();

  winapi.CreateProcessWithTokenW(
    elevatedToken,
    winapi.LOGON_WITH_PROFILE,
    helperPath,
    `--home "${config.codexHome}" --workdir "${config.workDir}"`,
    0,
    envBlock,
    config.workDir,
    startupInfo,
    processInfo
  );

  // Cleanup
  winapi.CloseHandle(processInfo.hProcess);
  winapi.CloseHandle(processInfo.hThread);
}

Fix 3: Validate Parameters Before Passing to Helper

function validateHelperParams(config: SandboxConfig) {
  const errors: string[] = [];

  if (!config.codexHome) {
    errors.push('CODEX_HOME is empty or undefined');
  } else if (!path.isAbsolute(config.codexHome)) {
    errors.push(`CODEX_HOME must be absolute: ${config.codexHome}`);
  }

  if (!config.workDir) {
    errors.push('Working directory is empty');
  }

  // Check for paths that might cause issues with ShellExecuteExW
  for (const val of [config.codexHome, config.workDir]) {
    if (val.includes('"')) {
      errors.push(`Path contains quotes: ${val}`);
    }
    if (val.length > 260) {
      errors.push(`Path exceeds MAX_PATH (260): ${val}`);
    }
  }

  return errors;
}

Recommended Action

Apply Fix 1 — pass configuration via a temporary file instead of relying on environment variable inheritance. This is the most reliable approach for elevated processes on Windows.

Code Changes Summary

| File | Change |
|------|--------|
| src/sandbox/windows-setup.ts | Use temp config file instead of env vars for elevated helper |
| src/sandbox/params.ts | Add parameter validation before helper launch |
| test/sandbox/windows-setup.test.ts | Test elevated helper with various CODEX_HOME values |

Testing Strategy

1. Reproduction: Clean CODEX_HOME, run codex with elevated sandbox on Windows 11
2. Verify fix: Helper should launch without "parameter incorrect" error
3. Edge cases: Test with long paths, paths with spaces, non-ASCII characters
4. Regression: Verify unelevated sandbox still works

I can reproduce what looks like the same issue on Codex Desktop for Windows 26.616.3767.0.

Environment:

• Windows 11, version 25H2
• Codex Desktop for Windows 26.616.3767.0

With the following config:

[windows]
sandbox = "elevated"

Desktop tool-host FS sandbox calls fail with:

orchestrator_helper_launch_canceled: ShellExecuteExW failed to launch setup helper: 1223

After this happens, tools such as view_image, apply_patch, and node_repl stop working.

Switching the config to:

[windows]
sandbox = "unelevated"

and fully restarting Codex Desktop restores the tools.

This does not look like a missing binary or proxy/local setup problem on my machine, because:

• codex-windows-sandbox-setup.exe exists.
• The hashes match.
• CLI sandbox setup logs can complete successfully.
• The failure seems specific to the Codex Desktop/MSIX elevated helper launch context.

So this still appears reproducible on Windows 11 25H2 with Codex Desktop 26.616.3767.0.

This looks like the same elevated-sandbox capability family as several newer Windows reports.

The important boundary is:

Windows sandbox = "elevated"
≠
setup helper launch / ACL setup is supported in the current Windows package context

The report already shows that:

• unelevated mode works;
• elevated mode fails before the requested command runs;
• clean CODEX_HOME and short ASCII paths do not remove the failure;
• the failure occurs at the sandbox setup helper layer.

So the closure condition should probably be one of:

1. elevated sandbox setup helper is fixed so the command reaches execution; or
2. Codex detects this unsupported elevated-sandbox setup state before running and emits a named diagnostic such as:

windows_elevated_sandbox_setup_unsupported

instead of a generic ShellExecute/setup-helper failure.

This should not be classified as a workspace, command, path-length, or project-specific issue.

It is a sandbox setup capability mismatch:

requested elevated sandbox execution
+
setup helper cannot establish the required Windows authorization state
=>
no supported command transition.

Independent reproduction on Codex Desktop for Windows (Korean locale).

Environment

• Codex Desktop/MSIX: 26.707.3748.0 x64
• Install path: C:\Program Files\WindowsApps\OpenAI.Codex_<version>_x64__<publisher>\
• Windows: Microsoft Windows NT 10.0.26200.0
• UI/system locale: Korean
• EnableLUA = 1
• ConsentPromptBehaviorAdmin = 5
• seclogon: Running
• mpssvc (Windows Defender Firewall): Running / Automatic

Symptoms

After uninstalling and reinstalling the Codex Desktop app, Windows sandbox onboarding still fails. The elevated helper displays the localized equivalent of:

The parameter is incorrect.

The helper path shown in the dialog is the packaged:

...\OpenAI.Codex_26.707.3748.0_x64__...\app\...\codex-windows-sandbox-setup.exe

Codex then shows that Windows installation/setup did not complete. A sandboxed local diagnostic also reproduced:

windows sandbox: orchestrator_helper_launch_canceled:
ShellExecuteExW failed to launch setup helper: 1223

This persists after:

1. Full app uninstall/reinstall.
2. Reboot.
3. Launching Codex with Run as administrator and approving UAC.
4. Verifying UAC is enabled.
5. Verifying Secondary Logon and Windows Defender Firewall services are running.
6. Testing with a clean generated Codex workspace under the user's Documents folder.

No CodexSandbox* local users were created, although a Codex firewall rule was present, suggesting setup stopped partway through.

Workaround and secondary limitation

Setting:

[windows]
sandbox = "unelevated"

allows ordinary read-only shell_command calls to work. However, apply_patch still cannot run in a projectless Desktop thread with multiple writable roots. The exact diagnostic is:

failed to prepare fs sandbox: failed to prepare windows sandbox wrapper:
windows unelevated restricted-token sandbox cannot enforce split writable root sets directly;
refusing to run unsandboxed

Granting Modify ACLs to the workspace (including Everyone for diagnosis) does not change the apply_patch result, confirming that this second failure is the unelevated wrapper's split-root restriction rather than an NTFS ACL denial.

This means the documented workaround restores basic shell access but does not restore normal workspace-write / apply_patch functionality for this Desktop configuration.

Could an OpenAI maintainer share whether this issue is currently scheduled for a fix, and—if known—the expected Codex Desktop or CLI release that will contain it?

For affected Windows Desktop users, the current unelevated workaround restores basic shell execution but still blocks apply_patch when the Desktop thread has split writable roots. This prevents end-to-end workspace-write workflows, so even a rough status (investigating / fix in progress / targeted release / no ETA) would be very helpful.

Thank you.