Codex live voice

Before you connect §

1. Use a Codex client that supports live voice and allow microphone access. Voice controls and experimental settings depend on the client version.
2. Create a Codex subscription group in GPT-Load, then authorize it with OAuth or import subscription credentials. The upstream account must actually have voice access; successful text requests do not establish voice eligibility.
3. Create an AccessKey that allows the Codex group. If protocol filters are set, allow both codex-live (voice) and openai-responses (text). If model filters are set, also allow the voice model requested by the client.

You do not need to add the voice model to the group's model list. The client's model is passed upstream unchanged; the default is gpt-live-1-codex when omitted. This uses the Codex subscription channel, not an ordinary OpenAI API key as a subscription credential.

Authorize or import subscription accounts →

Choose a voice mode §

Set the default under System settings → Connections and timeouts → Live voice. A Codex group's Advanced configuration / Runtime parameters can inherit or override it; different groups may use different modes.

In both enabled modes, GPT-Load authenticates the request, selects an account, creates the session, and proxies the control WebSocket. Upstream account tokens are never handed to the client. Only the media path differs: in direct mode, the server's outbound proxy cannot proxy audio on behalf of the client.

Configure the Codex client §

Prefer the generated configuration on the GPT-Load home page: select an AccessKey and Codex, then copy it. The complete example below uses a gateway address reachable from the client; replace YOUR_TEXT_MODEL with an enabled text model.

model = "YOUR_TEXT_MODEL"
model_provider = "gpt-load"

experimental_realtime_webrtc_call_base_url = "http://127.0.0.1:3001/v1"
experimental_realtime_ws_base_url = "http://127.0.0.1:3001/v1"

[model_providers.gpt-load]
name = "OpenAI"
base_url = "http://127.0.0.1:3001/v1"
model_catalog_url = "http://127.0.0.1:3001/v1/models"
env_key = "GPT_LOAD_API_KEY"
wire_api = "responses"
supports_websockets = true

[features]
api_key_model_discovery = true
realtime_conversation = true

export GPT_LOAD_API_KEY="YOUR_ACCESS_KEY"
codex

When merging with existing configuration, do not duplicate TOML sections. Both experimental_realtime_* settings are top-level keys and must precede any [section]. Use HTTPS for remote deployments, and ensure the client process inherits GPT_LOAD_API_KEY.

These voice settings are experimental; use the configuration generated by the current console. Restart the client after saving, then start a session from its voice controls. supports_websockets controls text Responses WebSocket, not voice. Voice also requires the separate realtime connection settings and realtime_conversation.

Official Codex configuration reference →

Deploy the gateway relay §

This section is only required for Gateway relay. All relay groups share the server media address and UDP range; you do not need separate ports for each group.

1. Download docker-compose.voice.yml from the version you are running and place it alongside the main docker-compose.yml.
2. Set a server media IP in .env that clients can reach. Do not use a domain name, a container-internal address, or an example IP.

CODEX_LIVE_PUBLIC_IP=YOUR_PUBLIC_IP
CODEX_LIVE_UDP_PORT_MIN=50000
CODEX_LIVE_UDP_PORT_MAX=50127

View the voice Compose file (select your deployed version before downloading) →

3. Allow the same UDP range in cloud security groups, the host firewall, and NAT mappings, then start with both Compose files.

docker compose -f docker-compose.yml -f docker-compose.voice.yml up -d

4. Select Gateway relay in system or Codex group settings, save, and start a new voice session. Keep using both Compose files for future container updates.

Native processes use the same environment variables and need the same UDP ports open. Restart after changing media environment variables. For complex NAT setups, configure STUN/TURN with CODEX_LIVE_ICE_SERVERS; see the environment-variable reference for the format.

The HTTP reverse proxy handles session setup and control connections and must forward WebSocket Upgrade. It does not automatically proxy media UDP. Add the following inside an existing Nginx proxy location while retaining your TLS and access controls.

proxy_pass http://127.0.0.1:3001;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_buffering off;
proxy_read_timeout 3600s;

Voice environment variables →

Sessions and cost §

Session creation uses global weighted scheduling and the retry budget. Explicit 403/429 rejections may switch candidates; a 401 may refresh credentials and retry. Ambiguous timeouts or disconnections after a successful connection do not automatically rebuild the call on another account. Failed voice admission does not blacklist the account for text.

Once established, a session stays on its selected account and media path. The client must attach the control WebSocket: a direct session is cleaned up if none attaches within 30 seconds, or if control does not reconnect within 30 seconds after a disconnect. Rotating or disabling the AccessKey, or revoking permissions, also ends affected calls.

One log entry is recorded when each call ends. Audio cost is currently unpriced and is not charged against the AccessKey's cost allowance, although existing cost limits still affect admission to new calls. Unpriced does not mean upstream usage is free.

If upstream hangup fails, the gateway returns 502. The session stays pending termination and occupies a concurrency slot while the server retries hangup; control cannot be reattached during this period. An incomplete log status does not confirm that upstream has stopped.

Verify and troubleshoot §

First verify text requests, then make a short voice call and check audio in both directions. Hang up and inspect the request log. A readable model list or successful session-creation response alone does not prove that media is connected.