Merge API Documentation

Codex is OpenAI’s terminal coding agent. Add Merge Gateway as a model provider and Codex can use every model Gateway supports through a single API key, with routing policies, cost governance, and full request observability in the Gateway dashboard.

Before you start

Install Codex: npm install -g @openai/codex or follow the Codex install guide
Grab an API key from gateway.merge.dev/settings/api-keys
Decide which models fit your workflow. Gateway model names take the form provider/model, for example openai/gpt-5.1 for heavy coding or openai/gpt-4o for fast, low-cost edits. Browse the full catalog with GET /v1/models or in the dashboard.

Configure Codex

Codex 0.134+ uses a two-file layout: providers live in ~/.codex/config.toml and each profile lives in its own file at ~/.codex/<profile-name>.config.toml. This keeps your default codex behavior untouched and lets you opt in to Gateway with codex --profile merge_gateway.

Register Merge Gateway as a model provider

Add the following to ~/.codex/config.toml (create the file if it doesn’t exist):

1 [model_providers.merge-gateway]
2 name = "Merge Gateway"
3 base_url = "https://api-gateway.merge.dev/v1/openai"
4 env_key = "MERGE_GATEWAY_API_KEY"

env_key is the environment variable Codex reads for the API key, so export it in any shell where you launch Codex:

$ export MERGE_GATEWAY_API_KEY="mg_your_key"

Create the profile file

Create ~/.codex/merge_gateway.config.toml with top-level keys (no [profiles.x] wrapper):

1 model_provider = "merge-gateway"
2 model = "openai/gpt-5.1"
3 model_reasoning_effort = "medium"

These are examples: a capable coding model and a moderate reasoning budget. Swap model to any Gateway provider/model slug from GET /v1/models, and adjust model_reasoning_effort to taste.

Launch Codex with the profile

In your project, run:

$ codex --profile merge_gateway

Codex applies the profile on top of your defaults, so your normal codex (without --profile) keeps its existing model and provider.

Send a test message

Ask Codex to make a small code change. Streaming, tool calls, and file edits all work, and the request shows up in your Gateway dashboard within a few seconds.

Codex desktop app

The steps above use the CLI’s --profile flag. The Codex desktop app (and the IDE extension) don’t accept --profile — they read the top-level model and model_provider keys from ~/.codex/config.toml. To make the desktop app default to Gateway, put the provider block and the defaults at the top level of config.toml (not in a separate profile file):

1 # top-level keys — read by the Codex desktop app
2 model = "openai/gpt-5.6-sol"
3 model_provider = "merge-gateway"
4 model_reasoning_effort = "high"
5 model_catalog_json = "/Users/you/.codex/mgw-model-catalog.json"
6 
7 [model_providers.merge-gateway]
8 name = "Merge Gateway"
9 base_url = "https://api-gateway.merge.dev/v1/openai"
10 env_key = "MERGE_GATEWAY_API_KEY"
11 wire_api = "responses"

Then fully quit the app (⌘Q) and reopen it so it reloads config.toml.

macOS GUI apps don’t inherit your shell environment. When Codex is launched from the Dock it won’t see MERGE_GATEWAY_API_KEY even if it’s exported in ~/.zshrc, so env_key resolves empty and auth fails. Expose the key to the GUI session:

$ launchctl setenv MERGE_GATEWAY_API_KEY "$MERGE_GATEWAY_API_KEY"

This lasts until you log out; to persist it across reboots, add a LaunchAgent that runs the same command at login. The CLI, run from a terminal, inherits the variable normally and doesn’t need this.

Switching models in the desktop app is limited. The desktop model picker is populated from OpenAI’s account model catalog (fetched remotely and cached in ~/.codex/models_cache.json), plus a single Custom entry for the top-level model you set above — it does not read model_catalog_json. To use a different Gateway model in the desktop app, change the top-level model and relaunch.

The full multi-model experience lives in the Codex CLI/TUI: model_catalog_json feeds the CLI’s model list, and you can select any Gateway model per launch with codex --profile merge_gateway -m "provider/slug" (or codex exec -m "provider/slug").

Caveats

Profile files live alongside config.toml

Codex 0.134+ rejects the legacy [profiles.x] table inside ~/.codex/config.toml. Each profile is a separate file at ~/.codex/<profile-name>.config.toml with top-level keys. The provider block ([model_providers.x]) stays in the main config.toml. See the Codex profile docs for details.

Let Gateway choose the model

Instead of hard-picking a model, point at a routing policy and let Gateway select the vendor and model per request based on your rules (cost, performance, or prompt complexity). Useful when you want cheap models for simple edits and stronger models for hard problems without switching by hand.

Persisting the configuration

The export MERGE_GATEWAY_API_KEY=... above lives in your shell, so it applies only to that terminal. To persist it, add the same line to your shell profile (~/.zshrc, ~/.bashrc, or ~/.config/fish/config.fish). The provider block in ~/.codex/config.toml and the profile file at ~/.codex/merge_gateway.config.toml are read on every Codex launch, so those persist automatically.

Tool calling

Codex is agentic and relies on tool calls to read and edit files. Tool calling works through Gateway for any model whose capabilities.supports_tool_calling is true on the chosen vendor route. See Tool calling.

Which models can I use?

Any model Gateway supports. Use GET /v1/models to list them, or open the Gateway dashboard and copy the model identifier.

Next steps

Routing policies

Let Gateway pick the best vendor for each Codex request

Projects

Use a project-scoped key so Codex usage is tracked separately

Cost governance

Cap spend and restrict which models Codex can hit