DEV Community

Cover image for How to set up OpenAI Codex with LiteLLM
Misbah Syed
Misbah Syed

Posted on Originally published at misbahsy.hashnode.dev on

How to set up OpenAI Codex with LiteLLM

#litellm #codex #openai

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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

OPENAI_API_KEY=...
ANTHROPIC_API_KEY=...
LITELLM_MASTER_KEY=sk-1234
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

And that it is serving the model list:

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

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

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

codex --profile deep
Enter fullscreen mode Exit fullscreen mode

Additional resources

Top comments (0)