# Codex

Codex позволяет добавить свой провайдер моделей в `config.toml`, и API моделей больше ничего не нужно: Codex говорит на OpenAI Responses API, а API моделей отвечает на нём по `POST /v1/responses`. Кроме самого Codex ставить ничего не надо. Модель `auto` сама выбирает модель каталога для разговора.

Что нужно: Codex CLI (версию показывает `codex --version`), ключ API моделей и деньги на [балансе организации](https://console.samreshuuu.ru).

## 1. Создайте ключ

В [консоли разработчика](https://console.samreshuuu.ru) откройте «Ключи API», оставьте в поле **Доступ** вариант **Ключ API моделей** и создайте ключ. Секрет показывается один раз. Положите его в профиль оболочки (`~/.zshrc`, `~/.bashrc`), чтобы Codex его прочитал:

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

## 2. Добавьте провайдер

Codex читает `~/.codex/config.toml` или `config.toml` в папке, которую называет `CODEX_HOME`. Добавьте строки ниже. Корневые ключи (`model`, `model_provider`, `model_reasoning_effort`) держите выше любого заголовка `[таблица]` в файле: в TOML ключ после заголовка относится к этой таблице.

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

[model_providers.samreshuuu]
name = "Сам Решу"
base_url = "https://api.samreshuuu.ru/v1"
env_key = "SAMRESHUUU_API_KEY"
wire_api = "responses"
```

| Настройка | Что делает |
| --- | --- |
| `model` | Модель, с которой начинаются сессии: `auto` или id со страницы [«Модели»](/models). |
| `model_provider` | Делает провайдер ниже тем, к которому обращается Codex. |
| `model_reasoning_effort` | Уровень рассуждений, который просит Codex: `minimal`, `low`, `medium`, `high`, `xhigh` или `max`. Для модели, которой Codex не знает, своего уровня он не шлёт. |
| `base_url` | Адрес API моделей. Оставьте `/v1` в конце: Codex сам дописывает `/responses`. |
| `env_key` | Переменная окружения, из которой Codex читает ключ. |
| `wire_api` | `responses`, единственный протокол, на котором говорит Codex. |

Перезапустите сессии Codex. На одну сессию другую модель называет `codex --model <id>`.

## 3. Проверьте подключение

Выполните в папке проекта:

```bash
codex exec "Ответь словом pong"
```

Приходит ответ, а вызов появляется в журнале вызовов [консоли](https://console.samreshuuu.ru) с моделью, которую выбрал `auto`, и его стоимостью. В начале сессии Codex предупреждает, что не знает метаданных `auto`, и берёт свои значения по умолчанию: так и должно быть.

## Как Codex работает через API

- Codex не хранит состояния на сервере: каждый запрос несёт весь разговор с `store: false`, как ждёт [Responses API](/docs/model-api-requests#responses-api-и-codex-cli).
- Модели, которой он не знает, Codex даёт свой инструмент оболочки и свой системный промпт по умолчанию и правит файлы через `apply_patch` в этой оболочке. Вызовы инструментов и их результаты идут элементами Responses.
- Рассуждение модели приходит элементом `reasoning`; Codex возвращает его в следующем запросе, и модель получает его снова, в том числе на другом хосте.
- Codex называет разговор в `prompt_cache_key`, и его вызовы попадают в один [кэш](/docs/model-api-routing#кэш-промпта).
- Codex считает цену треда на своей стороне и `usage.cost` не читает. Что списано с баланса, видно в журнале вызовов консоли.

## Как отменить настройку

Уберите строки `model`, `model_provider` и `model_reasoning_effort` и таблицу `[model_providers.samreshuuu]` из `config.toml`. Codex вернётся к вашему обычному провайдеру.

## Если что-то не так

| Что видно | Что проверить |
| --- | --- |
| `401` или нет переменной окружения | `SAMRESHUUU_API_KEY` не задана в оболочке, из которой запущен Codex, или ключ отозван. |
| Codex отклоняет файл настроек | Корневой ключ вроде `model` стоит ниже заголовка `[таблица]`, или `wire_api` не `responses`. |
| `model_not_found` | Такого id нет в каталоге: возьмите id из `GET /v1/models` или поставьте `auto`. |
| `402` | Баланс не покрывает резерв вызова или исчерпан лимит расхода ключа. |

| HTTP | type | Код | message | Повтор |
| --- | --- | --- | --- | --- |
| 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. | нет |
| 404 | `not_found_error` | `model_not_found` | The model does not exist. GET /v1/models lists the models this API sells. | нет |
| 400 | `invalid_request_error` | `no_auto_model` | No model meets the request for auto. | нет |
| 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. | нет |
| 402 | `billing_error` | `key_limit_exceeded` | This API key has reached its spending limit. Raise the limit or use another key. | нет |

Если ошибка не проходит, напишите в поддержку и приложите `x-request-id` ответа.
