> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yelu.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Codex CLI

> Configure OpenAI Codex CLI to use Yelu AI API on macOS, native Windows, and WSL 2 through the Responses API.

Codex CLI supports custom model providers. Configure a user-level `yelu` provider to send Responses API requests to `https://api.yelu.ai/v1` with your Yelu API key.

<Info>
  The configuration below uses `gpt-5.4`, a coding-capable model recognized by the Yelu gateway. Model access is account-specific; confirm availability with [`GET /v1/models`](/en/api-reference/models).
</Info>

## Configuration at a glance

| Setting                  | Value                                               |
| ------------------------ | --------------------------------------------------- |
| Provider ID              | `yelu`                                              |
| Base URL                 | `https://api.yelu.ai/v1`                            |
| Key environment variable | `YELU_API_KEY`                                      |
| Wire API                 | `responses`                                         |
| Example model            | `gpt-5.4`                                           |
| User configuration       | `$CODEX_HOME/config.toml` or `~/.codex/config.toml` |

Unlike Claude Code, Codex requires the `/v1` suffix because its provider base URL is the OpenAI-compatible API root.

## macOS

### 1. Install Codex

Use the official standalone installer:

```bash macOS theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex --version
```

Homebrew and npm are also supported:

<CodeGroup>
  ```bash Homebrew theme={"theme":{"light":"github-light","dark":"github-dark"}}
  brew install --cask codex
  ```

  ```bash npm theme={"theme":{"light":"github-light","dark":"github-dark"}}
  npm install -g @openai/codex
  ```
</CodeGroup>

### 2. Set the key

```bash macOS theme={"theme":{"light":"github-light","dark":"github-dark"}}
read -s "YELU_API_KEY?Yelu API key: "
echo
export YELU_API_KEY
```

The key remains available to processes started from this terminal and is not written to shell history. For persistent use, load it from macOS Keychain or another secret manager in your shell startup.

### 3. Create the provider configuration

Create `~/.codex/config.toml` and add:

```toml ~/.codex/config.toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
model = "gpt-5.4"
model_provider = "yelu"
model_reasoning_effort = "medium"

[model_providers.yelu]
name = "Yelu AI API"
base_url = "https://api.yelu.ai/v1"
env_key = "YELU_API_KEY"
wire_api = "responses"
```

Provider settings must be in the user-level file. Codex intentionally ignores `model_provider` and `model_providers` in a project-local `.codex/config.toml`.

## Windows

### Native PowerShell

Install Codex using the official Windows installer:

```powershell Windows PowerShell theme={"theme":{"light":"github-light","dark":"github-dark"}}
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
codex --version
```

Set the key for the current session without echoing it:

```powershell Windows PowerShell theme={"theme":{"light":"github-light","dark":"github-dark"}}
$secret = Read-Host "Yelu API key" -AsSecureString
$env:YELU_API_KEY = [System.Net.NetworkCredential]::new("", $secret).Password
```

Create `%USERPROFILE%\.codex\config.toml`:

```powershell Windows PowerShell theme={"theme":{"light":"github-light","dark":"github-dark"}}
New-Item -ItemType Directory -Force "$HOME\.codex" | Out-Null
@'
model = "gpt-5.4"
model_provider = "yelu"
model_reasoning_effort = "medium"

[model_providers.yelu]
name = "Yelu AI API"
base_url = "https://api.yelu.ai/v1"
env_key = "YELU_API_KEY"
wire_api = "responses"
'@ | Set-Content -Encoding utf8 "$HOME\.codex\config.toml"
```

To make the key available in future terminals, use a Windows secret manager. If you choose a user environment variable for convenience, remember that it is stored as plain user configuration rather than in a dedicated secret vault.

Native Codex on Windows uses the Windows sandbox. The default is appropriate for most projects; do not switch to unrestricted execution just to work around a project permission error.

### WSL 2

Use WSL 2 when your repository and tools live in Linux:

```powershell Administrator PowerShell theme={"theme":{"light":"github-light","dark":"github-dark"}}
wsl --install
wsl
```

Then install and configure Codex inside WSL:

```bash WSL 2 theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -fsSL https://chatgpt.com/codex/install.sh | sh
read -rsp "Yelu API key: " YELU_API_KEY; echo
export YELU_API_KEY
mkdir -p ~/.codex
codex --version
```

Put the same TOML provider block in the WSL file `~/.codex/config.toml`. The Windows and WSL Codex installations use separate home directories, keys, and configuration files. Keep WSL projects under `~/code` instead of `/mnt/c` for better filesystem performance.

## Verify the API and configuration

First confirm that the key can see the model:

<CodeGroup>
  ```bash macOS / WSL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -sS https://api.yelu.ai/v1/models \
    -H "Authorization: Bearer $YELU_API_KEY"
  ```

  ```powershell Windows PowerShell theme={"theme":{"light":"github-light","dark":"github-dark"}}
  Invoke-RestMethod `
    -Uri "https://api.yelu.ai/v1/models" `
    -Headers @{ Authorization = "Bearer $env:YELU_API_KEY" }
  ```
</CodeGroup>

Validate the local configuration and run a read-only smoke test from a Git repository:

```bash Terminal theme={"theme":{"light":"github-light","dark":"github-dark"}}
codex --strict-config --version
codex exec --strict-config --ephemeral --sandbox read-only \
  "Reply with exactly: Yelu Codex is ready"
```

Inside an interactive session, run `/status` to confirm that the provider is `yelu`, the model is `gpt-5.4`, and the active directory is correct.

## Safe defaults

* Keep `YELU_API_KEY` in an environment variable or secret manager; never place the key directly in TOML.
* Start unfamiliar repositories with `--sandbox read-only` or use `/permissions` before allowing edits.
* Use `workspace-write` only when the task should modify the current workspace.
* Review the diff and run tests before accepting generated changes.
* Avoid `--dangerously-bypass-approvals-and-sandbox` on a normal workstation.

## Troubleshooting

| Symptom                        | Fix                                                                                                      |
| ------------------------------ | -------------------------------------------------------------------------------------------------------- |
| `YELU_API_KEY` is missing      | Set it in the same terminal that launches Codex, then restart Codex.                                     |
| Requests go to OpenAI          | Check that `model_provider = "yelu"` is in the user-level `config.toml`, not only a project config.      |
| `404` or malformed URL         | Use `base_url = "https://api.yelu.ai/v1"` exactly.                                                       |
| Unknown model                  | Query [`GET /v1/models`](/en/api-reference/models) and set an enabled Responses-compatible coding model. |
| Config key rejected            | Update Codex, then run with `--strict-config` to identify the unsupported key.                           |
| WSL cannot see the Windows key | Export `YELU_API_KEY` inside WSL; Windows and WSL environments are separate.                             |
| Native Windows sandbox fails   | Run `codex doctor`; use WSL 2 if the native sandbox is incompatible with the workstation policy.         |

## Next step

Continue with the [Codex CLI examples](/en/examples/codex-cli) for exploration, implementation, review, image input, and automation.

## Official references

* [Codex CLI](https://learn.chatgpt.com/docs/codex/cli)
* [Codex configuration basics](https://learn.chatgpt.com/docs/config-file/config-basic)
* [Codex configuration reference](https://learn.chatgpt.com/docs/config-file/config-reference)
* [Codex on WSL](https://learn.chatgpt.com/docs/windows/wsl)