> This page is for Gateway.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.merge.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server.

# Codex

> Register Gateway as a Codex model provider, opt in with a profile in the CLI, or set top-level defaults for the desktop app.

[Codex](https://developers.openai.com/codex) accepts custom model providers in `~/.codex/config.toml`. Register Gateway once, then opt in per launch with a profile or make it the desktop app's default. Shared setup: [Building with coding agents](/merge-gateway/coding-agents/overview).

## Configure the Codex CLI

Add the provider:

**`~/.codex/config.toml`**

```toml title="~/.codex/config.toml"
[model_providers.merge-gateway]
name = "Merge Gateway"
base_url = "https://api-gateway.merge.dev/v1/openai"
env_key = "MERGE_GATEWAY_API_KEY"
wire_api = "responses"
```

Codex 0.134 and later reads each profile from its own file, not a `[profiles.x]` table. Create `~/.codex/merge_gateway.config.toml`:

**`~/.codex/merge_gateway.config.toml`**

```toml title="~/.codex/merge_gateway.config.toml"
model_provider = "merge-gateway"
model = "openai/gpt-5.5"
model_reasoning_effort = "medium"
```

Export `MERGE_GATEWAY_API_KEY` and run `codex --profile merge_gateway`; plain `codex` keeps its existing provider. Add `-m "anthropic/claude-sonnet-5"` to switch models for one launch, or set `model = "@alias/coding-heavy"` to let a policy choose.

## Codex desktop app

The desktop app and IDE extension ignore `--profile` and read the top-level `model` and `model_provider` keys, so put them next to the provider block:

**`~/.codex/config.toml`**

```toml title="~/.codex/config.toml"
model = "openai/gpt-5.5"
model_provider = "merge-gateway"

[model_providers.merge-gateway]
name = "Merge Gateway"
base_url = "https://api-gateway.merge.dev/v1/openai"
env_key = "MERGE_GATEWAY_API_KEY"
wire_api = "responses"
```

Quit fully (**⌘Q**) and reopen. The picker shows OpenAI's catalog plus one **Custom** entry for `model`, so change `model` and relaunch to switch Gateway models.

Dock-launched macOS apps don't inherit your shell environment, so `env_key` resolves empty and auth fails. Run `launchctl setenv MERGE_GATEWAY_API_KEY "$MERGE_GATEWAY_API_KEY"` (lasts until logout), or add a LaunchAgent that runs it at login.

## Gotchas

* Keep `base_url` at `/v1/openai`. Codex appends `/responses`, and `/v1/openai/responses` returns the OpenAI Responses stream Codex parses. A bare `/v1` hits Gateway's native Responses API, which serves the OpenAI shape only by detecting Codex's `originator` header.
* Each Codex session groups into one thread in Logs, and each turn gets its own **Turn ID**, with no config

## Next steps

#### [Building with coding agents](/merge-gateway/coding-agents/overview)

Keys, models, aliases, and project scoping

#### [Tracing](/merge-gateway/observability/tracing)

Follow a Codex session's turns in Logs