Custom pets fail to load in WSL environments due to path normalization

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

• #20014

Powered by Codex Action

Confirmed on my machine as well.

Repro: custom pet clawd is present under ~/.codex/pets/clawd/{pet.json,spritesheet.webp} and appears normally when Codex is used from Windows native, but it does not appear in Settings when Codex is run from a WSL2 environment.

Observed with Codex 26.429.30905 on @OpenAi.
Plan: Business Plan
Platform: Windows

This matches the path-loading behavior described in this issue.

Confirmed on my Windows + WSL2 as well.

I added a custom pet at

C:\Users\username\.codex\pets\petname\pet.json
C:\Users\username\.codex\pets\petname\spritesheet.webp

The same files are also present under the WSL home:

/home/username/.codex/pets/petname/{pet.json,spritesheet.webp}

Codex notes that the package validates locally per the hatch pet skill: pet.json points to spritesheet.webp, and the spritesheet is a valid 1536x1872 WebP. The app Settings UI shows the custom pets folder as C:\Users\username\.codex\pets, but after Refresh and app/PC restart, the custom pet still does not appear.

Environment:

• Windows host with WSL2 enabled
• Codex Desktop package path shows OpenAI.Codex_26.429.3425.0_x64
• App server reports 0.128.0-alpha.1
• runCodexInWindowsSubsystemForLinux is enabled

This appears to match the WSL path-loading behavior described here.

Confirmed

I can add a more specific reproduction and path-level finding for this issue.

## Environment

• OS: Microsoft Windows 11 Pro, build 26200, x64
• Requested PowerShell output: Microsoft Windows NT 10.0.26200.0 x64
• Codex Desktop package: OpenAI.Codex_26.429.8261.0_x64__2p2nqsd0c76g0
• App version observed in package: 26.429.61741
• App-server configured to run through WSL
• Custom pet installed under the Windows Codex home:

C:\Users\<USER>\.codex\pets\<pet-id>\pet.json

## Reproduction

1. On Windows, create a valid custom pet under:

C:\Users\<USER>\.codex\pets\<pet-id>

1. Open Codex Desktop in Windows native mode.
2. Go to Settings -> Appearance -> Pets and click Refresh.
3. The custom pet appears.
4. Switch Codex Desktop to run in WSL mode.
5. Restart Codex Desktop.
6. Go back to Settings -> Appearance -> Pets and click Refresh.
7. The custom pet does not appear.

This matches the behavior reported in #20905, but with a more specific path-normalization finding.

## Path finding

In WSL mode, the custom pet loader appears to construct a mixed Windows/POSIX path like:

C:\Users\<USER>\.codex/pets

The WSL app-server cannot discover pets at that path.

The path needs to be normalized to the WSL mount path before joining pets or avatars:

/mnt/c/Users/<USER>/.codex/pets

## Local verification

A local dry-run ASAR patch confirmed the narrow behavior change.

Before:

path.posix.join("C:\\Users\\<USER>\\.codex", "pets")
=> C:\Users\<USER>\.codex/pets

After normalizing the Codex home when preferWsl is true:

/mnt/c/Users/<USER>/.codex/pets

A loader-like verifier then discovered the custom pet from:

/mnt/c/Users/<USER>/.codex/pets/<pet-id>/pet.json

## Suggested fix scope

When preferWsl is true and the resolved Codex home is a Windows drive path, normalize it before constructing the custom pets and avatars paths.

Conceptually:

``ts
function normalizeCodexHomeForWsl(codexHome: string, preferWsl: boolean): string {
if (preferWsl && /^[a-zA-Z]:[\\/]/.test(codexHome)) {
return /mnt/${codexHome[0].toLowerCase()}/${codexHome
.slice(3)
.replace(/\\/g, "/")}`;
}
return codexHome;
}

  This should be scoped to custom pet/avatar discovery and should not change global CODEX_HOME, app-server launch behavior, terminal command execution, workspace paths, skills, agents, or file browsing helpers

Appreciate the idea @RomeoRaven
If anybody need this urgently, you can use my temporary patch script for now. 😂
https://github.com/Tairitsua/codex-wsl-custom-pets-patch

I can add one data point from a newer Windows build. This does not establish a new root cause, but it narrows the behavior a bit: the UI can open the expected custom pets folder, while the custom pet list/renderer still does not pick up valid packages from that same folder.

Environment

• Codex Desktop package: OpenAI.Codex_26.519.2081.0_x64__2p2nqsd0c76g0
• Codex Desktop version: 26.519.2081.0
• Windows host with WSL integration enabled
• WSL distro: Ubuntu-22.04
• CODEX_HOME in the WSL app-server process resolves to the WSL view of the Windows Codex home
• WSLENV includes CODEX_HOME/p

Note: this is not a clean-install environment. It is a real Windows + WSL Codex Desktop profile that has previously had Desktop/WSL path and local history troubleshooting. I am including this because the issue still reproduces after that profile is in a stable state where local history opens correctly.

Additional observation

• In Settings > Appearance > Pets, the custom pets Open folder action opens the expected folder:
• <CODEX_HOME_WIN>\pets
• That folder contains multiple valid custom pet packages.
• After clicking Refresh custom pets, no custom pets appear in the Pets list.
• Setting selected-avatar-id to a custom pet folder id, for example custom-pet-02, is persisted in .codex-global-state.json.
• Running Wake Pet or /pet still shows the built-in codex pet, so the renderer appears to fall back after failing to resolve/list/load the selected custom pet.

Local package validation

I tested three packages under <CODEX_HOME_WIN>\pets:

custom-pet-01
custom-pet-02
custom-pet-03

For each package:

• pet.json exists.
• spritesheet.webp exists.
• pet.json.id matches the folder name.
• pet.json.spritesheetPath points to the existing spritesheet.webp.
• The spritesheet opens as 1536x1872 RGBA.

Example normalized package metadata:

[
  {
    "folder": "custom-pet-01",
    "id": "custom-pet-01",
    "displayName": "Custom Pet 01",
    "spritesheetPath": "spritesheet.webp",
    "idMatchesFolder": true,
    "spritesheetExists": true
  },
  {
    "folder": "custom-pet-02",
    "id": "custom-pet-02",
    "displayName": "Custom Pet 02",
    "spritesheetPath": "spritesheet.webp",
    "idMatchesFolder": true,
    "spritesheetExists": true
  },
  {
    "folder": "custom-pet-03",
    "id": "custom-pet-03",
    "displayName": "Custom Pet 03",
    "spritesheetPath": "spritesheet.webp",
    "idMatchesFolder": true,
    "spritesheetExists": true
  }
]

Why this may be useful

Earlier comments already show that custom pets work in Windows native mode but not in WSL mode, and one comment points to a mixed path such as C:\Users\<USER>\.codex/pets.

This newer-build data point suggests there may be two separately visible paths in the UI:

1. The Open folder path resolves correctly to <CODEX_HOME_WIN>\pets.
2. The refresh/list/load path still fails to discover the same valid packages and falls back to the built-in pet.

So the failing path may be specifically in the custom pet scan/list/load code path rather than in the folder-opening helper.

I can confirm this is still reproducible in Codex Desktop on Windows.

In Settings > Appearance, the Custom Pets location is displayed with mixed path separators:

C:\Users\<user>\.codex/pets

The expected Windows path display would be:

C:\Users\<user>\.codex\pets

Or, if this path is being passed to the renderer for asset loading, it likely needs to be converted to a proper file URL first, e.g.:

file:///C:/Users/<user>/.codex/pets/...

This looks like the pets directory is being constructed with a hardcoded POSIX suffix, such as appending /pets to a Windows %USERPROFILE%\.codex path, instead of using platform-aware path joining and URL conversion. Custom pets are discovered/shown in the UI, but the mixed root path appears consistent with the load failure.

Still reproducible on a substantially newer Codex Desktop build as of July 18, 2026.

Environment

• Windows 11 Pro 25H2, build 26200.8875, x64
• Codex Desktop package: OpenAI.Codex_26.715.3651.0_x64__2p2nqsd0c76g0
• WSL2: Ubuntu 22.04, kernel 6.18.33.2-microsoft-standard-WSL2
• Codex CLI/app-server side: codex-cli 0.144.3
• Codex Desktop is configured to use WSL

Reproduction / validation

A valid custom pet package exists in both Codex homes:

<WSL_CODEX_HOME>/pets/rourou/pet.json
<WSL_CODEX_HOME>/pets/rourou/spritesheet.webp

<WINDOWS_CODEX_HOME>/pets/rourou/pet.json
<WINDOWS_CODEX_HOME>/pets/rourou/spritesheet.webp

The metadata is valid and the folder id matches pet.json.id:

{
  "id": "rourou",
  "displayName": "肉肉 Rourou",
  "spritesheetPath": "spritesheet.webp"
}

The files on the Windows and WSL sides are byte-identical:

pet.json          SHA-256 9806da6574bc412ae98320fce75240c1277b71a4122bc6ab48af50761e1f6ccc
spritesheet.webp  SHA-256 09f494c0689bf14505f978b54596e8eada105e152fee865bc61d476697d24870

Despite this, refreshing custom pets in Windows Codex Desktop while the app-server is running through WSL does not make the custom pet available/loadable. The built-in pet remains the only usable pet.

This confirms the problem is still present in Desktop 26.715.3651.0; it is not caused by a missing package or Windows/WSL copies being out of sync. It remains consistent with the WSL custom-pet discovery/path-normalization failure described in this issue.

Reproduced on Codex Desktop 26.715.4045.0 on Windows with the Codex app server running in WSL.

I had 37 valid custom pet packages under %USERPROFILE%\.codex\pets. Settings showed built-in pets only, with no error. The failure was caused by custom-pet discovery combining a Windows CODEX_HOME path (C:\...) with POSIX path operations from the WSL app server; the resulting mixed path fails and the loader silently returns an empty custom-pet list.

A user-local patched copy that normalizes the Windows drive path to /mnt/c/... before joining the pets directory loaded all 37 pets successfully, including Zoro, Obito, and Sasuke. Selecting pets then worked normally.

One extra detail: a separate patched desktop executable must be launched only after fully exiting stock Codex, otherwise the app's single-instance handoff reopens the unpatched WindowsApps build.