FeaturesBuilding with coding agents

Codex

Route Codex through Merge Gateway with a custom model provider in ~/.codex/config.toml

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.

1

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]
2name = "Merge Gateway"
3base_url = "https://api-gateway.merge.dev/v1/openai"
4env_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"
2

Create the profile file

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

1model_provider = "merge-gateway"
2model = "openai/gpt-5.1"
3model_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.

3

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.

4

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.

Caveats

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.

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.

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.

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.

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