codex - 💡(How to fix) Fix Windows Desktop can hang after enabling WSL app-server mode and requires Electron cache reset to recover

Summary

On Windows, Codex Desktop became unable to show the GUI after enabling the Desktop WSL app-server mode. The app stayed running in the background as Codex.exe, but no usable window appeared. Windows reported the process as hung. Disabling WSL mode alone was not enough to recover; the app only started normally after clearing/renaming the Desktop Electron roaming cache directory.

Environment

• OS: Windows 11
• Codex Desktop package: OpenAI.Codex_26.519.5221.0_x64__2p2nqsd0c76g0
• Desktop executable path pattern: C:\Program Files\WindowsApps\OpenAI.Codex_26.519.5221.0_x64__2p2nqsd0c76g0\app\Codex.exe
• Desktop-bundled CLI: codex-cli 0.133.0-alpha.1
• Globally installed CLI: codex-cli 0.133.0
• WSL distros present: Ubuntu, docker-desktop, Ubuntu24-E

Trigger

The issue began after setting:

[desktop]
runCodexInWindowsSubsystemForLinux = true

After that, Codex Desktop repeatedly failed to show the GUI. The CLI still worked separately.

Observed behavior

• Codex.exe remained in the background.
• The main GUI did not appear or could not be interacted with.
• Windows marked the main process as not responding.
• Launching Codex Desktop again appeared to route back to the existing hung single instance instead of creating a working new window.
• After reboot, the old hung instance disappeared, but Desktop still failed very early and produced a zero-byte Desktop log until the Electron roaming cache was reset.

Example process state before recovery:

Codex.exe  PID 8972   Responding=False  MainWindowTitle=""  StartTime=03:10:54
Codex.exe  PID 19896  Responding=True   MainWindowHandle=0
Codex.exe  PID 30920  Responding=True   MainWindowHandle=0

Relevant Desktop log excerpt

The last useful Desktop log stopped during local app-server startup/connection:

info Launching app ... packaged=true platform=win32
info [wsl] eligible distro list listResult="NAME              STATE           VERSION\n* Ubuntu            Stopped         2\n  docker-desktop    Stopped         2\n  Ubuntu24-E        Stopped         2"
info [AppServerConnection] Initializing app-server transport
info [AppServerConnection] Starting app-server connection hostId=local transport=stdio
info [AppServerConnection] app_server_connection.state_changed cause=start_process ... next=connecting ... transport=stdio
info [remote-connections/window-context] refresh_started previousConnectionCount=0

No later ready/success state appeared in that log.

Windows event log evidence

Windows recorded repeated hangs, for example:

Provider: Windows Error Reporting
Event Name: MoAppHang
P1: OpenAI.Codex_26.519.5221.0_x64__2p2nqsd0c76g0
P2: praid:App
P3: 3044.0.0.0

Provider: Application Hang
Message: The program Codex.exe version 3044.0.0.0 stopped interacting with Windows and was closed.

Provider: Microsoft-Windows-Winsrv
Message: The following application was terminated because it was hung: Codex.exe.

Recovery steps that worked

1. Change the Desktop setting back to Windows-native mode:

[desktop]
runCodexInWindowsSubsystemForLinux = false

1. Reboot Windows to clear the stuck MSIX/Desktop single-instance processes.
2. Rename the Desktop Electron roaming cache directory:

%LOCALAPPDATA%\Packages\OpenAI.Codex_2p2nqsd0c76g0\LocalCache\Roaming\Codex

to a backup name, e.g.

%LOCALAPPDATA%\Packages\OpenAI.Codex_2p2nqsd0c76g0\LocalCache\Roaming\Codex.bak-YYYYMMDD-HHMMSS

1. Launch Codex Desktop again.

After the cache was rebuilt, the GUI appeared normally and the new process state was healthy:

Codex.exe  Responding=True  MainWindowTitle=Codex

Expected behavior

• If WSL app-server startup or handshake fails, Desktop should surface an actionable error instead of hanging invisibly in the background.
• Toggling runCodexInWindowsSubsystemForLinux back to false should be enough to recover on the next launch, without requiring manual Electron cache reset.
• Stale lock/cache state from a failed WSL-mode startup should not prevent subsequent Windows-native launches.

Notes

This report intentionally excludes full local transcripts, user-specific paths, API keys, and full configuration files.