Integration Guide: Connecting Codex CLI to RouterHub

This guide explains how to configure OpenAI Codex CLI (v0.128.0+) to use the RouterHub API gateway as its backend. RouterHub 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 RouterHub, you can use supported GPT models as the backend while benefiting from RouterHub's unified billing, prompt caching, and multi-provider failover.

Prerequisites

1. A RouterHub Account: You need an active account with a valid API key.
2. Your API Key: Locate your unique API key in the RouterHub 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 RouterHub as a Provider

# ~/.codex/config.toml

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

# Define RouterHub as a custom model provider
[model_providers.routerhub]
name = "RouterHub API"
base_url = "https://api.routerhub.ai/v1"
env_key = "ROUTERHUB_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 ROUTERHUB_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. RouterHub 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 RouterHub
codex "What is 2 + 2?"

If successful, you'll see the model respond in your terminal. You can also verify in your RouterHub 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.routerhub] section.
• Top-level model_provider = "routerhub" matches your [model_providers.routerhub] section name.

Error: "stream disconnected before completion"

The SSE stream closed without sending a response.completed event. Ensure you are using RouterHub 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. ROUTERHUB_API_KEY).
• The actual key value is correct and active.
• Run echo $ROUTERHUB_API_KEY to confirm it's set in your current shell.

Error: "model not found" or 400 Bad Request

Ensure the model name follows RouterHub'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.