# Codex

Codex lets you add a model provider of its own in `config.toml`, and that is all the Model API needs: Codex speaks the OpenAI Responses API, and the Model API answers it at `POST /v1/responses`. Nothing to install besides Codex itself. The model is `auto`, which picks a model of the catalogue for the conversation.

Requirements: Codex CLI (`codex --version` shows the version), a Model API key and money on the [organization balance](https://console.samreshuuu.ru).

## 1. Create a key

In the [developer console](https://console.samreshuuu.ru), open API keys, keep **Model API key** in the **Access** field and create the key. The secret is shown once. Put it into your shell profile (`~/.zshrc`, `~/.bashrc`) so Codex can read it:

```bash
export SAMRESHUUU_API_KEY="sk-org-your_api_key"
```

## 2. Add the provider

Codex reads `~/.codex/config.toml`, or `config.toml` in the folder named by `CODEX_HOME`. Add the lines below. Keep the root keys (`model`, `model_provider`, `model_reasoning_effort`) above any `[table]` header of the file: in TOML a key after a header belongs to that table.

```toml
model = "auto"
model_provider = "samreshuuu"
model_reasoning_effort = "high"

[model_providers.samreshuuu]
name = "Samreshuuu"
base_url = "https://api.samreshuuu.ru/v1"
env_key = "SAMRESHUUU_API_KEY"
wire_api = "responses"
```

| Setting | What it does |
| --- | --- |
| `model` | The model sessions start on: `auto` or an id from the [Models](/models) page. |
| `model_provider` | Makes the provider below the one Codex calls. |
| `model_reasoning_effort` | The reasoning level Codex asks for: `minimal`, `low`, `medium`, `high`, `xhigh` or `max`. Codex sends none of its own for a model it does not know. |
| `base_url` | The Model API's address. Keep `/v1` at the end: Codex appends `/responses` itself. |
| `env_key` | The environment variable Codex reads the key from. |
| `wire_api` | `responses`, the only protocol Codex speaks. |

Restart your Codex sessions. For one session, `codex --model <id>` names another model.

## 3. Check the connection

Run in a project folder:

```bash
codex exec "Reply with pong"
```

The answer comes back, and the call shows up in the call log of the [console](https://console.samreshuuu.ru) with the model `auto` picked and its cost. At the start of a session Codex warns that it has no metadata for `auto` and falls back to its defaults: that is expected.

## How Codex works through the API

- Codex keeps no state on the server: every request carries the whole conversation with `store: false`, as the [Responses API](/docs/model-api-requests#responses-api-and-codex-cli) expects.
- For a model it does not know Codex gives the model its shell tool and its default system prompt, and edits files with `apply_patch` through that shell. Tool calls and their results travel as Responses items.
- The model's reasoning comes back as a `reasoning` item; Codex sends it back in the next request, and the model gets it again, on another host too.
- Codex names the conversation in `prompt_cache_key`, which keeps its calls in one [cache](/docs/model-api-routing#prompt-caching).
- Codex counts the price of a thread on its own side and does not read `usage.cost`. What the balance was charged is in the call log of the console.

## Undo the setup

Remove the `model`, `model_provider` and `model_reasoning_effort` lines and the `[model_providers.samreshuuu]` table from `config.toml`. Codex then goes back to your usual provider.

## Troubleshooting

| What you see | What to check |
| --- | --- |
| `401` or a missing environment variable | `SAMRESHUUU_API_KEY` is not set in the shell that started Codex, or the key was revoked. |
| Codex refuses the config file | A root key such as `model` stands below a `[table]` header, or `wire_api` is not `responses`. |
| `model_not_found` | The model id is not in the catalogue: take one from `GET /v1/models` or use `auto`. |
| `402` | The balance does not cover the call's hold, or the key's spend limit is reached. |

| HTTP | type | Code | message | Retry |
| --- | --- | --- | --- | --- |
| 401 | `authentication_error` | `invalid_api_key` | The API key is unknown, disabled, revoked or expired. Switch a disabled key back on in the developer console; create a new one in place of a revoked or expired key. | no |
| 404 | `not_found_error` | `model_not_found` | The model does not exist. GET /v1/models lists the models this API sells. | no |
| 400 | `invalid_request_error` | `no_auto_model` | No model meets the request for auto. | no |
| 402 | `billing_error` | `insufficient_balance` | The organization balance does not cover this request (max_tokens is held in full until the answer is settled). Top up the balance or lower max_tokens. | no |
| 402 | `billing_error` | `key_limit_exceeded` | This API key has reached its spending limit. Raise the limit or use another key. | no |

If an error persists, write to support with the `x-request-id` of the answer.
