# Codex CLI Configuration Guide

> Connect Codex CLI to the LLMoxy gateway via ~/.codex/config.toml with a custom model provider, using Grok 4.7 and other models for terminal programming.

> **📌 About Codex CLI**
> Codex CLI is OpenAI's official terminal coding agent, written in Rust, capable of reading, modifying, and running code locally ([open source](https://github.com/openai/codex)). It connects to OpenAI by default, but supports custom `model_provider`, so it can seamlessly connect to the LLMoxy gateway and use Grok 4.7 and other models.

## Installation Steps

### 1. Install Node.js

Visit the [Node.js official website](https://nodejs.org/). We recommend downloading the LTS version on the left, which is the long-term support version and more stable.

### 2. Install Codex CLI

Open a command line and install globally via npm:

```bash
npm install -g @openai/codex
```

macOS users can also use Homebrew:

```bash
brew install codex
```

Verify installation:

```bash
codex --version
```

Codex CLI supports macOS, Linux, and Windows. Windows users are recommended to run natively in PowerShell, or use WSL2 for a native Linux environment.

## Configuration Steps

Codex CLI's configuration file is located at `~/.codex/config.toml` (Windows: `%USERPROFILE%\.codex\config.toml`). Connecting to LLMoxy only requires two steps: **register a custom provider** + **provide API Key**.

### 1. Get API Key

Go to the [LLMoxy Console](https://llmoxy.com/) → API Key Management → Copy secret key.

> Note: Please use a token from the **auto** group.

### 2. Write config.toml

Add the following to `~/.codex/config.toml` (create if it does not exist):

```toml
# Default to LLMoxy provider and model
model = "grok-4.7"
model_provider = "llmoxy"

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

**Configuration item explanations:**

- `model` — Default model name, fill in a model supported by LLMoxy (e.g., `grok-4.7`)
- `model_provider` — Points to the provider ID defined below
- `base_url` — LLMoxy gateway address, **with** `/v1`
- `wire_api` — Use `responses` for `/v1/responses`. Codex supports only this value; `chat` fails with an error
- `env_key` — Environment variable name for storing the API Key, set in the next step

> **TIP**
> Unlike Claude Code, Codex CLI's `base_url` **must include** `/v1`.

### 3. Set API Key environment variable

The environment variable specified by `env_key` needs to be set with a real Key in the system.

**Windows (PowerShell, permanent):**

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

After setting, **close PowerShell and open a new window** for it to load.

**macOS / Linux:**

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

Verify:

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

You **must** replace `Your LLMoxy API Key` with the real Key copied from the [LLMoxy Console](https://llmoxy.com/).

### 4. Launch

Enter your project directory and start an interactive session:

```bash
codex
```

If you can chat and execute tasks normally, you have successfully connected to LLMoxy.

## Common Operations

### Switch model and reasoning intensity

Enter `/model` in the session to switch models or adjust reasoning effort. You can also specify at launch via `-m`:

```bash
codex -m grok-4.7
```

### Approval modes

Codex requests confirmation before editing files or executing commands. You can switch in the session with `/approvals`, or specify at launch:

```bash
codex --ask-for-approval      # Confirm each step (default, safest)
codex --full-auto             # Auto-execute, only within working directory in a network-restricted sandbox
```

> **💡 Tip**
> When running for the first time in a project directory, Codex will ask whether you trust that directory.

### Scripting (non-interactive)

Use the `exec` subcommand to hand one-off tasks to Codex, suitable for calling in scripts or CI:

```bash
codex exec "Add unit tests for ParseConfig in main.go"
```

### Image input

You can attach screenshots or design drafts to let Codex understand requirements combined with images:

```bash
codex -i screenshot.png "Implement the login page according to this design draft"
```

### Web search

Enable Web search to get the latest information:

```bash
codex --search
```

### Connect MCP tools

Register MCP services in `config.toml` via `[mcp_servers.*]` to provide third-party tools and context for Codex. This configuration can coexist with the LLMoxy provider configuration:

```toml
[mcp_servers.chrome-devtools]
command = "npx"
args = ["chrome-devtools-mcp@latest"]
```

## Common Issues

### `npm install -g` permission error

Do not use `sudo npm install -g`. We recommend using nvm to manage Node.js, or modify the npm global directory:

```bash
npm config set prefix ~/.npm-global
```

Then add `~/.npm-global/bin` to PATH. macOS users can also install Node.js via Homebrew (no sudo needed).

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

Confirm `model_provider = "llmoxy"` is active in `config.toml`, and the `LLMOXY_API_KEY` environment variable is set. After configuring a custom provider, Codex uses API Key authentication and does not require ChatGPT login.

### Error 404 / model does not exist

- Confirm `base_url` includes `/v1`: `https://llmoxy.com/v1`
- Confirm `model` is filled with a model name supported by LLMoxy
- Make sure `wire_api = "responses"`: Codex no longer supports `chat`, and the `wire_api = "chat"` from older guides fails with an error

### Environment variables not taking effect

- Windows: `SetEnvironmentVariable(...,"User")` requires **reopening the terminal**
- macOS / Linux: run `source ~/.zshrc` (or `~/.bashrc`), or reopen the terminal, then verify with `echo "$LLMOXY_API_KEY"`

### API call failure / balance issue

- Check that the API Key has no extra spaces
- Go to the [LLMoxy Console](https://llmoxy.com/) to check account balance and token group (recommended to use **auto** group)

### Remote server connection timeout (Linux)

- Check network: `curl -I https://llmoxy.com`
- If proxy is needed, configure the `HTTPS_PROXY` environment variable

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