Codex

Compatibility first

Standalone gateway only for coding agent workflows. Codex sends tool requests and maintains agent context. The current prepaid API rejects tool definitions, tool results, and stored response continuation. Buying credit or enabling customer BYOK does not remove these restrictions.

Prepare a standalone deployment, a dedicated managed gateway key, and a tool-capable model whose provider supports the gateway's Responses translation. A successful text response alone does not establish full Codex compatibility.

Configure the provider

Set the key in the environment used to launch Codex:

export ZROUTER_API_KEY="YOUR_MANAGED_GATEWAY_KEY"

Merge this configuration into ~/.codex/config.toml, preserving unrelated settings. Replace the model with an enabled gateway identifier and the URL with your standalone endpoint:

model = "PROVIDER_INSTANCE/MODEL_ID"
model_provider = "zrouter"

[model_providers.zrouter]
name = "ZRouter"
base_url = "https://STANDALONE_GATEWAY_HOST/v1"
env_key = "ZROUTER_API_KEY"
wire_api = "responses"
requires_openai_auth = false
supports_websockets = false

Codex custom providers use the Responses protocol. The URL includes /v1 once. WebSockets are disabled because this setup uses the gateway's HTTP/SSE endpoint. Custom provider selection belongs in user-level configuration; project-local provider settings are not applied. See Codex advanced configuration and the configuration reference.

Launch and verify

curl "https://STANDALONE_GATEWAY_HOST/v1/responses" \
  -H "Authorization: Bearer $ZROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"PROVIDER_INSTANCE/MODEL_ID","input":"Say hello","max_output_tokens":256,"store":false}'

codex

The curl request consumes provider tokens. Check that Codex selects ZRouter, then try a small task and review gateway logs for Responses and tool compatibility. Some model/provider combinations cannot satisfy all agent features.

IDE extension

Use the same user-level provider configuration for the Codex IDE extension. Make the environment key available to the extension process, then restart the editor. Do not assume an editor opened from the desktop inherits your shell variables. Keep provider secrets out of project configuration and source control.

Troubleshooting

• A missing environment-key error means ZROUTER_API_KEY is unavailable to that process.
• A /v1/v1/responses error means the API version was appended twice.
• A provider or model error requires an enabled gateway model that supports the requested behavior.
• A prepaid tool or continuation rejection means this deployment cannot serve full Codex sessions yet.

See shared troubleshooting. A ChatGPT subscription does not supply ZRouter credits or transfer subscription usage to this custom provider.