Codex CLI

Codex CLI should talk to Codex Pooler through the Codex backend compatibility route. Use /backend-api/codex, not the OpenAI-compatible /v1 SDK surface.

For a deployed instance, the Codex backend base URL is:

https://pooler.example.com/backend-api/codex

For local setup and local smoke checks, use:

http://localhost:4000/backend-api/codex

Keep your Pool API key in an environment variable. Don’t paste raw keys into ~/.codex/config.toml.

Websocket provider

Use the websocket-capable provider for normal Codex backend behavior. Keep name = "OpenAI" because Codex uses that provider family for its backend Responses protocol.

model = "gpt-5.5"
model_provider = "codex-pooler-ws"

[model_providers.codex-pooler-ws]
name = "OpenAI"
base_url = "https://pooler.example.com/backend-api/codex"
env_key = "CODEX_POOLER_API_KEY"
wire_api = "responses"
supports_websockets = true
requires_openai_auth = true

With a local Codex Pooler instance, change base_url to http://localhost:4000/backend-api/codex.

HTTP/SSE provider

Keep an HTTP/SSE provider when you need to force non-websocket behavior for a client check or when your runtime can’t open backend websocket streams.

[model_providers.codex-pooler-http]
name = "OpenAI"
base_url = "https://pooler.example.com/backend-api/codex"
env_key = "CODEX_POOLER_API_KEY"
wire_api = "responses"
supports_websockets = false
requires_openai_auth = true

Both providers use the same Pool API key and the same Codex backend compatibility route. Codex Pooler routes each request through Pool policy, account eligibility, limits, session continuity, and request accounting.

Operator MCP endpoint

Codex Pooler also exposes an operator MCP endpoint at /mcp. MCP uses an operator-owned MCP token, not a Pool API key.

[mcp_servers.codex_pooler]
url = "https://pooler.example.com/mcp"
bearer_token_env_var = "CODEX_POOLER_MCP_KEY"

Set the token separately:

export CODEX_POOLER_MCP_KEY="<operator-mcp-token>"

Use http://localhost:4000/mcp only for local setup.

Route boundaries

/backend-api/codex/* is an authenticated Codex backend compatibility surface. It is not a wildcard proxy and it is not the OpenAI-compatible /v1 SDK surface.

The backend route family includes GET /backend-api/codex/models, POST /backend-api/codex/responses, backend websocket response-stream compatibility on GET /backend-api/codex/responses, and POST /backend-api/codex/responses/compact.

POST /backend-api/codex/realtime/calls is a Codex backend control-plane SDP proxy route. It is not OpenAI Realtime SDK compatibility.