Codex OpenAI-compatible proxy Base URL setup guide

Install the OpenAI Codex CLI and configure API keys, Base URL, config.toml, and provider switching for an OpenAI-compatible proxy.

Install and start

Codex CLI is OpenAI’s local coding agent. The official install flow is:

npm i -g @openai/codex
codex

On first run, Codex asks you to log in with ChatGPT or use an API key. For proxy use, the usual path is an API key plus an OpenAI-compatible endpoint.

Confirm what the provider supports

Codex is not a simple chat shell. It reads code, edits files, and runs commands, so the proxy provider should clearly support the OpenAI Responses API or an OpenAI-compatible interface that works with Codex.

Ask the provider:

  • Whether the Base URL is OpenAI-compatible
  • Whether it supports the Responses API
  • Which model name you should use
  • Whether streaming and tool calls are supported
  • Whether any special headers or query parameters are required

If you have not picked a provider yet, start with the Codex Proxy Service Comparison. To broaden the search to all OpenAI-compatible endpoints, use the OpenAI API Proxy Providers comparison. For price-sensitive setups, also check Cheap OpenAI API Providers, or browse the broader AI API Directory.

Configuration

For a temporary test, start with environment variables:

export OPENAI_API_KEY="your proxy API key"
export OPENAI_BASE_URL="https://your-proxy.example/v1"
codex

For long-term use, consider writing the provider into ~/.codex/config.toml and using separate profiles for official OpenAI, proxy providers, local models, or team gateways.

Debugging order

  1. Confirm codex --version is up to date.
  2. Confirm OPENAI_API_KEY and OPENAI_BASE_URL are active in the current terminal.
  3. Ask the provider to confirm the specific API type Codex needs. Do not only ask whether it “supports OpenAI format.”
  4. If you use config.toml, temporarily return to environment variables to reduce moving parts.

Codex changes quickly, and its configuration options may continue to evolve. Keep a guide’s “minimal verifiable setup” separate from advanced profile configuration, so readers do not copy a complex TOML block and then have no idea where the failure came from.

Codex OpenAI config.toml

Related errors

Claude Code / Codex 503 No available accounts Do not rotate keys first. This error usually points to an unavailable account pool, provider, group, or model route. Test a minimal request, confirm the model and group, then decide whether to wait, reduce context, change model, or switch provider. Codex: Selected model is at capacity. Error: Selected model is at capacity. Please try a different model. Treat it as model-level capacity, admission, or streaming interruption first. It can happen with ChatGPT-authenticated Codex CLI, proxy account pools, or Sub2API upstream overloaded passthrough. Error 401 Unauthorized for AI API proxies A 401 is an authentication failure. Check which key is loaded, which Base URL receives the request, whether the header format is correct, and whether the key is still active for that provider. Error 429 Too Many Requests for AI API proxies Error: exceeded retry limit, last status: 429 Too Many Requests, request id: <request-id>. With an AI API proxy, repeated 429s usually mean the upstream account pool is rate limited, cooling down, or out of usable quota. Ask the provider to switch account, route, or model first.