Codex

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.

Configure the Codex CLI

Add the provider:

[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:

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:

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