# How to Configure Headroom for OpenAI API: Complete Setup Guide

> Configure Headroom for OpenAI API with this complete setup guide. Learn to instantiate HeadroomClient, set your API key, and choose audit or optimize mode for caching and compression.

- Repository: [Tejas Chopra/headroom](https://github.com/chopratejas/headroom)
- Tags: how-to-guide
- Published: 2026-06-15

---

**To configure Headroom for OpenAI API, instantiate a `HeadroomClient` with an `OpenAI()` client and `OpenAIProvider()`, set the `OPENAI_API_KEY` environment variable, and select between `audit` (observe) or `optimize` (transform) mode to enable intelligent caching and compression.**

Headroom wraps the OpenAI SDK to add compression, intelligent context management, and provider-specific optimizations. Configuring this integration requires setting up credentials, instantiating the correct provider classes from [`headroom/providers/openai.py`](https://github.com/chopratejas/headroom/blob/main/headroom/providers/openai.py), and optionally tuning model-specific limits. This guide covers the exact configuration steps using the `chopratejas/headroom` source code.

## Prerequisites: OpenAI API Key Authentication

Headroom never stores API keys in the repository. Instead, it relies on the underlying `openai` library to read credentials from the environment. Export your key before initializing any client.

```bash
export OPENAI_API_KEY=sk-...

```

The SDK and proxy will automatically detect this variable when making requests to OpenAI's endpoints.

## Configure Headroom SDK for OpenAI (Python)

### Instantiate HeadroomClient with OpenAIProvider

Create an OpenAI-enabled client by passing an `OpenAI()` instance as the `original_client` and an `OpenAIProvider()` to unlock provider-specific features. According to the implementation in [`headroom/providers/openai.py`](https://github.com/chopratejas/headroom/blob/main/headroom/providers/openai.py), the provider handles token counting, model limit resolution, and OpenAI-specific flags like prefix caching.

```python
from headroom import HeadroomClient, OpenAIProvider
from openai import OpenAI

client = HeadroomClient(
    original_client=OpenAI(),
    provider=OpenAIProvider(),
    default_mode="optimize"  # Use "audit" to observe without transforms

)

# Make a request with automatic compression and caching

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Explain quantum tunneling in simple terms."}]
)
print(response.choices[0].message.content)

```

### Enable OpenAI Prefix Caching

Set `enable_cache_optimizer=True` when constructing `OpenAIProvider` to leverage OpenAI's prefix caching feature. This optimization reuses system prompts across calls, significantly reducing token costs for repetitive contexts.

```python
provider = OpenAIProvider(enable_cache_optimizer=True)

```

### Customize Model Context Limits

Headroom respects OpenAI's default limits (e.g., `gpt-4o: 128000` tokens), but you can override these via three methods. The resolution order is documented in lines 80-90 of [`headroom/providers/openai.py`](https://github.com/chopratejas/headroom/blob/main/headroom/providers/openai.py):

1. Pass a `context_limits` dictionary to the `OpenAIProvider` constructor
2. Set the `HEADROOM_MODEL_LIMITS` environment variable (JSON string or path to a file)
3. Add entries to `~/.headroom/models.json`

```python

# Override via constructor

provider = OpenAIProvider(
    context_limits={"gpt-4o-mini": 128000, "custom-model": 32000}
)

```

## Configure Headroom Proxy for OpenAI

If running the Headroom proxy instead of embedding the SDK, pass `--provider openai` (or rely on the default) and optionally specify a custom endpoint with `--openai-api-url`.

```bash
headroom proxy \
  --port 8787 \
  --host 0.0.0.0 \
  --provider openai \
  --openai-api-url https://api.openai.com

```

The proxy intercepts requests, applies transforms based on your configured mode, and forwards them to OpenAI's API.

## TypeScript SDK Configuration

The TypeScript client connects through the Headroom proxy or directly by reading environment variables. Set `HEADROOM_BASE_URL` and `HEADROOM_API_KEY` before importing the client.

```typescript
process.env.HEADROOM_BASE_URL = "http://localhost:8787";
process.env.HEADROOM_API_KEY = "your-headroom-key";

import { HeadroomClient } from "headroom-ai";

const client = new HeadroomClient();

await client.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content": "What is the speed of light?" }]
});

```

## Summary

- **Authentication**: Set `OPENAI_API_KEY` as an environment variable; Headroom never stores keys in source files.
- **Python SDK**: Combine `HeadroomClient` with `OpenAIProvider` from [`headroom/providers/openai.py`](https://github.com/chopratejas/headroom/blob/main/headroom/providers/openai.py) to enable provider-specific transforms.
- **Optimization**: Enable `enable_cache_optimizer` for OpenAI prefix caching and override model limits via the constructor, `HEADROOM_MODEL_LIMITS` environment variable, or `~/.headroom/models.json`.
- **Proxy Mode**: Use CLI flags `--provider openai` and `--openai-api-url` to route traffic through Headroom's HTTP proxy.
- **Operation Modes**: Choose `audit` to observe token usage without changes, or `optimize` (default) to apply compression and intelligent caching.

## Frequently Asked Questions

### How does Headroom handle OpenAI API credentials?

Headroom delegates credential management to the official `openai` library. Set the `OPENAI_API_KEY` environment variable before runtime. The key is read dynamically and never committed to the repository or stored in Headroom's configuration objects.

### What is the difference between `audit` and `optimize` mode?

`audit` mode logs requests and analyzes token usage without modifying traffic, useful for evaluating costs before enabling transforms. `optimize` mode activates Headroom's full feature set including request compression, context window management, and prefix caching to minimize API spend.

### Where are model context limits resolved in the source code?

Model limit resolution logic resides in [`headroom/providers/openai.py`](https://github.com/chopratejas/headroom/blob/main/headroom/providers/openai.py) between lines 80-90. The provider checks for overrides in this priority order: constructor `context_limits` parameter, `HEADROOM_MODEL_LIMITS` environment variable, and `~/.headroom/models.json`, falling back to built-in defaults for known OpenAI models.

### Can I use a custom OpenAI API endpoint or reverse proxy?

Yes. When running the Headroom proxy, pass `--openai-api-url https://your-endpoint.com` to override the default `https://api.openai.com` base URL. For the Python SDK, instantiate the underlying `OpenAI` client with a custom `base_url` before passing it to `HeadroomClient`.