# Codex App Configuration Guide

> Install OpenAI Codex App on macOS and Windows, and connect to LLMoxy Grok 4.7 via config.toml.

> **Scope**
> This article only covers connecting Codex App to LLMoxy, with the example model uniformly using `grok-4.7`. For the terminal version, please refer to the "Codex CLI Configuration Guide".

![Codex App Interface Preview](https://en.llmoxy.com/docs-assets/migrated/tutorial-codex-app/app-screenshot-light.webp)

## Preparation

Prepare three things before starting:

1. An active [LLMoxy](https://llmoxy.com/) account
2. An **auto** group LLMoxy API Key
3. The model name used uniformly in this article: `grok-4.7`

Codex App shares the Codex configuration layer with Codex CLI and IDE plugins. User-level configuration is usually placed in `~/.codex/config.toml`; in Windows native mode it corresponds to `%USERPROFILE%\.codex\config.toml`.

## Universal LLMoxy Configuration

The following macOS, Windows Native, and Windows + WSL sections all use the same configuration. Write it to the `config.toml` in the corresponding environment:

```toml
model_provider = "llmoxy"
model = "grok-4.7"
model_reasoning_effort = "high"
model_verbosity = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[model_providers.llmoxy]
name = "LLMoxy"
base_url = "https://llmoxy.com/v1"
wire_api = "responses"
requires_openai_auth = false
env_key = "LLMOXY_API_KEY"
```

Configuration meanings:

- `model_provider = "llmoxy"`: Default to the LLMoxy Provider defined below
- `model = "grok-4.7"`: Default to calling Grok 4.7 on LLMoxy
- `base_url = "https://llmoxy.com/v1"`: Codex OpenAI compatible endpoint needs `/v1`
- `wire_api = "responses"`: Use `/v1/responses`. Codex supports only this value; `chat` fails with an error
- `env_key = "LLMOXY_API_KEY"`: API Key is read from environment variables, not written into the config file
- `approval_policy` and `sandbox_mode`: Keep confirmation and workspace sandbox, suitable for ordinary users getting started

## macOS Installation and Configuration

### 1. Install Codex App

Open the official macOS download address:

- [https://persistent.oaistatic.com/codex-app-prod/Codex.dmg](https://persistent.oaistatic.com/codex-app-prod/Codex.dmg)

After downloading, double-click `.dmg` and drag Codex into `Applications` as prompted by the system.

### 2. Write configuration file

Open a terminal and create the Codex configuration directory:

```bash
mkdir -p ~/.codex
open -a TextEdit ~/.codex/config.toml
```

Paste the "Universal LLMoxy Configuration" above and save.

### 3. Set API Key

The default Shell on macOS is usually Zsh; write to `~/.zshrc`:

```bash
{
echo ''
echo '# LLMoxy'
echo 'export LLMOXY_API_KEY="Your LLMoxy API Key"'
} >> ~/.zshrc
source ~/.zshrc
```

Verify:

```bash
echo "$LLMOXY_API_KEY"
```

You must replace `Your LLMoxy API Key` with the real token copied from the console.

### 4. Open project to verify

Launch Codex App, select a code directory, and send a lightweight task:

```text
Explain the current project structure and point out where the entry file is.
```

If Codex can read the project and reply normally, the macOS side is connected to LLMoxy.

## Windows Native Installation and Configuration

![Codex App Windows Interface](https://en.llmoxy.com/docs-assets/migrated/tutorial-codex-app/codex-windows-light.webp)

Windows uses **Windows Native Agent** by default; commands execute in the PowerShell environment, and the configuration file is under the Windows user directory.

### 1. Install Codex App

Choose either method:

- Microsoft Store page: [Codex App](https://apps.microsoft.com/detail/9plm9xgg6vks?hl=en-US&gl=US)
- PowerShell installation:

```powershell
winget install Codex -s msstore
```

### 2. Write configuration file

Create and open the configuration file with PowerShell:

```powershell
New-Item -ItemType Directory -Force "$HOME\.codex"
notepad "$HOME\.codex\config.toml"
```

Paste the "Universal LLMoxy Configuration" and save.

The actual path is usually similar to:

```text
C:\Users\YourUsername\.codex\config.toml
```

### 3. Set API Key

We recommend writing to Windows user-level environment variables:

```powershell
[Environment]::SetEnvironmentVariable("LLMOXY_API_KEY","Your LLMoxy API Key","User")
```

Close Codex App and PowerShell, reopen and verify:

```powershell
echo $env:LLMOXY_API_KEY
```

### 4. Open project to verify

Launch Codex App, add a project directory, then send:

```text
Run git status and explain the current workspace state.
```

If PowerShell execution policy blocks script execution, you can run in PowerShell:

```powershell
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
```

If Git functionality is unavailable, install native Git first:

```powershell
winget install Git.Git
```

## Windows + WSL Configuration

If your project is mainly developed in the Linux toolchain, you can switch the Codex Agent to WSL.

![Switch to WSL Agent](https://en.llmoxy.com/docs-assets/migrated/tutorial-codex-app/wsl-select-light.webp)

### 1. Switch Agent

In Codex App, open `Settings`, switch Agent from Windows Native to WSL, then restart the App. This setting takes effect after restart.

### 2. Write WSL internal configuration

After switching to the WSL terminal, create the configuration:

```bash
mkdir -p ~/.codex
nano ~/.codex/config.toml
```

Write the "Universal LLMoxy Configuration" to `~/.codex/config.toml` inside WSL.

### 3. Set WSL internal API Key

Bash users:

```bash
{
echo ''
echo '# LLMoxy'
echo 'export LLMOXY_API_KEY="Your LLMoxy API Key"'
} >> ~/.bashrc
source ~/.bashrc
```

Zsh users:

```bash
{
echo ''
echo '# LLMoxy'
echo 'export LLMOXY_API_KEY="Your LLMoxy API Key"'
} >> ~/.zshrc
source ~/.zshrc
```

Verify:

```bash
echo "$LLMOXY_API_KEY"
```

Windows Native and WSL are two separate environments. When Agent runs in WSL, you need to modify `~/.codex/config.toml` in WSL and set `LLMOXY_API_KEY` in WSL.

## Common App Settings

### Default editor

You can select the default `Open In` editor in settings, such as VS Code or Visual Studio.

![Set default editor](https://en.llmoxy.com/docs-assets/migrated/tutorial-codex-app/open-in-windows-light.webp)

### Integrated terminal

Under Windows, the integrated terminal can choose PowerShell, Command Prompt, Git Bash, or WSL. This setting and the Agent runtime environment are two different things: you can let Agent run in WSL while the integrated terminal still uses PowerShell.

![Set integrated terminal](https://en.llmoxy.com/docs-assets/migrated/tutorial-codex-app/integrated-shell-light.webp)

After modifying the terminal, it usually only takes effect for new sessions; restart Codex App if necessary.

## Common Issues

### Still asks to log in to OpenAI after launch

Confirm that `config.toml` in the current environment has been written:

```toml
model_provider = "llmoxy"
```

And confirm that `LLMOXY_API_KEY` can be read in the same environment. When using the LLMoxy Provider, Codex uses the API Key from the environment variable to call LLMoxy; there is no need to write the secret key into the config file.

### 404 or model does not exist

Check three items:

1. `base_url` must be `https://llmoxy.com/v1`
2. `model` must be `grok-4.7`
3. API Key should use an **auto** group token

### Windows and WSL configuration inconsistent

See which environment the Agent is running in:

- Windows Native: modify `%USERPROFILE%\.codex\config.toml`, set Windows user environment variable
- WSL: modify `~/.codex/config.toml` inside WSL, set WSL Shell environment variable

### Want to reset to more conservative permissions

Keep the following configuration:

```toml
approval_policy = "on-request"
sandbox_mode = "workspace-write"
```

This will make Codex ask before going beyond the sandbox or performing sensitive operations.

## Reference Links

- [OpenAI Codex App](https://developers.openai.com/codex/app/)
- [OpenAI Codex App for Windows](https://developers.openai.com/codex/app/windows/)
- [OpenAI Codex Basic Config](https://developers.openai.com/codex/config-basic)
- [OpenAI Codex Auth Guide](https://developers.openai.com/codex/auth)

This is the markdown version of https://en.llmoxy.com/docs/code-tutorials/codex-app.
