Codex

Before you start

If your service name or domain is different, replace the sample values below with your actual backend configuration.

Typical Codex setup:

1. Base URL: https://api.example.com/v1
2. API key: sk-your-token
3. Model: a model name exposed by your backend

Install Codex

npm install -g @openai/codex

Verify the CLI:

codex --version

Run with environment variables

macOS / Linux

export OPENAI_API_KEY="sk-your-token"
export OPENAI_BASE_URL="https://api.example.com/v1"
codex

PowerShell

$env:OPENAI_API_KEY="sk-your-token"
$env:OPENAI_BASE_URL="https://api.example.com/v1"
codex

Optional config file

You can also place the provider settings in ~/.codex/config.toml:

model = "your-model-name"
model_provider = "gateway"

[model_providers.gateway]
name = "gateway"
base_url = "https://api.example.com/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"

The model_provider value and section name are only local aliases. You can rename them to match your environment.

Validation

Test the gateway before launching Codex:

curl https://api.example.com/v1/models \
  -H "Authorization: Bearer sk-your-token"

Troubleshooting

Cannot connect

Check whether OPENAI_BASE_URL includes /v1.

Unauthorized

Make sure OPENAI_API_KEY matches a valid token from your backend.

Model not found

The configured model does not match the model list exposed by your gateway.