How to set up OpenAI Codex with LiteLLM

Misbah Syed — Wed, 09 Sep 2026 17:20:51 +0000

This guide connects OpenAI Codex to a LiteLLM proxy, one you run yourself or one your team already hosts. Codex reads one base URL out of a config file, so pointing it at LiteLLM gives you:

Any model LiteLLM can reach, from the same Codex CLI and desktop app
A log line and a cost for every request, in one place
Per-developer keys with their own budgets and their own model access
One provider key on the server instead of a copy on every machine

The five-minute walkthrough this guide is written from:

The steps below are the ones in the video, so you can move between the two.

Requirements

Docker, for the setting up LiteLLM gateway. Not needed if you are pointing at a gateway already hosted.
Node, for the Codex CLI
One provider key. One is enough to start

Everything below runs on the open-source image, ghcr.io/berriai/litellm:main-stable. The admin UI, virtual keys and spend tracking come from having a database attached, which the compose file does.

Versions used here: litellm 1.99.0, current @openai/codex.

Let's go!

If your team already hosts a LiteLLM gateway, skip steps 2 and 3 below.

1. Install OpenAI Codex

Install the Codex CLI globally:

npm install -g @openai/codex

2. Configure LiteLLM for model routing

Make a directory for the LiteLLM proxy and put config.yaml in it. This file is the model list: the names your clients ask for, and where each one goes.

config.yaml

model_list:
  # `codex -m <id>` works with any of them.
  - model_name: gpt-5.6-terra
    litellm_params:
      model: openai/gpt-5.6-terra
      api_key: os.environ/OPENAI_API_KEY
  - model_name: gpt-5.6-luna
    litellm_params:
      model: openai/gpt-5.6-luna
      api_key: os.environ/OPENAI_API_KEY
  - model_name: gpt-5.6-sol
    litellm_params:
      model: openai/gpt-5.6-sol
      api_key: os.environ/OPENAI_API_KEY

  # Anything from another provider goes in the same list.
  - model_name: claude-sonnet-5
    litellm_params:
      model: anthropic/claude-sonnet-5
      api_key: os.environ/ANTHROPIC_API_KEY

  # Catch-all, so `codex -m <anything>` reaches OpenAI without editing
  # this file. Delete this entry to restrict a fleet to the list above.
  - model_name: "*"
    litellm_params:
      model: openai/*
      api_key: os.environ/OPENAI_API_KEY

litellm_settings:
  drop_params: true

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
  # Coding turns stream for a long time. Do not cut them off.
  request_timeout: 600

You could as many model names to this list from the ones supported by LiteLLM

drop_params: true . Coding agents sometimes send parameters that not every provider accepts, which is dropped by this line.

master_key . This is the key to access the proxy.

3. Start the LiteLLM proxy

We'll start the LiteLLM gateway along with a postgres database, so that we can access the dashboard UI for the gateway..

docker-compose.yml

name: litellm-coding-agents

services:
  litellm:
    image: ghcr.io/berriai/litellm:main-stable
    restart: unless-stopped
    command: ["--config", "/app/config.yaml", "--port", "4000"]
    ports:
      - "4000:4000"
    volumes:
      - ./config.yaml:/app/config.yaml:ro
    env_file:
      - .env
    environment:
      DATABASE_URL: postgresql://litellm:litellm@postgres:5432/litellm
      STORE_MODEL_IN_DB: "True"
    depends_on:
      postgres:
        condition: service_healthy
    healthcheck:
      test: ["CMD-SHELL", "python -c \"import urllib.request,sys; sys.exit(0 if urllib.request.urlopen('http://localhost:4000/health/liveliness').status==200 else 1)\""]
      interval: 10s
      timeout: 5s
      retries: 12
      start_period: 30s

  postgres:
    image: postgres:16-alpine
    restart: unless-stopped
    # Deliberately not published to the host. Nothing outside this
    # network needs it, and 5432 is usually already taken.
    environment:
      POSTGRES_USER: litellm
      POSTGRES_PASSWORD: litellm
      POSTGRES_DB: litellm
    volumes:
      - litellm-pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U litellm -d litellm"]
      interval: 5s
      timeout: 5s
      retries: 20

volumes:
  name: litellm-pgdata

Provider keys go in .env next to the compose file:

OPENAI_API_KEY=...
ANTHROPIC_API_KEY=...
LITELLM_MASTER_KEY=sk-1234

sk-1234 is the placeholder master key used in the LiteLLM docs. Replace it with a real secret key.

Bring it up

Start the proxy and its database:

docker compose up -d

First boot runs the database migrations and takes about eighty seconds. Every boot after that is about fifteen (depending on the machine spec).

Check that it is alive:

curl -s http://localhost:4000/health/liveliness

And that it is serving the model list:

curl -s http://localhost:4000/v1/models -H "Authorization: Bearer sk-1234" | head -c 400

A quick tip: If something else is running on port 4000, you can check using this command before running docker compose. You could either stop that process or run LiteLLM gateway on a different port but will have to adjust rest of the tutorial accordingly.

lsof -nP -iTCP:4000 -sTCP:LISTEN

The proxy is up. Now we will look at the Codex side.

4. Configure Codex to use LiteLLM

~/.codex/config.toml

It's a good idea to back up the existing codex config file first.

cp ~/.codex/config.toml ~/.codex/config.toml.bak 2>/dev/null || true

Then edit the codex config file as below:

model = "gpt-5.6-terra"
model_provider = "litellm"
model_reasoning_effort = "medium"

[model_providers.litellm]
name = "LiteLLM Gateway"
base_url = "http://localhost:4000/v1"
# More on setting up LITELLM_API_KEY towards the end
env_key = "LITELLM_API_KEY"
# Codex talks the Responses API. 
wire_api = "responses"
# A coding turn can stream for long time, hence the setting below
stream_idle_timeout_ms = 7200000
stream_max_retries = 5
request_max_retries = 4
# Codex cli complains if not in a trusted folder
[projects."/path/to/your/project"]
trust_level = "trusted"

model_provider = "litellm" . Has to match the [model_providers.<name>] table below it. Any name works, as long as they both match.

wire_api = "responses" . Codex uses the Responses API, whereas the default for a custom provider is chat completions.

5. Run Codex

codex exec "reply with the word CONNECTED and nothing else"

Codex is now runs against your proxy, on your provider key, with your model.

Or you can start a codex session in the terminal with:

codex

Open http://localhost:4000/ui, sign in with the master key, and the request appears in the Logs tab.

6. Use the Codex desktop app

The Codex desktop app reads the same ~/.codex/config.toml. Nothing new to write.

But it will not see your environment variable. macOS hands apps launched from Finder or the Dock the GUI login session's environment, not your shell's. You can run this command to set env variable for the login session:

launchctl setenv LITELLM_API_KEY "sk-1234"

Then fully quit and reopen the codex app. That holds until you log out. Make it a LaunchAgent if you want it permanent.

Advanced options

Manage usage with virtual keys

Clients get a virtual key, issued from the Virtual Keys page in the admin UI at http://localhost:4000/ui, with its own budget and its own list of allowed models.

Issue one per person, per machine or per project, then set LITELLM_API_KEY to that key instead:

export LITELLM_API_KEY=""

Three things follow from that. Spend in the Logs tab is broken down by key, so you can see which project is costing what. A budget on the key stops it rather than surprising you at the end of the month. And if a key leaks, you can revoke that one key.

Using different models

Any public name in the model list works:

codex -m gpt-5.6-luna

Profiles are saved model and reasoning-effort pairs, that can get you started with quickly.

In your ~/.codex/config.toml add:

# Optional profiles 
# Saved model plus reasoning-effort pairs. `codex --profile deep`.
[profiles.fast]
model = "gpt-5.6-luna"
model_reasoning_effort = "low"

[profiles.deep]
model = "gpt-5.6-sol"
model_reasoning_effort = "high"

Now you can run a codex session with a specific profile.

codex --profile deep

Additional resources

LiteLLM docs: https://docs.litellm.ai
Codex tutorial page: https://docs.litellm.ai/docs/tutorials/openai_codex
LiteLLM on GitHub: https://github.com/BerriAI/litellm
Video walkthrough: Watch it on YouTube

DEV Community: Misbah Syed