Codex CLI Guide

Codex CLI Custom Provider Setup

Codex CLI supports custom model providers through its config file. Verify `openai_base_url`, `model_providers`, the exact model ID, `wire_api`, token billing and privacy before routing coding requests through a gateway.

Fast setup decision

Use a relay with Codex CLI only if it exposes a real OpenAI-compatible API and documents the base URL, model names, streaming behavior, token billing, failed-request rules and privacy policy. For 302.AI-style providers, separate web-app pricing from raw API pricing before testing.

Compare GPT/Codex providersCheck model familiesReview relay risks

Verify before testing

  • OpenAI-compatible `/v1` API is documented.
  • Model names and coding-model support are public.
  • Input/output token pricing, failed-request billing and refund rules are clear.
  • Privacy policy and log-retention language are visible before testing.

Pre-Setup Checklist

  • Confirm the provider offers an OpenAI-compatible API, not only a web chat product.
  • Check whether it supports the GPT, DeepSeek, Qwen, Gemini or other coding model you need.
  • Verify base URL, model name, API key, streaming output and error format.
  • Confirm whether input and output tokens are billed separately and whether failed requests are charged.
  • Review privacy policy, log retention, refund rules and support channels.

Minimal Environment Test

Use a temporary environment-variable test only to isolate endpoint and authentication problems. Persistent custom providers belong in the current Codex config format, not in copied shell snippets from an unknown version.

OPENAI_API_KEY="your-gateway-api-key"
OPENAI_BASE_URL="https://example.com/v1"
OPENAI_MODEL="provider-model-id"

Built-In OpenAI Provider Shortcut

If you only need to point Codex's built-in OpenAI provider at a proxy or data-residency endpoint, the official advanced config uses `openai_base_url`. Do not define `[model_providers.openai]`, because built-in provider IDs cannot be overridden.

openai_base_url = "https://example.com/v1"

Custom Provider Config Checklist

Public Codex config examples and provider docs commonly use `~/.codex/config.toml` for persistent custom providers. Before copying a TOML block, confirm the provider's required wire API, model ID and key storage pattern.

  • Use a provider-specific `model_provider` id instead of assuming the built-in OpenAI provider will behave like a generic proxy.
  • Check whether the provider expects `wire_api = "responses"` or `wire_api = "chat"`; Codex coding workflows often need Responses-style behavior.
  • Prefer an environment variable such as `EXAMPLE_API_KEY` through `env_key` instead of hardcoding real keys in TOML.
  • If a project-local `.codex/config.toml` is ignored or warns about unsupported `model_provider` keys, move the provider definition to user-level `~/.codex/config.toml` and retest.
  • Keep a minimal environment-variable test separate from a long-term profile setup so debugging does not mix provider, profile and model errors.
  • Keep provider credentials in environment variables or user-level config. Do not let an untrusted project-local config redirect credentials or code traffic to an unknown provider.
model = "provider-model-id"
model_provider = "example_gateway"

[model_providers.example_gateway]
name = "Example Gateway"
base_url = "https://example.com/v1"
env_key = "EXAMPLE_GATEWAY_API_KEY"
wire_api = "responses"

Small-Balance Test Flow

  1. Start with a public sample repository or non-sensitive code snippet.
  2. Test code explanation, cross-file edits, long context, streaming output and error recovery.
  3. Record latency, success rate, billing, output quality and possible model substitution.
  4. Normalize token cost across providers before deciding on long-term use.

Selection Advice

GPT/Codex workflows care most about OpenAI-compatible behavior, model quality, context length, response speed and predictable billing. Low price is only one dimension and should not replace privacy and stability.

For production systems, customer code, secrets and trade secrets, prefer official APIs, cloud-provider channels or a self-hosted gateway. Relays are better for non-sensitive projects, small tests and model experiments.

FAQ

Does a Codex CLI relay need OpenAI-compatible API support?

Usually yes. Codex CLI and most GPT coding tools are easiest to connect through OpenAI-compatible APIs, so verify base URL, model names, auth and streaming behavior.

Can low-cost GPT/Codex relays be used directly for production projects?

Not directly. First test with a small balance, non-sensitive code and a fixed test suite for stability, billing, model quality and privacy disclosures.

How should I compare Codex API relay prices?

Normalize every provider to cost per 1M input tokens and 1M output tokens, then compare failed-request billing, cache rules, minimum recharge and refunds.

Should I configure a Codex relay with environment variables or config.toml?

Start with the smallest environment-variable test when debugging a new relay. Move to `~/.codex/config.toml` only after the provider confirms the base URL, model ID, wire API, streaming and auth behavior.