# Codex with OpenCheese

> Run OpenAI Codex CLI, Codex Desktop and the Codex IDE extension on OpenCheese: a config.toml model provider on the Responses API, API key, effort and fixes.
>
> Web page: https://opencheese.dev/en/docs/codex/ · Every docs page: https://opencheese.dev/llms.txt

Codex speaks the OpenAI Responses API, which OpenCheese serves at
`https://api.opencheese.dev/v1`. Codex 0.120 or newer is required: older builds use a chat
wire protocol that OpenAI has removed, and their configuration will not load.

The Codex CLI, the Codex desktop app and the Codex IDE extension (VS Code, Cursor and other VS
Code forks) read the same `~/.codex/config.toml`, so one setup serves all three.

## The fastest way: the generated file

Sign in, open **Configuration**, choose the **Codex** tab, pick an API key and confirm your
password, then merge the generated file into your user configuration:

| System | File |
| --- | --- |
| macOS and Linux | `~/.codex/config.toml` |
| Windows | `%USERPROFILE%\.codex\config.toml` |
| Codex inside WSL | `~/.codex/config.toml` in your WSL home directory |

## Manual setup

```toml
model = "MODEL_ID"
model_provider = "opencheese"
model_reasoning_summary = "auto"

[model_providers.opencheese]
name = "OpenCheese"
base_url = "https://api.opencheese.dev/v1"
wire_api = "responses"
env_key = "OPENCHEESE_API_KEY"
request_max_retries = 4
stream_max_retries = 5
stream_idle_timeout_ms = 300000
```

Then export the key in the shell that starts Codex, in single quotes (the key contains `$`
characters that double quotes would expand):

```bash
export OPENCHEESE_API_KEY='YOUR_OPENCHEESE_API_KEY'
```

- `base_url` must end in `/v1`: Codex appends `/responses` itself.
- `wire_api` must be `"responses"`; current Codex refuses `"chat"`.
- Every root key (`model`, `model_provider`, ...) must come before the first `[table]`
  header, or the file will not parse.
- The generated file stores the key as `experimental_bearer_token`. `env_key` keeps it out of
  the file instead. Use one or the other, never both: Codex rejects the combination.
- Keep this in your user configuration. Codex ignores `model_provider` in a project-local
  `.codex/config.toml` and prints a startup warning.

## Models and reasoning effort

`/model` inside Codex lists Codex's built-in OpenAI models, not the OpenCheese catalog; a model
from that list works only if your key has a model with the same ID. To use any other model, set
`model` in `config.toml`, or start Codex with one for this session:

```bash
codex -m MODEL_ID
```

`model_reasoning_effort` sets the starting reasoning level (for example `"high"`); the
generated file starts at `max` where the model offers it, otherwise `high` or `medium`. A level
the model does not offer is refused with a message naming the levels it does.
Codex reads `config.toml` only at startup, so restart it after every edit.

Codex's **Fast** mode switches to the model's Fast version where one exists: replies come
sooner and cost more. Where a model has no Fast version, the normal one answers.

## Usage and costs

Every request appears under **Transactions** in the dashboard, grouped as one session per
conversation, with its token usage and cost.

## Troubleshooting

- **The configuration does not load**: update Codex to 0.120 or newer, and check that no root
  key appears after a `[table]` header.
- **"Invalid or disabled OpenCheese API key"**: check the key on the **API keys** page, and that
  `OPENCHEESE_API_KEY` is set in the shell that starts Codex.
- **The website answers instead of the API**: `base_url` must use `api.opencheese.dev`.
- **`/model` does not show my OpenCheese models**: expected; it lists Codex's built-in catalog.
  Set `model` in `config.toml` or use `codex -m MODEL_ID`.