Codex WSL Terminal Flashes and Closes? Switch the Agent Host

If the integrated terminal in Codex Desktop flashes open and immediately closes only when Agent environment is set to WSL, switch the agent host to Windows native, restart Codex, and then choose WSL as the integrated terminal shell if you still want a Linux prompt.

That combination is the important workaround:

Agent environment: Windows native
Integrated terminal: WSL

An August 5 reproduction on Codex Desktop 26.730.8199.0 found that both PowerShell and WSL terminal profiles worked under the Windows-native agent host. Both profiles failed under the WSL agent host, even though WSL itself worked outside Codex. The upstream bug is still open, so treat this as a bounded workaround rather than an official fix.

Confirm the WSL Agent-Host Failure

Prerequisites

• Codex Desktop is running on Windows.

• WSL2 and at least one Linux distribution are installed.

• You can save any active terminal work before restarting Codex.

• You know your current Agent environment and integrated terminal selections.

First, verify WSL independently from PowerShell:

wsl --status
wsl --list --verbose

Expected result: your intended distribution appears in the list with VERSION set to 2. Note its exact name, such as Ubuntu, then run a harmless command inside it:

wsl -d Ubuntu -- sh -lc 'printf "terminal-ok\n"; pwd'

Expected result:

terminal-ok
/your/current/wsl/path

Replace Ubuntu with the distribution name from wsl --list --verbose. If this command fails, the problem is not limited to Codex's integrated terminal. Skip to When WSL itself does not start.

Now test the two independent Codex settings:

1. Record the current Agent environment under Codex settings.

2. Record the selected integrated terminal shell.

3. With the Agent environment set to WSL, restart Codex.

4. Open a task and press Ctrl+J, use the terminal button, or select View > Open Terminal.

5. Repeat once with PowerShell selected as the terminal shell and once with WSL selected.

The reported failure matrix was:

This matrix matters more than the shell label alone. If changing only the terminal shell does not help, but changing the Agent environment does, you have isolated the failure to the agent-host boundary.

Switch the Agent Host to Windows Native

1. Open Codex Desktop settings.

2. Find Agent environment.

3. Select Windows native.

4. Leave your integrated terminal set to WSL if that is the shell you want.

5. Fully restart Codex. OpenAI's Windows documentation says an Agent environment change does not take effect until restart.

6. Reopen the same project and open the terminal.

7. Run a read-only shell check:

printf 'terminal-ok\n'
pwd
git status --short

Expected result: the bottom panel remains visible, terminal-ok prints once, pwd shows the expected project location, and git status --short reports the repository state without changing it.

The Codex agent now executes through the Windows-native host, but the integrated terminal can still be WSL. OpenAI documents these as separate settings. You do not need to abandon your Linux shell merely to route the agent through the host that keeps the panel open.

Why This Workaround Works

The controlled comparison narrows the failure to the agent host, not to the selected terminal shell:

Agent host starts Codex runtime
  -> integrated terminal request is routed
  -> selected PowerShell or WSL shell starts
  -> bottom panel stays mounted

In the reported build, changing the shell did not alter the result while the Agent environment remained WSL. Switching the Agent environment to Windows native restored both shell options immediately. The same report confirmed that the WSL application server initialized and that the distribution accepted commands outside Codex.

That makes the host boundary the smallest supported target for a workaround. It does not prove the underlying product root cause. One reporter observed a missing bundled bwrap resource and an earlier child exit code of 127, while a second same-day issue described a failure before terminal process startup. OpenAI has not confirmed that either observation causes the panel to close.

Avoid Destructive Look-Alike Fixes

Do not unregister or reinstall your distribution

wsl --unregister deletes the selected distribution and its data. A healthy wsl -d <distribution> -- ... result already shows that reinstalling the distribution targets the wrong layer.

Do not keep changing only the terminal shell

The terminal shell and Agent environment are separate. In the reported reproduction, PowerShell and WSL both failed under the WSL agent host and both worked under the Windows-native host.

Do not assume Windows sandbox setup caused this symptom

One reporter completed elevated Windows sandbox setup successfully and still reproduced the terminal failure. Treat a sandbox-setup error as a separate problem unless your own A/B test links it to the panel.

Do not treat generic panel advice as a verified fix

OpenAI's troubleshooting guide recommends closing and reopening a stuck terminal panel. That is reasonable for a panel that remains visible but stops responding. A panel that flashes and immediately disappears under one Agent environment has a more specific boundary.

When WSL Itself Does Not Start

If the independent PowerShell check fails, use Microsoft's WSL diagnostics before changing Codex:

wsl --status
wsl --list --verbose

Close work running in every distribution before using:

wsl --shutdown

That command stops all running WSL distributions. Start the intended distribution again and repeat the harmless terminal-ok command. If WSL remains unhealthy, resolve that platform issue first. Switching Codex to Windows native can keep the agent usable, but it does not repair WSL.

If Windows Native Does Not Restore the Terminal

Fully quit Codex, reopen it, and confirm the Agent environment still reads Windows native. Then try the official terminal troubleshooting sequence: close the panel, reopen it, and run pwd or git status.

If the panel still closes, report the issue from Codex with /feedback. Include:

• Codex Desktop package version.

• Windows version and build.

• wsl --list --verbose output with private distribution names redacted if needed.

• The four-row Agent environment and terminal shell matrix.

• Whether the same WSL command succeeds from PowerShell.

• Whether restarting after the setting change altered the result.

Do not attach unredacted logs until you have checked them for usernames, paths, repository names, prompts, and environment values.

Keep Structured Actions Available

The integrated terminal is useful for local repository commands. Connected Actions are a separate route for structured services such as analytics, search, issue trackers, and publishing systems. Aident Loadout lets the same agent inspect an Action contract and estimate its cost before execution.

From the restored terminal, check the installed public CLI:

aident account auth status
aident vault vault --action status

aident capabilities search \
  --targetEnv staging \
  --types '["action"]' \
  --queries '["one read-only Action for my current task"]'

Use the exact Action name returned by search with aident capabilities get, then call aident capabilities preflight before execution. Expected result: authentication and Vault status are visible, and the Action contract can be reviewed without copying provider credentials into the terminal.

Follow https://aident.ai/SETUP.md to set up Aident Loadout, then preflight one read-only Action.

Sources

• OpenAI: Codex app on Windows

• OpenAI: Codex app troubleshooting

• OpenAI Codex issue 25256: bottom panel flashes and disappears

• OpenAI Codex issue 37104: WSL integrated terminal fails before startup

• Microsoft: Basic commands for WSL

Review this article when either upstream issue closes, OpenAI changes the Windows Agent environment controls, or a Codex Desktop release documents a permanent terminal fix.