# Codex

Codex talks to models through the Responses API. Add a provider that points at NezhaGate in config.toml and code with NezhaGate's GPT models.

> https://nezhagate.com/en/docs/integrations/codex

Written against Codex CLI 0.160

## Before you start

- Install the Codex CLI, or the Codex extension in VS Code, Cursor or Windsurf, and create an API key in the console.

- Codex only uses the OpenAI Responses API (`/v1/responses`), where NezhaGate serves the GPT models. For Claude, Gemini and the other models, use the chat endpoint or a tool such as [Claude Code](https://nezhagate.com/en/docs/integrations/claude-code).

Models you can use in Codex:

`gpt-5.6-sol` · `gpt-5.6-terra` · `gpt-5.6-luna` · `gpt-5.5` · `gpt-6-astra` · `gpt-6.1-sol` · `gpt-6-sol` · `gpt-6-luna`

## Add a provider in config.toml

Open `~/.codex/config.toml` (`%USERPROFILE%\.codex\config.toml` on Windows), create it if needed, and add:

```
model = "gpt-6.1-sol"
model_provider = "nezhagate"
web_search = "disabled"

[model_providers.nezhagate]
name = "NezhaGate"
base_url = "https://nezhagate.com/v1"
wire_api = "responses"
env_key = "NEZHAGATE_API_KEY"
```

- Top-level keys such as `model` and `model_provider` must come before the first `[...]` table, or Codex reads them as part of that table.

- `web_search = "disabled"`: Codex's built-in web search relies on an OpenAI-hosted tool that is not guaranteed through another provider, so turn it off.

- The provider must live in the user-level config.toml: `model_provider` in a project's `.codex/config.toml` is ignored. The provider id cannot be `openai`, `ollama` or `lmstudio`; Codex reserves them.

## Set the API key

Codex reads the key from the `NEZHAGATE_API_KEY` environment variable (the `env_key` above) and sends it as `Authorization: Bearer`; no `codex login` is needed.

```
export NEZHAGATE_API_KEY=YOUR_API_KEY
codex
```

```
setx NEZHAGATE_API_KEY "YOUR_API_KEY"
```

On macOS / Linux, put the `export` line in `~/.zshrc` or `~/.bashrc` so it sticks. On Windows, reopen the terminal or VS Code after `setx` so the variable is picked up.

## Run and test

Run the command below; a reply of `gateway-ok` means you are connected:

```
codex exec "Reply with exactly: gateway-ok"
```

- Type `/status` in Codex to see the current model and provider.

- To switch models, start with `codex -m gpt-6.1-sol` or change `model` in config.toml. Codex's `/model` menu lists its own built-in models only, not NezhaGate's list.

- Then ask for something that needs a tool (for example, list the files here) to check that tool calls work too.

## The IDE extension

The Codex extension in VS Code, Cursor and Windsurf reads the same config.toml: gear icon in the extension panel → **Codex Settings** → **Open config.toml**. Restart the editor after editing, and make sure an editor not launched from a terminal can see the API key variable.

## Troubleshooting

**Missing environment variable: `NEZHAGATE_API_KEY`**

The process that launched Codex cannot see the variable: set it in the same terminal before running; restart the IDE or desktop app, and on Windows reopen it after `setx`.

**`wire_api = "chat"` is no longer supported**

An old config: set `wire_api` to `"responses"`.

**unexpected status 401**

The key is wrong: check that it was copied in full without extra spaces, or whether it was disabled.

**unexpected status 404**

`base_url` is missing `/v1`. It should be `https://nezhagate.com/v1`; Codex appends `/responses` itself.

**Errors after choosing a Claude, Gemini or other non-GPT model**

Codex only uses `/v1/responses`, where NezhaGate serves the GPT models only. Switch to one of the GPT models listed above.

**stream disconnected before completion**

The stream was cut before it finished, usually by a local proxy or the network. Retry, and check your proxy if it keeps happening.