GetCheapAI

Using an API Relay in Codex

Configure a custom model provider in ~/.codex/config.toml.

2 min read

Codex CLI reads ~/.codex/config.toml at startup. By defining a custom model provider, you can point Codex at an API relay that is compatible with the OpenAI API.

What You'll Need

Get the following information from the API platform you use:

  • API base URL: the root endpoint address the platform gives you, usually ending in /v1
  • API key: the token used for authentication
  • Model name: the model identifier the platform supports and that you plan to use

Configuring config.toml

Edit ~/.codex/config.toml, add a custom provider, and set it as the default:

model = "your-model-name"        # Replace with a model name the platform supports
model_provider = "thirdparty"    # Custom provider ID, pick your own (avoid openai/ollama/lmstudio)

[model_providers.thirdparty]
name = "Third-party API"
base_url = "https://example.com/v1"   # Replace with the API base URL the platform provides
env_key = "THIRDPARTY_API_KEY"        # Name of the environment variable holding your API key
wire_api = "chat"                      # Third-party compatible endpoints usually use chat

env_key specifies the name of the environment variable that holds your API key, not the key itself. Export that variable in your terminal:

export THIRDPARTY_API_KEY="your-key"

Common Issues

  • API key validation fails: if the platform's API key prefix differs from OpenAI's and the key is rejected as a result, you can add requires_openai_auth = false under that provider's configuration.
  • Choosing the protocol: third-party compatible endpoints generally use wire_api = "chat" (which maps to /chat/completions).
  • Do not put your API key in config.toml: use env_key to point to an environment variable, so the key does not leak along with the config file.
  • Temporary override: if you only want to change the base URL temporarily, set the OPENAI_BASE_URL environment variable to override it for the current session.

Learn More