Integration Guide: Connecting Codex CLI to Pomex

This guide explains how to configure OpenAI Codex CLI (v0.128.0+) to use the Pomex API gateway as its backend. Pomex implements the OpenAI Responses API (/v1/responses) with full streaming support, making it compatible with Codex's latest architecture.

What is Codex CLI?

Codex CLI is OpenAI's open-source coding agent that runs in your terminal. It uses the /v1/responses endpoint with streaming SSE to power an interactive coding assistant that can read, write, and execute code in your project.

By pointing Codex at Pomex, you can use supported GPT models as the backend while benefiting from Pomex's unified billing, prompt caching, and multi-provider failover.

Prerequisites

1. A Pomex Account: You need an active account with a valid API key.
2. Your API Key: Locate your unique API key in the Pomex dashboard.
3. Codex CLI Installed: Install via npm:

   npm install -g @openai/codex

API Compatibility

Codex CLI v0.128.0+ exclusively uses the Responses API (/v1/responses) with streaming SSE. The legacy /v1/chat/completions endpoint is no longer used by Codex.

Configuration: config.toml (Required)

Since v0.128.0, Codex CLI uses a TOML configuration file for provider management. Simple environment variables like OPENAI_BASE_URL are no longer sufficient — Codex will ignore them and attempt to connect to the official OpenAI WebSocket endpoint instead.

Step 1: Create the Config File

mkdir -p ~/.codex && nano ~/.codex/config.toml

Step 2: Add Pomex as a Provider

# ~/.codex/config.toml

model_provider = "pomex"
model = "openai/gpt-5.3-codex"

# Define Pomex as a custom model provider
[model_providers.pomex]
name = "Pomex API"
base_url = "https://api.pomex.ai/v1"
env_key = "POMEX_API_KEY"   # Name of the env var holding your API key
wire_api = "responses"          # Use the Responses API protocol (required)

Step 3: Set the API Key Environment Variable

# Add to your ~/.zshrc or ~/.bashrc
export POMEX_API_KEY="sk-rh-xxxxxxxxxxxx"

Step 4: Launch Codex

source ~/.zshrc   # reload env
codex

Configuration Reference

Top-level fields

[model_providers.<name>]

Selecting a Model

Override the default model per session:

# Use a specific model for this session
codex --model openai/gpt-5.3-codex

Recommended Models for Codex

How It Works

Under the hood, the integration works as follows:

1. Codex reads ~/.codex/config.toml and resolves the provider's base_url and API key.
2. Because wire_api = "responses", Codex sends POST /v1/responses with "stream": true over HTTPS (not WebSocket).
3. Pomex converts the request to the appropriate provider format internally (Claude, Gemini, GPT, etc.).
4. The response is streamed back as typed SSE events (response.created, response.output_text.delta, response.completed).
5. Codex receives the stream and renders output in your terminal in real time.

Verifying the Configuration

After setting up, verify the integration works:

# Quick test — should produce a response from Pomex
codex "What is 2 + 2?"

If successful, you'll see the model respond in your terminal. You can also verify in your Pomex dashboard that usage is being logged under the /v1/responses endpoint.

Troubleshooting

Codex Still Connects to wss://api.openai.com

This means the config.toml is not being read. Check:

• File is at ~/.codex/config.toml (not config.json).
• wire_api = "responses" is present in the [model_providers.pomex] section.
• Top-level model_provider = "pomex" matches your [model_providers.pomex] section name.

Error: "stream disconnected before completion"

The SSE stream closed without sending a response.completed event. Ensure you are using Pomex v00083+ which includes the terminal event fallback.

Error: "Invalid API Key" or 401 Unauthorized

Verify:

• The env var name in env_key matches what you exported (e.g. POMEX_API_KEY).
• The actual key value is correct and active.
• Run echo $POMEX_API_KEY to confirm it's set in your current shell.

Error: "model not found" or 400 Bad Request

Ensure the model name follows Pomex's naming convention: provider/model-name (e.g. openai/gpt-5.3-codex). Check the Models page for the full list.

Why OPENAI_BASE_URL No Longer Works

In Codex v0.128.0+, the priority order is:

1. ~/.codex/config.toml — highest priority, controls provider routing and protocol.
2. Legacy OPENAI_BASE_URL — ignored when config.toml is present or when Codex defaults to WebSocket mode.

The config.toml approach is required because Codex needs to know both the base URL and the wire protocol (wire_api). A simple URL environment variable cannot express both.