Support Codex Desktop on Windows with WSL app-server mode

[Ted151951]

Summary

OpenCodex appears to support pure Windows-native Codex and pure Linux-native Codex, but it does not seem to support the Codex Desktop setup where the Windows Desktop app launches the Codex app-server inside WSL.

In this setup, OpenCodex currently fails from both sides:

• Installed/run on Windows: ocx init cannot find a Codex executable on PATH.
• Installed/run inside Ubuntu/WSL: ocx init cannot find Codex config at /home/<user>/.codex/config.toml.

This looks like a path/layout mismatch rather than a provider-specific issue.

Environment

• OS: Windows Desktop app using WSL / Ubuntu
• Codex mode: Windows Codex Desktop launches the app-server in WSL
• Codex CLI location, from WSL:

/mnt/c/Users/<user>/.codex/bin/wsl/<hash>/codex

• Codex config location, from WSL:

/mnt/c/Users/<user>/.codex/config.toml

• WSL home also has a .codex directory, but it does not contain the main Desktop config:

/home/<wsl-user>/.codex/config.toml   # missing
/mnt/c/Users/<user>/.codex/config.toml # exists

Reproduction

Case 1: Install/run OpenCodex on Windows

Run:

ocx init

When prompted to install the Codex autostart shim, OpenCodex reports:

Could not find a codex executable on PATH.

This seems to come from the Windows shim discovery logic, which looks for codex.cmd, codex.ps1, or an extensionless codex launcher on the Windows PATH. In Codex Desktop WSL mode, however, the active CLI is a Linux binary under:

%USERPROFILE%\.codex\bin\wsl\<hash>\codex

That binary is not a normal Windows codex.cmd launcher.

Case 2: Install/run OpenCodex inside Ubuntu/WSL

Run:

ocx init

When prompted to inject into Codex config, OpenCodex reports:

Codex config not found at /home/<wsl-user>/.codex/config.toml. Is Codex installed?

But in this Codex Desktop WSL setup, the active Desktop config is actually under the Windows-mounted Codex home:

/mnt/c/Users/<user>/.codex/config.toml

So OpenCodex is using the WSL user's default home instead of the Desktop Codex home.

Expected behavior

It would be helpful if OpenCodex could either:

1. Officially support this Windows Desktop + WSL app-server layout; or
2. Detect it and print a clear unsupported/setup message; or
3. Document a safe manual setup, for example whether users should run something like:

CODEX_HOME=/mnt/c/Users/<user>/.codex ocx init

and whether that is safe with Codex Desktop's WSL app-server state/history.

Important concerns

This environment is not the same as pure Windows-native Codex or pure Linux-native Codex.

Some things that may need explicit handling:

• Windows side may not have a normal codex.cmd on PATH.
• WSL side may not have ~/.codex/config.toml even though Codex Desktop is installed.
• The active CLI is a Linux binary cached under the Windows Codex home.
• 127.0.0.1 / localhost can mean different things from Windows vs WSL.
• OpenCodex proxy base URL injected as http://127.0.0.1:<port>/v1 may not be reachable by the WSL app-server if the proxy runs on Windows.
• Codex Desktop history/state may live in a different location than a normal Linux CLI install.
• OpenCodex modifies config.toml, model catalog/cache, and resume history metadata, so this layout needs a safe restore story.

Request

Could OpenCodex add support or documentation for Codex Desktop on Windows when runCodexInWindowsSubsystemForLinux / WSL app-server mode is enabled?

At minimum, a documented compatibility statement would be very helpful:

• supported / unsupported;
• where OpenCodex should be installed, Windows or WSL;
• how CODEX_HOME should be set;
• whether the Codex shim should be skipped;
• how the local proxy should be bound so the WSL app-server can reach it;
• how to restore safely if history DB/cache updates fail.

Thanks for building this project — it is currently the closest community solution I have found for making third-party models appear in Codex Desktop's model picker while keeping native OpenAI/Codex models available.

[lidge-jun]

OK I'll look

[lidge-jun]

Fixed and released.

What changed:

• Added shared Codex home resolution so WSL can discover the Windows Codex Desktop home layout instead of assuming only /home/<wsl-user>/.codex.
• Added diagnostics for WSL /mnt / Windows-backed Codex home layouts so users get a clearer compatibility story instead of a generic missing-config failure.
• Updated Codex integration docs across locales with the Windows Desktop + WSL app-server setup guidance.
• Added tests for Windows Codex Desktop home discovery from WSL and path expansion behavior.

Released in:

• @bitkyc08/opencodex@2.6.22 (latest)
• @bitkyc08/opencodex@2.6.22-preview.20260705 (preview)

Verification included doctor/path tests, full bun test (1385 pass), typecheck, privacy scan, GitHub ci.yml, and service-lifecycle.yml before publish.