Run Codex CLI Through an OpenAI-Compatible Relay

Codex relay setup starts with protocol compatibility

Running Codex CLI through a relay requires more than replacing an API hostname. The client needs a compatible protocol, a provider definition, credentials, and an exact model identifier. Current Codex configuration supports the Responses API through wire_api = "responses"; a relay offering only Chat Completions is not sufficient.

This walkthrough uses BestRelay, the publisher of this article. BestRelay is a quality-first API relay that forwards each request to the official model named in it, without substitution. Its coverage includes Claude, GPT, Gemini, DeepSeek, Kimi, GLM, Qwen, Grok, and more. That catalog breadth does not mean every model exposes every feature Codex needs.

Step one installs Codex before changing providers

With npm available, run npm install -g @openai/codex@latest, then codex --version. Record the version so future troubleshooting starts from a known client build. These are the installation and version-check commands documented by OpenAI.

Use a disposable repository for the initial test. Back up any existing Codex configuration before editing it, and avoid changing unrelated sandbox or approval settings. Treat relay connectivity and permission policy as separate setup decisions.

Step two prepares credentials and confirms endpoint details

Create a BestRelay account to follow along. Obtain an API key and copy the exact API model identifier from the service's configuration information rather than deriving one from a display name.

The supplied API base is https://api.bestapirelay.com . Before continuing, confirm the Responses endpoint path, whether the base requires a version prefix, and whether your chosen model supports streaming and tool calls through that endpoint. Do not assume SDK compatibility alone proves complete coding-agent compatibility.

For a Bash session, read the key without placing its literal value in your command history: read -r -s -p "BestRelay API key: " BESTRELAY_API_KEY; export BESTRELAY_API_KEY; printf '\n'. Keep credentials out of repositories, screenshots, and diagnostic reports.

Step three defines BestRelay as the Codex provider

Edit ~/.codex/config.toml. Define a custom provider named bestrelay and select it with model_provider. Codex supports custom provider definitions containing a base URL and an environment-variable key reference.

Place these two assignments at the top level, before any table header, replacing the model placeholder:

Then add the following table, keeping each displayed entry on its own line. Use the base below only if the endpoint check confirms that no additional prefix is required.

The env_key value names the environment variable; it is not the secret itself. Leave requires_openai_auth unset for this environment-key configuration rather than enabling OpenAI authentication.

Step four validates routing with a small request

From the test repository, launch codex in the same shell that holds the key. Codex's interactive terminal interface is started with this command. Ask: Reply with READY. Do not inspect files or run commands.

Check the relay's request record for the requested model, response status, and usage. Do not use the assistant's self-reported model identity as routing evidence. Next, request one small repository inspection and a proposed change before authorizing edits. This separates basic text delivery from tool execution.

Step five diagnoses failures before expanding usage

• Authentication failure: Check that the launching process receives BESTRELAY_API_KEY and that the credential remains valid.
• Missing endpoint: Recheck the documented Responses path and version prefix instead of repeatedly changing the model.
• Rejected model or parameter: Compare the exact identifier and requested capabilities with the relay's supported configuration.
• Interrupted tool workflow: Preserve a redacted error report and test streaming and tool handling separately.

BestRelay also works with Claude Code, Gemini CLI, and any OpenAI SDK, alongside Codex. Billing is pay-as-you-go using provider-reported token counts, with cache reads and writes priced separately. Review those categories when comparing repeated tasks. Members also earn referral commissions when invited users top up; keep that separate from technical suitability and workload cost.