Copy page

Integrations

Codex

Codex is OpenAI's coding agent for the terminal. This guide routes its requests through the Zuplo AI Gateway.

Two approaches:

• Use a provider key. The gateway calls OpenAI with the API key saved on your provider. OpenAI bills that key's account.
• Use your ChatGPT subscription. Codex stays signed in with codex login. The gateway forwards that login to OpenAI and meters usage against an app. Your ChatGPT plan pays for the tokens.

Prerequisites

Create an OpenAI provider in the AI Gateway, then get a gateway URL and key in one of two ways:

• Use your personal API key (recommended). Codex runs on your own machine, so call the project's User App. Open the My Keys tab of your AI Gateway project, copy the Gateway URL, and create a key under My API keys. Your requests count against your own budget.
• Use an app. For a shared or automated setup, and for the ChatGPT subscription approach, create a pool and an app for Codex, then copy the app's API URL and API Key.

The rest of this guide calls these your gateway URL and gateway key.

Configure Codex

Codex reads configuration from ~/.codex/config.toml. Create this file (and the ~/.codex directory if needed) if it does not exist. Add the block for your approach, then set the API key in your environment and restart Codex:

Code
export ZUPLO_AI_GATEWAY_API_KEY="<your-gateway-key>"

Use a provider key

This example uses the User App's gateway URL. For an app, use the app's API URL instead.

Code
model_provider = "zuplo"
model = "openai/gpt-6.1-sol"

[model_providers.zuplo]
name = "Zuplo AI Gateway"
base_url = "https://my-gateway-main-2e18f50.zuplo.app/u/741d375d631b429293481d6d0458bb64/v1"
env_key = "ZUPLO_AI_GATEWAY_API_KEY"
wire_api = "responses"

• base_url is your gateway URL with /v1 appended.
• model is providerName/model.

Use your ChatGPT subscription

This approach is shown with an app. On the User App, turning on passthrough would change authentication for everyone who uses it, so use an app for subscription logins.

Code
model_provider = "zuplo"
model = "openai/gpt-6.1-sol"

[model_providers.zuplo]
name = "Zuplo AI Gateway"
base_url = "https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e/v1"
wire_api = "responses"
requires_openai_auth = true
env_http_headers = { "zp-gateway-api-key" = "ZUPLO_AI_GATEWAY_API_KEY" }

• requires_openai_auth = true makes Codex send your ChatGPT login in the Authorization header. Do not set env_key.
• env_http_headers sends the app's API key in the zp-gateway-api-key header, which is where the passthrough policy reads it.
• model must be a model your ChatGPT plan can use in Codex, with your provider name as the prefix.

Run codex login if you are not signed in. The gateway never sends your ChatGPT login anywhere except OpenAI, and never sends your app key to OpenAI.

Configure the API Key Authentication policy

On the pool's policy template, or on the app's Policies tab, edit API Key Authentication in the JSON editor:

Code
{
  "credentialPassthrough": true,
  "authHeader": "zp-gateway-api-key",
  "authScheme": ""
}

authScheme must be the empty string, not left blank. A blank field keeps the Bearer default and every request fails with 401 Invalid Authorization Scheme.

The provider still needs an API key saved. Passthrough requests never use it; Fallback Model targets do. A placeholder value works if nothing else uses it.

Rules

• model_provider = "zuplo" is required. Without it, Codex uses its built-in openai provider and bypasses the gateway.
• wire_api must be responses. Codex speaks only the Responses API; it removed support for /v1/chat/completions, and wire_api = "chat" fails to load.
• Put this configuration in the user-level file. Codex ignores model_provider and model_providers in a project-level .codex/config.toml.
• Do not use openai_base_url to point Codex at the gateway. That keeps Codex's built-in transport, which the gateway does not support.

Switch models

Set model in config.toml, or pass it on the command line:

Code
codex --config model_provider="zuplo" --model "openai/gpt-6.1-sol"

Do not use the /model picker. It sends model names without the provider prefix, and the gateway rejects them with a 400.

Codex warns that it has no metadata for a prefixed model name. Requests still succeed.

The Model Filtering policy on the User App or the app controls which models you can use.

Verify

Code
codex exec "Reply with the single word OK"

The session header shows provider: zuplo. With a personal key, the request appears in your usage on the My Keys tab; with an app, it appears in the app's usage in the Zuplo Portal.

Troubleshooting