Codex on Windows: native and WSL install with a gateway

OpenAI's Codex CLI runs on Windows in two ways: natively in PowerShell and inside WSL2. The choice affects the install path, where the config lives and how the sandbox behaves. Below: how to install Codex on Windows, how to connect it to the Zukko gateway and how to handle common problems.

Install commands and sandbox details come from the README of github.com/openai/codex and OpenAI's Codex documentation as of October 18, 2026. Versions change, so trust the documentation if anything differs.

Native or WSL

According to OpenAI's documentation, on Windows you should use the native sandbox by default. WSL2 is chosen when you need Linux tooling, when your repositories and workflow already live in WSL2, or when the native sandbox options do not fit. WSL1 was supported up to Codex 0.114 and is not supported from 0.115.

As for the Windows version: Windows 11 is listed as the recommended baseline. Windows 10 needs a modern console (ConPTY), in practice version 1809 or newer, and is described as best effort. The documentation also says winget should be available.

Native installation

The official PowerShell installer, as in the README:

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

The script downloads and runs code from the internet. If you prefer not to do that, install via npm (Node.js is required):

npm install -g @openai/codex

After installing, run codex --version in a new PowerShell window to make sure the command is visible.

The sandbox

On Windows Codex runs commands in a sandbox. The documentation lists three implementations: mxc (recommended on compatible devices, requires OS-level support in Windows 11 24H2 or 25H2 at a suitable build), elevated (a fallback that needs administrator approval during setup) and unelevated (a weaker fallback with weaker network isolation). You can choose a fallback in config.toml:

[windows]
sandbox = "elevated" # or "unelevated"

If elevated sandbox setup fails, the documentation names typical causes: a declined UAC prompt, a ban on creating local users or firewall rules, and corporate policies. You can then temporarily switch to unelevated if company policy allows. Error 1385 is described separately: Windows denies the logon type that the sandbox users need, which is solved at the device policy level, and when contacting support it helps to attach CODEX_HOME\.sandbox\sandbox.log.

Installation in WSL2

In PowerShell as administrator:

wsl --install
wsl

Then in the WSL shell:

curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex

Two recommendations from the documentation. Keep repositories in the Linux home directory (~/code/...) rather than in /mnt/c/...: I/O is faster and there are fewer permission and symlink problems. If you need access from Windows, the files are available at \\wsl$\Ubuntu\home\<user> in Explorer. For the VS Code extension in this mode, start it from a window opened in WSL (code . from the WSL shell): this opens a WSL remote window, and the integrated terminal runs in Linux.

Connecting to the Zukko gateway

Codex reads config.toml from the .codex folder in the home directory: on Windows that is %USERPROFILE%\.codex\config.toml, in WSL it is ~/.codex/config.toml inside Linux. These are different files: a setting made in Windows is not visible from inside WSL, and vice versa. If you use both, configure both.

The config file:

model = "gpt-6.1-sol"
model_provider = "zukko"
model_reasoning_effort = "medium"

[model_providers.zukko]
name = "zukko"
base_url = "https://api.zukko.pro/v1"
env_key = "ZUKKO_API_KEY"
wire_api = "responses"

Create the fetch_... key in the dashboard↗. Pass it through an environment variable. In PowerShell at user level:

[Environment]::SetEnvironmentVariable("ZUKKO_API_KEY", "fetch_your_key", "User")

Open a new PowerShell window so the variable is picked up. In WSL add the line export ZUKKO_API_KEY=fetch_your_key to ~/.bashrc and restart the shell.

Notes. base_url carries the /v1 suffix, like for any OpenAI-compatible client. wire_api = "responses": per OpenAI's documentation this is the only supported value, and Codex talks through the Responses API, which the gateway supports (POST /v1/responses). The Zukko documentation for Codex describes another method too: requires_openai_auth = true with the key in %USERPROFILE%\.codex\auth.json as { "OPENAI_API_KEY": "fetch_..." }. That works as well; if you create the file from PowerShell, write it as UTF-8 without BOM, or the JSON may fail to parse. Current details: the Codex documentation↗.

According to the Zukko documentation, GPT and Claude models work through Codex, while GLM models do not. So for a first test use gpt-6.1-sol or claude-sonnet-5-5. GET https://api.zukko.pro/v1/models returns the available models. If the key is restricted to a model list, add the one you picked.

First run and a check

Go to the project directory (a Windows path in native mode, a Linux path in WSL) and run:

codex "briefly describe the structure of this project"

To estimate spend: suppose a trial session made 10 requests of 20,000 input and 500 output tokens each. Input 200,000, output 5,000. On gpt-6.1-sol (input $0.27, output $1.32 per 1M, prices as of October 18, 2026): 0.2 × 0.27 + 0.005 × 1.32 = 0.054 + 0.0066 = $0.0606. The real amount depends on the project; rely on the spending history in the dashboard.

Typical errors

• codex not found. Open a new terminal window; with an npm install check that the global packages directory is in PATH. In WSL run which codex.
• 401. The ZUKKO_API_KEY variable is not visible to the process: the terminal was started before it was created, or there is a typo in the name. Check echo $env:ZUKKO_API_KEY in PowerShell.
• 404 on every request. /v1 is missing from base_url, or the model name is wrong (404 model_not_found).
• 402. Not enough balance. Top up with SBP (the payment page adds an 8.5% fee on top), cryptocurrency or MasterCard cards.
• Sandbox setup failure. See the sandbox section above; ask the computer's administrator about policy.
• The VS Code extension is unresponsive. OpenAI's documentation names missing Visual C++ components (Build Tools and the Redistributable) as the cause; after installing, fully restart VS Code.

For the general picture of connection errors see 401, 402, model not found: error breakdown↗. For another agent's approach see Claude Code on Windows↗.

FAQ

Do I have to install Codex for Windows through WSL?

No. OpenAI's documentation calls the native sandbox the default, and WSL2 the choice for those who need a Linux toolchain.

Can I use a ChatGPT subscription and Zukko at the same time?

Codex supports sign-in with ChatGPT and sign-in with an API key. See OpenAI's site for subscription terms. With the env_key approach the Zukko provider is configured separately from the account sign-in, but the selected model_provider decides where requests go.

Where is the config if I use both Windows and WSL?

In two places: %USERPROFILE%\.codex\config.toml on Windows and ~/.codex/config.toml inside Linux. The files are independent.

Which model should I start with?

gpt-6.1-sol or claude-sonnet-5-5 is fine for a first check. Test quality on your own task by comparing price and result.

Create a key in the Zukko dashboard, add the provider to config.toml and run a first task on a small repository.