> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAI

OpenClaw использует единый идентификатор провайдера, `openai`, как для прямой аутентификации с помощью API-ключа, так и для
аутентификации по подписке ChatGPT/Codex. `openai/*` — канонический маршрут модели.
Для встроенных обращений агента, когда политика среды выполнения не задана или имеет значение `auto`, параметры маршрута OpenAI
определяют, может ли OpenClaw неявно выбрать встроенную среду выполнения сервера приложений Codex.
Сам по себе префикс `openai/*` не выбирает среду выполнения.

* **Модели агента** — `openai/*` через среду выполнения, выбранную явной
  конфигурацией `agentRuntime` или неявной политикой маршрутизации OpenAI. Для использования
  подписки ChatGPT/Codex войдите с помощью аутентификации Codex либо настройте профиль
  аутентификации с API-ключом, если требуется оплата по ключу.
* **API OpenAI, не относящиеся к агенту** — прямой доступ к OpenAI Platform с оплатой по факту использования
  через `OPENAI_API_KEY` или профиль аутентификации с API-ключом `openai`.
* **Устаревшая конфигурация** — ссылки `codex/*` и `openai-codex/*` исправляются на
  `openai/*` вместе с привязанным к модели `agentRuntime.id: "codex"` с помощью
  `openclaw doctor --fix`.

OpenAI явно поддерживает использование OAuth подписки во внешних инструментах и
рабочих процессах, таких как OpenClaw.

## Отслеживание использования и расходов

OpenClaw раздельно учитывает квоту подписки и оплату API Platform:

* OAuth ChatGPT/Codex показывает план подписки, окна квот и кредитный баланс.
* `OPENAI_ADMIN_KEY` показывает в разделе **Использование** Control UI сообщаемые провайдером расходы организации и использование completions за 30 дней, включая ежедневные расходы, общее количество запросов и токенов, основные модели и категории расходов.
* `OPENAI_PROJECT_ID` при необходимости ограничивает историю Admin API одним проектом.
* OpenClaw никогда не отправляет `OPENAI_API_KEY` или профиль инференса `openai` в API организации; эти учетные данные могут принадлежать пользовательским, Azure- или локальным для агента конечным точкам.

Явный ключ администратора имеет приоритет над OAuth. Сообщаемая провайдером история не объединяется с приблизительными расходами, вычисленными OpenClaw на основе сеансов; она может включать активность API других клиентов и корректировки оплаты на стороне провайдера.

В документации OpenAI по [панели использования API](https://help.openai.com/en/articles/10478918) описаны требования к владельцу организации и явному разрешению Usage Dashboard для доступа к данным об использовании.

Провайдер, модель, среда выполнения и канал — отдельные уровни. Если эти понятия
смешиваются, прочитайте раздел [Среды выполнения агентов](https://docs2.openclaw.ai/ru/concepts/agent-runtimes.md), прежде чем
изменять конфигурацию.

## Быстрый выбор

| Цель | Использовать | Примечания |
| - | - | - |
| Подписка ChatGPT/Codex, нативная среда выполнения Codex | `openai/gpt-5.6-sol` | Первоначальная настройка подписки; войдите с помощью аутентификации Codex. |
| Прямая оплата по API-ключу для обращений агента | `openai/gpt-5.6` вместе с упорядоченным профилем аутентификации с API-ключом | Первоначальная настройка API-ключа; базовый идентификатор прямого API разрешается в Sol. |
| Выбор точного уровня GPT-5.6 | `openai/gpt-5.6-sol`, `-terra` или `-luna` | Проверьте доступные этой учетной записи уровни с помощью `models list`. |
| Учетная запись без доступа к GPT-5.6 | `openai/gpt-5.5` | Явный вариант восстановления; OpenClaw не выполняет незаметный переход на более раннюю версию. |
| Прямая оплата по API-ключу, явная среда выполнения OpenClaw | `openai/gpt-5.6` вместе с провайдером/моделью `agentRuntime.id: "openclaw"` | Выберите обычный профиль API-ключа `openai`. |
| Псевдоним последней модели ChatGPT Instant | `openai/chat-latest` | Только прямой API-ключ; изменяемый псевдоним, а не стабильное значение по умолчанию. |
| Генерация или редактирование изображений | `openai/gpt-image-2` | Работает с `OPENAI_API_KEY` или OAuth Codex. |
| Изображения с прозрачным фоном | `openai/gpt-image-1.5` | Установите `outputFormat` в `png` или `webp`, а также `background=transparent`. |

## Карта названий

| Отображаемое название | Уровень | Значение |
| - | - | - |
| `openai` | Префикс провайдера | Канонический маршрут модели OpenAI; параметры маршрута определяют неявную среду выполнения. |
| Плагин `codex` | Плагин | Встроенный плагин, предоставляющий нативную среду выполнения сервера приложений Codex и элементы управления чатом `/codex`. |
| `agentRuntime.id: codex` провайдера/модели | Среда выполнения агента | Принудительно использовать нативную среду сервера приложений Codex для соответствующих встроенных обращений. |
| `/codex ...` | Набор команд чата | Привязывать потоки сервера приложений Codex к беседе и управлять ими. |
| `runtime: "acp", agentId: "codex"` | Маршрут сеанса ACP | Явный резервный маршрут, запускающий Codex через ACP/acpx. |

## Неявная среда выполнения агента

Когда политика `agentRuntime` провайдера/модели не задана или имеет значение `auto`, принадлежащая OpenAI
политика маршрутизации выбирает неявную среду выполнения на основе фактических
конечной точки и адаптера:

| Фактические параметры маршрута | Неявная среда выполнения |
| - | - |
| Точная официальная конечная точка Platform HTTPS с `openai-responses` или точная официальная конечная точка ChatGPT HTTPS с `openai-chatgpt-responses`; без пользовательского переопределения запроса | Может быть выбран Codex |
| Пользовательский адаптер `openai-completions` | OpenClaw |
| Пользовательская конечная точка | OpenClaw |
| Явно заданная точная официальная конечная точка с использованием HTTP | Отклоняется |
| Маршрут с пользовательским переопределением запроса провайдера/модели | OpenClaw |

Явное нестандартное значение `agentRuntime.id` провайдера/модели сохраняет приоритет.
Например, `agentRuntime.id: "openclaw"` оставляет маршрут, который в ином случае подходил бы для Codex,
на OpenClaw, а `agentRuntime.id: "codex"` требует Codex и завершает работу
с ошибкой, если фактический маршрут не объявлен совместимым с Codex.
Выбор среды выполнения не изменяет тип учетных данных или способ оплаты: аутентификация
с помощью API-ключа Platform и аутентификация по подписке ChatGPT/Codex остаются раздельными.

`openclaw doctor --fix` переносит устаревшие ссылки на модели `codex/*` и `openai-codex/*`,
устаревшие идентификаторы профилей аутентификации Codex и устаревшие записи порядка аутентификации Codex на
канонический маршрут `openai`. Перенесенные ссылки на модели получают привязанный к модели
`agentRuntime.id: "codex"`; для новой конфигурации порядка аутентификации используйте `auth.order.openai`.

> [!NOTE]
>
> При первоначальной настройке OpenAI основная модель GPT-5.6 применяется только в том случае, если основная модель
> не настроена. Добавление или обновление аутентификации OpenAI сохраняет существующий явный
> выбор, включая `openai/gpt-5.5`, если только явно не используется
> `models auth login --set-default` или `models set`. Используйте профиль аутентификации с API-ключом,
> только если для модели агента требуется аутентификация с API-ключом.

## Ограниченная предварительная версия GPT-5.6

OpenClaw распознает точные идентификаторы моделей `openai/gpt-5.6-sol`,
`openai/gpt-5.6-terra` и `openai/gpt-5.6-luna`. В текущем каталоге все три поддерживают
уровни рассуждений `xhigh` и `max`. OpenAI описывает Sol как
флагманский уровень, Terra — как сбалансированный, а Luna — как быстрый
и менее дорогой уровень. См.
[объявление о выпуске GPT-5.6](https://openai.com/index/previewing-gpt-5-6-sol/)
и [руководство по доступу](https://help.openai.com/en/articles/20001325-a-preview-of-gpt-5-6-sol-terra-and-luna).

При прямой аутентификации OpenAI с помощью API-ключа базовый идентификатор `openai/gpt-5.6` является псевдонимом
Sol и используется по умолчанию при первоначальной настройке. Нативный каталог Codex не применяет
этот псевдоним прямого API на стороне клиента; в зависимости от доступа рабочего пространства он может отображать
точные идентификаторы Sol, Terra и Luna. Поэтому при первоначальной настройке OAuth ChatGPT/Codex
используется `openai/gpt-5.6-sol`. Проверьте текущую учетную запись командой:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw models list --provider openai
```

Доступ организации API и рабочего пространства Codex может различаться. Если GPT-5.6
недоступен, явно выберите GPT-5.5:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw models set openai/gpt-5.5
```

OpenClaw показывает ошибку доступа от вышестоящей системы и не заменяет незаметно
выбранную GPT-5.6 на GPT-5.5.

> [!NOTE]
>
> Для подходящих точных официальных маршрутов HTTPS может быть выбран встроенный плагин сервера приложений
> Codex, если политика среды выполнения не задана или имеет значение `auto`; пользовательские маршруты Completions,
> пользовательские конечные точки и переопределения транспорта запросов остаются на OpenClaw. Официальные
> конечные точки с незашифрованным HTTP отклоняются. Явная конфигурация среды выполнения провайдера/модели сохраняет
> приоритет. Запустите `openclaw doctor --fix`, чтобы исправить устаревшие ссылки на модели Codex,
> ссылки `codex-cli/*` или старые закрепления среды выполнения сеанса, которые не были заданы
> явной конфигурацией среды выполнения.

## Поддержка возможностей OpenClaw

| Возможность OpenAI | Поверхность OpenClaw | Статус |
| - | - | - |
| Чат / Responses | провайдер модели `openai/<model>` | Да |
| Модели по подписке Codex | `openai/<model>` с OpenAI OAuth | Да |
| Устаревшие ссылки на модели Codex | старые ссылки на модели Codex, `codex-cli/<model>` | Исправляются командой doctor на `openai/<model>` |
| Среда app-server Codex | совместимый с Codex маршрут HTTPS с неустановленной средой выполнения/`auto` либо явно заданным `agentRuntime.id: codex` | Да |
| Серверный веб-поиск | встроенный инструмент OpenAI Responses | Да, если веб-поиск включён и не закреплён другой провайдер |
| Изображения | `image_generate` | Да |
| Видео | `video_generate` | Да |
| Преобразование текста в речь | `messages.tts.provider: "openai"` / `tts` | Да |
| Пакетное преобразование речи в текст | `tools.media.audio` / распознавание медиаконтента | Да |
| Потоковое преобразование речи в текст | плагин Voice Call `streaming.provider: "openai"` | Да |
| Голосовая связь в реальном времени | плагин Voice Call `realtime.provider: "openai"` / Talk в Control UI `talk.realtime.provider: "openai"` | Да (ключ API OpenAI Platform) |
| Эмбеддинги | провайдер эмбеддингов памяти | Да |

> [!NOTE]
>
> Голосовая связь OpenAI Realtime работает через общедоступный **OpenAI Platform Realtime
> API** и требует ключа API Platform. Токены Codex OAuth вместо этого аутентифицируют
> бэкенд ChatGPT Codex; они не взаимозаменяемы с ключами API Platform
> для общедоступных конечных точек Realtime.
>
> Если при аутентификации с помощью ключа API сообщается об отсутствии средств, пополните баланс Platform на странице
> [platform.openai.com/account/billing](https://platform.openai.com/account/billing)
> для организации, к которой относятся ваши учётные данные Realtime. Голосовая связь Realtime принимает профиль аутентификации по ключу API `openai`, созданный командой
> `openclaw onboard --auth-choice openai-api-key`, ключ API Platform, заданный через
> `talk.realtime.providers.openai.apiKey` для Talk в Control UI, либо
> `plugins.entries.voice-call.config.realtime.providers.openai.apiKey` для Voice
> Call, либо переменную окружения `OPENAI_API_KEY`.

## Эмбеддинги памяти

OpenClaw может использовать OpenAI или совместимую с OpenAI конечную точку эмбеддингов для
индексирования `memory_search` и эмбеддингов запросов:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "openai",
        model: "text-embedding-3-small",
      },
    },
  },
}
```

Для совместимых с OpenAI конечных точек, которым требуются разные метки эмбеддингов, задайте
`queryInputType` и `documentInputType` в `memorySearch`. OpenClaw
передаёт их как специфичные для провайдера поля запроса `input_type`: для эмбеддингов
запросов используется `queryInputType`; для индексируемых фрагментов памяти и пакетного индексирования —
`documentInputType`. Полный пример см. в
[справочнике по конфигурации памяти](https://docs2.openclaw.ai/ru/reference/memory-config.md#provider-specific-config).

## Начало работы

> [tab] Ключ API (OpenAI Platform)
>
> **Лучше всего подходит для:** прямого доступа к API с оплатой по объёму использования.
>
> **1. Получите ключ API**
>
> Создайте или скопируйте ключ API на [панели управления OpenAI Platform](https://platform.openai.com/api-keys).
>
> **2. Запустите первоначальную настройку**
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> openclaw onboard --auth-choice openai-api-key
> ```
>
> Либо передайте ключ напрямую:
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> openclaw onboard --openai-api-key "$OPENAI_API_KEY"
> ```
>
> **3. Убедитесь, что модель доступна**
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> openclaw models list --provider openai
> ```
>
> ### Сводка маршрутов
>
> | Ссылка на модель | Политика среды выполнения или сведения о маршруте | Маршрут | Аутентификация |
> | - | - | - | - |
> | `openai/gpt-5.6` | не задано/`auto`, точный встроенный официальный маршрут HTTPS без переопределения запроса | Может быть выбран Codex | Упорядоченный профиль аутентификации по ключу API |
> | `openai/gpt-5.6` | провайдер/модель `agentRuntime.id: "openclaw"` | Встроенная среда выполнения OpenClaw | Выбранный профиль ключа API `openai` |
> | `openai/gpt-5.5` | явно заданные провайдер/модель `agentRuntime.id` | Выбранная среда выполнения агента | Выбранный профиль ключа API OpenAI |
> | `openai/*` | заданный пользователем маршрут Completions, пользовательский маршрут или переопределение запроса | Встроенная среда выполнения OpenClaw | Тип учётных данных остаётся неизменным |
> | `openai/*` | официальная конечная точка HTTP с открытым текстом | Отклоняется | Учётные данные не отправляются |
>
> > [!NOTE]
> >
> > Если среда выполнения не задана или задана как `auto`, неявно выбрать
> > среду app-server Codex может только подходящий точный встроенный официальный маршрут HTTPS.
> > Для аутентификации агента по ключу API создайте профиль аутентификации по ключу API
> > `openai` и задайте его порядок с помощью
> > `auth.order.openai`; `OPENAI_API_KEY` остаётся прямым резервным вариантом для
> > поверхностей API OpenAI, не связанных с агентами. Выполните `openclaw doctor --fix`, чтобы перенести старые
> > устаревшие записи порядка аутентификации Codex.
>
> ### Пример конфигурации
>
> ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
> {
>   env: { OPENAI_API_KEY: "example-openai-key-not-real" },
>   agents: { defaults: { model: { primary: "openai/gpt-5.6" } } },
> }
> ```
>
> Краткий идентификатор прямого API `gpt-5.6` разрешается в уровень Sol. Если эта
> организация API не предоставляет GPT-5.6, явно задайте основной моделью
> `openai/gpt-5.5`.
>
> Чтобы попробовать текущую модель Instant из ChatGPT через OpenAI API, задайте модель
> `openai/chat-latest`:
>
> ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
> {
>   env: { OPENAI_API_KEY: "example-openai-key-not-real" },
>   agents: { defaults: { model: { primary: "openai/chat-latest" } } },
> }
> ```
>
> `chat-latest` — динамический псевдоним. При новой настройке ключа API OpenAI вместо него используется
> `openai/gpt-5.6`, краткий идентификатор которого для прямого API разрешается в Sol. Существующие
> явно заданные основные модели, включая `openai/gpt-5.5`, остаются без изменений. Псевдоним
> `chat-latest` принимает только уровень детализации текста `medium`; для этой модели OpenClaw принудительно
> заменяет любой другой запрошенный уровень детализации на `medium`.
>
> > [!WARNING]
> >
> > OpenClaw **не** предоставляет `gpt-5.3-codex-spark` через прямой маршрут
> > с ключом API OpenAI. Эта модель доступна только через записи каталога подписки Codex,
> > если она доступна для вашей вошедшей в систему учётной записи.

> [tab] Подписка Codex
>
> **Лучше всего подходит для:** использования подписки ChatGPT/Codex с выполнением во встроенном
> app-server Codex вместо отдельного ключа API. Для Codex Cloud требуется
> вход в ChatGPT.
>
> **1. Запустите Codex OAuth**
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> openclaw onboard --auth-choice openai
> ```
>
> Либо запустите OAuth напрямую:
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> openclaw models auth login --provider openai
> ```
>
> Для систем без графического интерфейса или конфигураций, где обратный вызов затруднён, добавьте `--device-code`, чтобы
> войти через поток кода устройства ChatGPT вместо обратного вызова
> локального браузера:
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> openclaw models auth login --provider openai --device-code
> ```
>
> **2. Используйте канонический маршрут модели OpenAI**
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> openclaw config set agents.defaults.model.primary openai/gpt-5.6-sol
> ```
>
> Для этого точного встроенного официального маршрута HTTPS конфигурация среды выполнения
> не требуется. Он может автоматически выбрать среду app-server Codex, а
> OpenClaw устанавливает или восстанавливает встроенный плагин Codex при выборе этой среды
> выполнения.
>
> **3. Убедитесь, что аутентификация Codex доступна**
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> openclaw models list --provider openai
> ```
>
> После запуска Gateway отправьте `/codex status` или `/codex models`
> в чате, чтобы проверить встроенную среду app-server.
>
> ### Сводка маршрутов
>
> | Ссылка на модель | Политика среды выполнения или сведения о маршруте | Маршрут | Аутентификация |
> | - | - | - | - |
> | `openai/gpt-5.6-sol` | не задано/`auto`, точный встроенный официальный маршрут HTTPS без переопределения запроса | Может быть выбран Codex | Вход в Codex или упорядоченный профиль аутентификации `openai` |
> | `openai/gpt-5.6-terra` | не задано/`auto`, точный встроенный официальный маршрут HTTPS без переопределения запроса | Может быть выбран Codex | Вход в Codex, если каталог предоставляет Terra |
> | `openai/gpt-5.6-luna` | не задано/`auto`, точный встроенный официальный маршрут HTTPS без переопределения запроса | Может быть выбран Codex | Вход в Codex, если каталог предоставляет Luna |
> | `openai/gpt-5.6-sol` | провайдер/модель `agentRuntime.id: "openclaw"` | Встроенная среда выполнения OpenClaw, внутренний транспорт аутентификации Codex | Выбранный профиль OAuth `openai` |
> | `openai/gpt-5.5` | явно заданные провайдер/модель `agentRuntime.id` | Выбранная среда выполнения агента | Выбранный профиль аутентификации OpenAI |
> | `openai/*` | заданный пользователем маршрут Completions, пользовательский маршрут или переопределение запроса | Встроенная среда выполнения OpenClaw | Требование к учётным данным остаётся специфичным для маршрута |
> | `openai/*` | официальная конечная точка HTTP с открытым текстом | Отклоняется | Учётные данные не отправляются |
> | Устаревшая ссылка Codex GPT-5.5 | исправляется командой doctor | Перезаписывается на `openai/gpt-5.5` | Перенесённый профиль OpenAI OAuth |
> | `codex-cli/gpt-5.5` | исправляется командой doctor | Перезаписывается на `openai/gpt-5.5` | Аутентификация app-server Codex |
>
> > [!WARNING]
> >
> > При новой настройке с подпиской используется точная ссылка `openai/gpt-5.6-sol`;
> > нативный каталог Codex также может предоставлять точные ссылки Terra или Luna. Если
> > для учётной записи недоступна GPT-5.6, явно выберите `openai/gpt-5.5`. Более старые
> > ссылки Codex GPT — это устаревшие маршруты OpenClaw, а не путь нативной среды выполнения
> > Codex; выполните `openclaw doctor --fix`, чтобы перенести их без обновления
> > существующего явно выбранного GPT-5.5. `gpt-5.3-codex-spark` остаётся доступной
> > только для учётных записей, в каталоге подписки Codex которых она указана; прямые ссылки
> > на неё с API-ключом OpenAI и через Azure остаются скрытыми.
>
> > [!NOTE]
> >
> > В новой конфигурации порядок аутентификации агента OpenAI следует указывать в `auth.order.openai`;
> > doctor переносит более старые записи порядка аутентификации устаревшего Codex.
>
> ### Пример конфигурации
>
> ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
> {
>   plugins: { entries: { codex: { enabled: true } } },
>   agents: {
>     defaults: {
>       model: { primary: "openai/gpt-5.6-sol" },
>     },
>   },
> }
> ```
>
> При наличии резервного API-ключа оставьте выбранную модель в `openai/*`, а
> порядок аутентификации укажите в `openai`. OpenClaw сначала использует подписку,
> а затем API-ключ, продолжая работать в среде Codex:
>
> ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
> {
>   plugins: { entries: { codex: { enabled: true } } },
>   agents: {
>     defaults: {
>       model: { primary: "openai/gpt-5.6-sol" },
>     },
>   },
>   auth: {
>     order: {
>       openai: [
>         "openai:user@example.com",
>         "openai:api-key-backup",
>       ],
>     },
>   },
> }
> ```
>
> > [!NOTE]
> >
> > Первоначальная настройка больше не импортирует материалы OAuth из `~/.codex`. Войдите
> > через OAuth в браузере (по умолчанию) или с помощью описанного выше потока кода устройства;
> > OpenClaw управляет полученными учётными данными в собственном хранилище аутентификации агента.
>
> ### Проверка и восстановление маршрутизации Codex OAuth
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> openclaw models status
> openclaw models auth list --provider openai
> openclaw config get agents.defaults.model --json
> openclaw config get models.providers.openai.agentRuntime --json
> ```
>
> Для конкретного агента добавьте `--agent <id>`:
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> openclaw models status --agent <id>
> openclaw models auth list --agent <id> --provider openai
> ```
>
> Если в старой конфигурации всё ещё присутствуют устаревшие ссылки Codex GPT или
> закрепление устаревшего сеанса среды выполнения OpenAI без явной конфигурации среды,
> исправьте это:
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> openclaw doctor --fix
> openclaw config validate
> ```
>
> Если `models auth list --provider openai` не показывает пригодного профиля, войдите
> снова:
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> openclaw models auth login --provider openai
> openclaw models status --probe --probe-provider openai
> ```
>
> Используйте `--profile-id` для нескольких входов Codex OAuth в одном агенте, а затем
> управляйте ими с помощью порядка аутентификации или `/model ...@<profileId>`:
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> openclaw models auth login --provider openai --profile-id openai:ritsuko
> openclaw models auth login --provider openai --profile-id openai:lain
> ```
>
> Выполните `openclaw doctor --fix`, чтобы перенести идентификаторы профилей и записи порядка
> со старым префиксом OpenAI Codex, прежде чем полагаться на порядок профилей.
>
> ### Индикатор состояния
>
> Команда чата `/status` показывает, какая среда выполнения модели активна для текущего
> сеанса. Встроенная среда app-server Codex отображается как
> `Runtime: OpenAI Codex`, когда её выбирает подходящий неявный маршрут или явная
> политика среды выполнения поставщика/модели.
>
> ### Предупреждение doctor
>
> Если в конфигурации или состоянии сеанса остаются устаревшие ссылки на модели Codex
> либо закрепления среды выполнения OpenAI, `openclaw doctor --fix` преобразует их в `openai/*`
> со средой выполнения Codex, если только OpenClaw не настроен явно.
>
> ### Ограничение контекстного окна
>
> OpenClaw рассматривает метаданные модели и ограничение контекста среды выполнения как отдельные
> значения. Для `openai/gpt-5.5` через каталог Codex OAuth:
>
> * Нативная `contextWindow`: `400000`
> * Ограничение `contextTokens` среды выполнения по умолчанию: `272000`
>
> На практике меньшее ограничение по умолчанию обеспечивает более выгодные характеристики
> задержки и качества. Переопределите его с помощью `contextTokens`:
>
> ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
> {
>   models: {
>     providers: {
>       openai: {
>         models: [{ id: "gpt-5.5", contextTokens: 160000 }],
>       },
>     },
>   },
> }
> ```
>
> > [!NOTE]
> >
> > Используйте `contextWindow` для объявления нативных метаданных модели. Используйте `contextTokens`,
> > чтобы ограничить бюджет контекста среды выполнения. Прямой маршрут с API-ключом OpenAI
> > сообщает большее нативное значение `contextWindow` (`1000000`) для `gpt-5.5`; эти два
> > маршрута отслеживаются отдельно, поскольку вышестоящие каталоги различаются.
>
> ### Восстановление каталога
>
> OpenClaw использует метаданные вышестоящего каталога Codex для `gpt-5.5`, когда они
> присутствуют. Если при действующей аутентификации учётной записи динамическое обнаружение Codex
> не возвращает строку `gpt-5.5`, OpenClaw синтезирует эту строку модели OAuth, чтобы
> запуски Cron, субагентов и настроенной модели по умолчанию не завершались ошибкой
> `Unknown model`.

## Аутентификация нативного app-server Codex

Нативная среда app-server Codex использует ссылки на модели `openai/*`, когда её неявно
выбирает подходящий точный официальный маршрут HTTPS или когда её явно выбирает
`agentRuntime.id: "codex"` поставщика/модели. Аутентификация по-прежнему
основана на учётной записи. OpenClaw выбирает аутентификацию в следующем порядке:

1. Упорядоченные профили аутентификации OpenAI для агента, предпочтительно в
   `auth.order.openai`. Выполните `openclaw doctor --fix`, чтобы перенести старые идентификаторы
   профилей аутентификации Codex и порядок аутентификации.
2. Существующая учётная запись app-server, например локальный вход ChatGPT
   через Codex CLI. Для изолированного домашнего каталога агента по умолчанию OpenClaw передаёт эту
   нативную учётную запись CLI в app-server через RPC входа; конфигурация,
   плагины и хранилище веток CLI при этом не используются совместно.
3. Только для локальных запусков app-server через stdio и только когда app-server
   сообщает об отсутствии учётной записи: `CODEX_API_KEY`, затем `OPENAI_API_KEY`.

Локальный вход по подписке ChatGPT/Codex не заменяется только потому, что
у процесса Gateway также есть `OPENAI_API_KEY` для прямых моделей OpenAI или
эмбеддингов. Резервный API-ключ из переменной окружения применяется только к локальному
пути stdio без учётной записи; он никогда не отправляется через соединения app-server WebSocket.
Когда выбран профиль Codex с подпиской, OpenClaw также исключает
`CODEX_API_KEY` и `OPENAI_API_KEY` из среды порождённого дочернего процесса app-server stdio
и вместо этого передаёт выбранные учётные данные через RPC входа app-server.

Когда этот профиль подписки блокируется из-за ограничения использования Codex, OpenClaw
помечает профиль заблокированным до указанного Codex времени сброса и позволяет порядку
аутентификации перейти к следующему профилю `openai:*`, не меняя выбранную
модель и не выходя из среды Codex. После наступления времени сброса
профиль подписки снова становится доступен.

## Генерация изображений

Встроенный плагин `openai` регистрирует генерацию изображений через
инструмент `image_generate`. Он поддерживает генерацию изображений как с API-ключом OpenAI,
так и через Codex OAuth, используя одну и ту же ссылку на модель `openai/gpt-image-2`.

| Возможность | API-ключ OpenAI | Codex OAuth |
| - | - | - |
| Ссылка на модель | `openai/gpt-image-2` | `openai/gpt-image-2` |
| Аутентификация | `OPENAI_API_KEY` | Вход OpenAI Codex OAuth |
| Транспорт | API OpenAI Images | Бэкенд Codex Responses |
| Макс. изображений на запрос | 4 | 4 |
| Режим редактирования | Включён (до 5 эталонных изображений) | Включён (до 5 эталонных изображений) |
| Переопределение размера | Поддерживается, включая размеры 2K/4K | Поддерживается, включая размеры 2K/4K |
| Соотношение сторон / разрешение | Не передаётся в API OpenAI Images | По возможности безопасно сопоставляется с поддерживаемым размером |

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  agents: {
    defaults: {
      imageGenerationModel: { primary: "openai/gpt-image-2" },
    },
  },
}
```

> [!NOTE]
>
> Общие параметры инструмента, выбор поставщика и поведение при переключении после сбоя
> описаны в разделе [«Генерация изображений»](https://docs2.openclaw.ai/ru/tools/image-generation.md).

`gpt-image-2` используется по умолчанию для генерации изображений OpenAI по тексту и
редактирования изображений. `gpt-image-1.5`, `gpt-image-1` и `gpt-image-1-mini` по-прежнему можно
использовать как явные переопределения модели. Используйте `openai/gpt-image-1.5` для
вывода PNG/WebP с прозрачным фоном; текущий API `gpt-image-2` отклоняет
`background: "transparent"`.

Для запроса с прозрачным фоном вызовите `image_generate` с
`model: "openai/gpt-image-1.5"`, `outputFormat: "png"` или `"webp"`, а также
`background: "transparent"`; более старый параметр поставщика `openai.background`
по-прежнему принимается. OpenClaw также защищает общедоступные маршруты OpenAI и OpenAI Codex OAuth,
преобразуя прозрачные запросы по умолчанию `openai/gpt-image-2` в
`gpt-image-1.5`; Azure и пользовательские конечные точки, совместимые с OpenAI, сохраняют
настроенные имена развёртываний/моделей.

Та же настройка доступна для безголовых запусков CLI:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw infer image generate \
  --model openai/gpt-image-1.5 \
  --output-format png \
  --background transparent \
  --prompt "Простая наклейка с красным кругом на прозрачном фоне" \
  --json
```

Используйте те же флаги `--output-format` и `--background` с
`openclaw infer image edit`, если исходным материалом служит входной файл.
`--openai-background` остаётся доступным как псевдоним, специфичный для OpenAI. Используйте
`--quality low|medium|high|auto` для управления качеством и стоимостью OpenAI Images.
Используйте `--openai-moderation low|auto`, чтобы передать подсказку модерации OpenAI из
`image generate` или `image edit`.

Для установок с ChatGPT/Codex OAuth используйте ту же ссылку `openai/gpt-image-2`. Когда
настроен профиль OAuth `openai`, OpenClaw получает сохранённый токен доступа OAuth
и отправляет запросы изображений через бэкенд Codex Responses; он
не пытается сначала использовать `OPENAI_API_KEY` и не переключается незаметно на API-ключ.
Явно настройте `models.providers.openai` с API-ключом, пользовательским базовым
URL или конечной точкой Azure, если вместо этого требуется прямой маршрут API OpenAI Images.
Если эта пользовательская конечная точка изображений находится по доверенному адресу LAN/частной сети,
также задайте `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`; OpenClaw
блокирует частные/внутренние конечные точки изображений, совместимые с OpenAI, если это
явное разрешение отсутствует.

Генерация:

```
/tool image_generate model=openai/gpt-image-2 prompt="Отшлифованный постер запуска OpenClaw на macOS" size=3840x2160 count=1
```

Генерация прозрачного PNG:

```
/tool image_generate model=openai/gpt-image-1.5 prompt="Простая наклейка с красным кругом на прозрачном фоне" outputFormat=png background=transparent
```

Редактирование:

```
/tool image_generate model=openai/gpt-image-2 prompt="Сохранить форму объекта, изменить материал на полупрозрачное стекло" image=/path/to/reference.png size=1024x1536
```

## Генерация видео

Встроенный плагин `openai` регистрирует генерацию видео через
инструмент `video_generate`.

| Возможность | Значение |
| - | - |
| Модель по умолчанию | `openai/sora-2` |
| Режимы | Текст в видео, изображение в видео, редактирование одного видео |
| Эталонные входные данные | 1 изображение или 1 видео |
| Переопределение размера | Поддерживается для преобразования текста и изображения в видео |
| Соотношение сторон | Преобразуется в ближайший поддерживаемый размер, исходное значение не передаётся |
| Другие переопределения | `resolution`, `audio`, `watermark` не поддерживаются, отбрасываются с предупреждением инструмента |

Запросы OpenAI на преобразование изображения в видео используют `POST /v1/videos` с изображением
`input_reference`. Для редактирования одного видео используется `POST /v1/videos/edits` с
загруженным видео в поле `video`.

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  agents: {
    defaults: {
      videoGenerationModel: { primary: "openai/sora-2" },
    },
  },
}
```

> [!NOTE]
>
> Общие параметры инструмента, выбор провайдера и поведение при переключении
> после сбоя описаны в разделе [Генерация видео](https://docs2.openclaw.ai/ru/tools/video-generation.md).
>
> Провайдер OpenAI объявляет `supportsSize`, но не `supportsAspectRatio` или
> `supportsResolution`. Общий слой нормализации OpenClaw преобразует запрошенное
> значение `aspectRatio` в наиболее близкое соответствующее значение OpenAI `size` до
> передачи запроса провайдеру, поэтому запросы с соотношением сторон обычно продолжают работать.
> Для `resolution` нет резервного значения размера, поэтому оно отбрасывается, а вызывающей стороне
> передаётся `Ignored unsupported overrides for openai/<model>: resolution=<value>`.

## Дополнение к промпту GPT-5

OpenClaw добавляет общее дополнение к промпту GPT-5 для моделей семейства GPT-5
у провайдера `openai` (включая устаревшие ссылки Codex до исправления, которые нормализуются
в `openai/*`). Другие провайдеры, также предоставляющие идентификаторы моделей семейства GPT-5,
например маршруты OpenRouter или opencode, не получают это наложение: оно включается по
идентификатору провайдера `openai`, а не только по идентификатору модели. Более старые модели GPT-4.x
никогда его не получают.

Нативный контур app-server Codex не получает контракт поведения для персоны и
дисциплины использования инструментов или дружественное наложение стиля взаимодействия через
инструкции разработчика; нативный Codex сохраняет собственное базовое поведение, поведение модели и
документации проекта, а OpenClaw отключает встроенную личность Codex для
нативных потоков, чтобы файлы личности в рабочем пространстве агента оставались приоритетными.
OpenClaw добавляет в нативные потоки Codex только контекст среды выполнения: доставку
через каналы, динамические инструменты OpenClaw, делегирование ACP, контекст рабочего пространства и
Skills OpenClaw. Текст рекомендаций по Heartbeat из этого же дополнения является
единственным исключением: нативные ходы Heartbeat Codex получают его в виде отдельных
инструкций по совместной работе, а не через общий механизм дополнения
к промпту.

Дополнение GPT-5 добавляет размеченный контракт поведения для сохранения
персоны, безопасности выполнения, дисциплины использования инструментов, формы вывода, проверок
завершённости и верификации в соответствующих промптах, сформированных OpenClaw. Поведение ответов,
зависящее от канала, и поведение беззвучных сообщений остаются в общей системной
подсказке OpenClaw и политике исходящей доставки. Слой дружественного стиля взаимодействия
настраивается отдельно.

| Значение | Эффект |
| - | - |
| `"friendly"` (по умолчанию) | Включает слой дружественного стиля взаимодействия |
| `"on"` | Псевдоним для `"friendly"` |
| `"off"` | Отключает только слой дружественного стиля |

> [tab] Конфигурация
>
> ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
> {
>   agents: {
>     defaults: {
>       promptOverlays: {
>         gpt5: { personality: "friendly" },
>       },
>     },
>   },
> }
> ```

> [tab] CLI
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> openclaw config set agents.defaults.promptOverlays.gpt5.personality off
> ```

> [!TIP]
>
> Во время выполнения значения не зависят от регистра, поэтому и `"Off"`, и `"off"`
> отключают слой дружественного стиля.

> [!NOTE]
>
> Устаревшее значение `plugins.entries.openai.config.personality` по-прежнему считывается как
> резервный вариант совместимости, если общая настройка
> `agents.defaults.promptOverlays.gpt5.personality` не задана.

## Голос и речь

> [accordion] Синтез речи (TTS)
>
> Встроенный плагин `openai` регистрирует синтез речи для
> интерфейса `messages.tts`.
>
> | Настройка | Путь конфигурации | Значение по умолчанию |
> | - | - | - |
> | Модель | `messages.tts.providers.openai.model` | `gpt-4o-mini-tts` |
> | Голос | `messages.tts.providers.openai.speakerVoice` | `coral` |
> | Скорость | `messages.tts.providers.openai.speed` | (не задано) |
> | Инструкции | `messages.tts.providers.openai.instructions` | (не задано, только `gpt-4o-mini-tts`) |
> | Формат | `messages.tts.providers.openai.responseFormat` | `opus` для голосовых сообщений, `mp3` для файлов |
> | Ключ API | `messages.tts.providers.openai.apiKey` | Резервное значение: `OPENAI_API_KEY` |
> | Базовый URL | `messages.tts.providers.openai.baseUrl` | `https://api.openai.com/v1` |
> | Дополнительное тело запроса | `messages.tts.providers.openai.extraBody` / `extra_body` | (не задано) |
>
> Доступные модели: `gpt-4o-mini-tts`, `tts-1`, `tts-1-hd`. Доступные голоса:
> `alloy`, `ash`, `ballad`, `cedar`, `coral`, `echo`, `fable`, `juniper`,
> `marin`, `onyx`, `nova`, `sage`, `shimmer`, `verse`.
>
> Значение `extraBody` объединяется с JSON запроса `/audio/speech` после полей,
> сгенерированных OpenClaw, поэтому используйте его для совместимых с OpenAI конечных точек, которым
> требуются дополнительные ключи, например `lang`. Ключи прототипа игнорируются.
>
> ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
> {
>   messages: {
>     tts: {
>       providers: {
>         openai: { model: "gpt-4o-mini-tts", speakerVoice: "coral" },
>       },
>     },
>   },
> }
> ```
>
> > [!NOTE]
> >
> > Задайте `OPENAI_TTS_BASE_URL`, чтобы переопределить базовый URL TTS, не затрагивая
> > конечную точку API чата. TTS OpenAI и голос Realtime настраиваются
> > с помощью ключа API платформы OpenAI; установки только с OAuth по-прежнему могут использовать
> > модели чата на базе Codex, но не голосовые ответы OpenAI в реальном времени.

> [accordion] Преобразование речи в текст
>
> Встроенный плагин `openai` регистрирует пакетное преобразование речи в текст через
> интерфейс транскрибирования в системе анализа медиа OpenClaw.
>
> * Модель по умолчанию: `gpt-4o-transcribe`
> * Конечная точка: OpenAI REST `/v1/audio/transcriptions`
> * Путь ввода: загрузка аудиофайла в формате multipart
> * Используется везде, где транскрибирование входящего аудио считывает `tools.media.audio`,
>   включая сегменты голосовых каналов Discord и аудиовложения каналов
>
> Чтобы принудительно использовать OpenAI для транскрибирования входящего аудио:
>
> ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
> {
>   tools: {
>     media: {
>       audio: {
>         models: [
>           {
>             type: "provider",
>             provider: "openai",
>             model: "gpt-4o-transcribe",
>           },
>         ],
>       },
>     },
>   },
> }
> ```
>
> Язык и подсказки промпта передаются в OpenAI, если они указаны в
> общей конфигурации аудиомедиа или в отдельном запросе транскрибирования.

> [accordion] Транскрибирование в реальном времени
>
> Встроенный плагин `openai` регистрирует транскрибирование в реальном времени для
> плагина Voice Call.
>
> | Настройка | Путь конфигурации | Значение по умолчанию |
> | - | - | - |
> | Модель | `plugins.entries.voice-call.config.streaming.providers.openai.model` | `gpt-4o-transcribe` |
> | Язык | `...openai.language` | (не задано) |
> | Промпт | `...openai.prompt` | (не задано) |
> | Длительность тишины | `...openai.silenceDurationMs` | `800` |
> | Порог VAD | `...openai.vadThreshold` | `0.5` |
> | Аутентификация | `...openai.apiKey`, `OPENAI_API_KEY` или профиль ключа API `openai` | Требуется ключ API платформы |
>
> > [!NOTE]
> >
> > Использует подключение WebSocket к `wss://api.openai.com/v1/realtime` со звуком
> > G.711 u-law (`g711_ulaw` / `audio/pcmu`). Для профиля ключа API `openai`
> > Gateway создаёт временный клиентский секрет для транскрибирования Realtime
> > перед открытием WebSocket. Этот потоковый провайдер предназначен для пути
> > транскрибирования Voice Call в реальном времени; сейчас Discord записывает короткие
> > сегменты и вместо него использует путь пакетного транскрибирования `tools.media.audio`.

> [accordion] Голосовая связь в реальном времени
>
> Встроенный плагин `openai` регистрирует голосовую связь в реальном времени для плагина
> Voice Call.
>
> | Настройка | Путь конфигурации | Значение по умолчанию |
> | - | - | - |
> | Модель | `plugins.entries.voice-call.config.realtime.providers.openai.model` | `gpt-realtime-2.1` |
> | Голос | `...openai.voice` | `alloy` |
> | Температура (мост развёртывания Azure) | `...openai.temperature` | `0.8` |
> | Порог VAD | `...openai.vadThreshold` | `0.5` |
> | Длительность тишины | `...openai.silenceDurationMs` | `500` |
> | Начальное дополнение | `...openai.prefixPaddingMs` | `300` |
> | Интенсивность рассуждений | `...openai.reasoningEffort` | (не задано) |
> | Аутентификация | профиль ключа API `openai`, `...openai.apiKey` или `OPENAI_API_KEY` | Требуется ключ API платформы OpenAI |
>
> Доступные встроенные голоса Realtime для `gpt-realtime-2.1`: `alloy`, `ash`,
> `ballad`, `coral`, `echo`, `sage`, `shimmer`, `verse`, `marin`, `cedar`.
> Для наилучшего качества Realtime OpenAI рекомендует `marin` и `cedar`. Это
> отдельный набор, не связанный с указанными выше голосами для преобразования текста в речь; голос,
> предназначенный только для TTS, например `fable`, `nova` или `onyx`, нельзя использовать в сеансах Realtime.
> Явно задайте модель `gpt-realtime-2.1-mini`, если предпочитаете
> уменьшенный и более дешёвый вариант Realtime 2.1.
>
> > [!NOTE]
> >
> > **GPT-Live (скоро).** Полнодуплексные модели OpenAI `gpt-live-1` и
> > `gpt-live-1-mini` заменили голосовой режим ChatGPT в июле 2026 года; API
> > для разработчиков постепенно становится доступен организациям с ранним доступом. OpenClaw
> > распознаёт семейство моделей, но пока не запускает его: сеансы GPT-Live
> > работают только через WebRTC, самостоятельно управляют очерёдностью реплик (без VAD) и делегируют работу
> > агента через протокол событий передачи управления, который транспорты Realtime OpenClaw
> > пока не реализуют. Настройка модели `gpt-live-*` приводит к безопасному отказу с
> > рекомендациями как для моста WebSocket, так и для браузерных сеансов Talk, вместо
> > неявного подключения звука без доступа к агенту. Во время раннего доступа доступ к API также
> > предоставляется отдельно каждой организации OpenAI. Используйте `gpt-realtime-2.1` (значение
> > по умолчанию), пока не будет добавлена поддержка GPT-Live.
>
> > [!NOTE]
> >
> > Серверные мосты OpenAI Realtime используют структуру сеанса WebSocket
> > общедоступной версии Realtime, которая не принимает `session.temperature`. Развёртывания Azure OpenAI
> > остаются доступными через `azureEndpoint` и `azureDeployment` и
> > сохраняют совместимую с развёртыванием структуру сеанса (включая `temperature`).
> > Поддерживаются двунаправленные вызовы инструментов и звук G.711 u-law.
>
> > [!NOTE]
> >
> > Голос для режима реального времени выбирается при создании сеанса. OpenAI позволяет
> > позднее изменять большинство полей сеанса, но голос нельзя изменить после того,
> > как модель выдала аудио в этом сеансе. В настоящее время OpenClaw предоставляет
> > встроенные идентификаторы голосов Realtime в виде строк.
>
> > [!NOTE]
> >
> > Функция Talk в Control UI использует браузерные сеансы OpenAI в режиме реального времени с
> > выпущенным Gateway временным клиентским секретом и прямым обменом WebRTC SDP
> > между браузером и OpenAI Realtime API. Gateway выпускает этот клиентский секрет с
> > выбранными учётными данными `openai`. Настроенные ключи, профили API-ключей и
> > `OPENAI_API_KEY` имеют приоритет; резервным вариантом служит OAuth-профиль
> > `openai` или внешний вход в Codex. Ретранслятор Gateway и мосты WebSocket
> > реального времени бэкенда Voice Call используют тот же порядок учётных данных
> > для нативных конечных точек OpenAI.
> > Сопровождающие могут выполнить проверку в реальной среде с помощью
> > `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts`;
> > этапы OpenAI проверяют и серверный мост WebSocket, и браузерный обмен
> > WebRTC SDP без записи секретов в журнал.
> > Передайте `--openai-only`, чтобы выполнить эти два этапа без учётных данных Google.

## Конечные точки Azure OpenAI

Встроенный провайдер `openai` может использовать ресурс Azure OpenAI для
генерации изображений посредством переопределения базового URL. На пути генерации
изображений OpenClaw обнаруживает имена хостов Azure в `models.providers.openai.baseUrl` и
автоматически переключается на формат запросов Azure.

> [!NOTE]
>
> Голос в режиме реального времени использует отдельный путь конфигурации
> (`plugins.entries.voice-call.config.realtime.providers.openai.azureEndpoint`)
> и не зависит от `models.providers.openai.baseUrl`. Параметры Azure см. в раскрывающемся разделе
> **Голос в режиме реального времени** в разделе [Голос и речь](#voice-and-speech).

Используйте Azure OpenAI, если:

* У вас уже есть подписка Azure OpenAI, квота или корпоративное
  соглашение
* Вам нужны региональное хранение данных или предоставляемые Azure средства соответствия требованиям
* Вы хотите сохранить трафик внутри существующего клиента Azure

### Конфигурация

Для генерации изображений Azure через встроенный провайдер `openai` укажите
в `models.providers.openai.baseUrl` свой ресурс Azure и задайте в `apiKey`
ключ Azure OpenAI (не ключ OpenAI Platform):

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  models: {
    providers: {
      openai: {
        baseUrl: "https://<your-resource>.openai.azure.com",
        apiKey: "<azure-openai-api-key>",
      },
    },
  },
}
```

OpenClaw распознаёт следующие суффиксы хостов Azure для маршрута генерации
изображений Azure:

* `*.openai.azure.com`
* `*.services.ai.azure.com`
* `*.cognitiveservices.azure.com`

Для запросов генерации изображений на распознанном хосте Azure OpenClaw:

* Отправляет заголовок `api-key` вместо `Authorization: Bearer`
* Использует пути, привязанные к развёртыванию (`/openai/deployments/{deployment}/...`)
* Добавляет `?api-version=...` к каждому запросу
* Использует тайм-аут запроса по умолчанию 600s для вызовов генерации изображений Azure.
  Значения `timeoutMs` отдельных вызовов по-прежнему переопределяют это значение по умолчанию.

Другие базовые URL (публичный OpenAI, прокси-серверы, совместимые с OpenAI) сохраняют
стандартный формат запросов OpenAI для изображений.

> [!NOTE]
>
> Для маршрутизации Azure в пути генерации изображений провайдера
> `openai` требуется OpenClaw 2026.4.22 или более поздней версии. Более ранние
> версии обрабатывают любой пользовательский `openai.baseUrl` как публичную
> конечную точку OpenAI и завершаются с ошибкой при работе с развёртываниями изображений Azure.

### Версия API

Задайте `AZURE_OPENAI_API_VERSION`, чтобы закрепить конкретную предварительную или общедоступную версию Azure
для пути генерации изображений Azure:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
export AZURE_OPENAI_API_VERSION="2024-12-01-preview"
```

Если переменная не задана, по умолчанию используется `2024-12-01-preview`.

### Имена моделей являются именами развёртываний

Azure OpenAI связывает модели с развёртываниями. Для запросов генерации изображений Azure,
направляемых через встроенный провайдер `openai`, поле `model` в OpenClaw
должно содержать **имя развёртывания Azure**, настроенное на портале Azure, а не
публичный идентификатор модели OpenAI.

Если вы создадите развёртывание с именем `gpt-image-2-prod`, обслуживающее `gpt-image-2`:

```
/tool image_generate model=openai/gpt-image-2-prod prompt="Чистый плакат" size=1024x1024 count=1
```

То же правило для имени развёртывания применяется к любому вызову генерации изображений,
направляемому через встроенный провайдер `openai`.

### Региональная доступность

В настоящее время генерация изображений Azure доступна только в некоторых регионах
(например, `eastus2`, `swedencentral`, `polandcentral`, `westus3`,
`uaenorth`). Перед созданием развёртывания проверьте актуальный список регионов
Microsoft и убедитесь, что конкретная модель доступна в вашем регионе.

### Различия параметров

Azure OpenAI и публичный OpenAI не всегда принимают одинаковые параметры изображений.
Azure может отклонять параметры, разрешённые публичным OpenAI (например, некоторые
значения `background` для `gpt-image-2`), или предоставлять их только в
определённых версиях модели. Эти различия обусловлены Azure и базовой моделью, а не
OpenClaw. Если запрос Azure завершается ошибкой проверки, проверьте на портале Azure
набор параметров, поддерживаемый вашим конкретным развёртыванием и версией API.

> [!NOTE]
>
> Azure OpenAI использует нативный транспорт и поведение совместимости, но не получает
> скрытые заголовки атрибуции OpenClaw — см. раскрывающийся раздел **Нативные и совместимые
> с OpenAI маршруты** в разделе [Расширенная конфигурация](#advanced-configuration).
>
> Для трафика чата или Responses в Azure (помимо генерации изображений) используйте
> процесс первоначальной настройки или отдельную конфигурацию провайдера Azure; одного
> `openai.baseUrl` недостаточно для применения формата API и аутентификации Azure.
> Существует отдельный провайдер `azure-openai-responses/*`; см. раскрывающийся раздел
> о серверной Compaction ниже.

## Расширенная конфигурация

Приведённые ниже примеры `params` для отдельных моделей определяют запрос
встроенного провайдера OpenClaw. Их настройка считается явно заданным поведением запроса,
поэтому маршрут `auto`, даже если он соответствует требованиям, остаётся в
OpenClaw вместо неявного выбора Codex. Нативная среда app-server Codex управляет
собственным транспортом и параметрами запросов; явный `agentRuntime.id: "codex"` приводит
к безопасному отказу, если фактический маршрут не объявлен совместимым с Codex.

> [accordion] Транспорт (WebSocket или SSE)
>
> OpenClaw в первую очередь использует WebSocket с резервным переходом на SSE (`"auto"`) для `openai/*`.
>
> В режиме `"auto"` OpenClaw:
>
> * Повторяет одну раннюю неудачную попытку WebSocket перед переходом на SSE
> * После сбоя помечает WebSocket как деградировавший на 60 секунд и использует SSE
>   в период восстановления
> * Добавляет стабильные заголовки идентификации сеанса и хода для повторных попыток и
>   переподключений
> * Нормализует счётчики использования (`input_tokens` / `prompt_tokens`) между
>   вариантами транспорта
>
> | Значение | Поведение |
> | - | - |
> | `"auto"` (по умолчанию) | Сначала WebSocket, затем резервный переход на SSE |
> | `"sse"` | Использовать только SSE |
> | `"websocket"` | Использовать только WebSocket |
>
> ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
> {
>   agents: {
>     defaults: {
>       models: {
>         "openai/gpt-5.5": {
>           params: { transport: "auto" },
>         },
>       },
>     },
>   },
> }
> ```
>
> Связанная документация OpenAI:
>
> * [Realtime API с WebSocket](https://platform.openai.com/docs/guides/realtime-websocket)
> * [Потоковые ответы API (SSE)](https://platform.openai.com/docs/guides/streaming-responses)

> [accordion] Быстрый режим
>
> OpenClaw предоставляет общий переключатель быстрого режима для `openai/*`:
>
> * **Чат/UI:** `/fast status|auto|on|off`
> * **Конфигурация:** `agents.defaults.models["<provider>/<model>"].params.fastMode`
>
> Когда он включён, OpenClaw сопоставляет быстрый режим с приоритетной обработкой OpenAI
> (`service_tier = "priority"`). Существующие значения `service_tier`
> сохраняются, и быстрый режим не перезаписывает `reasoning` или
> `text.verbosity`. `fastMode: "auto"` запускает новые вызовы модели в быстром режиме
> до автоматического порога, а последующие повторные, резервные вызовы, вызовы с
> результатами инструментов или продолжения запускает без быстрого режима.
> По умолчанию порог составляет 60 секунд; чтобы изменить его, задайте
> `params.fastAutoOnSeconds` для активной модели.
>
> ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
> {
>   agents: {
>     defaults: {
>       models: {
>         "openai/gpt-5.5": { params: { fastMode: "auto", fastAutoOnSeconds: 30 } },
>       },
>     },
>   },
> }
> ```
>
> > [!NOTE]
> >
> > Переопределения сеанса имеют приоритет над конфигурацией. Удаление переопределения
> > сеанса в UI Sessions возвращает сеанс к настроенному значению по умолчанию.

> [accordion] Приоритетная обработка (service\_tier)
>
> API OpenAI предоставляет приоритетную обработку через `service_tier`. Задайте её
> отдельно для каждой модели в OpenClaw:
>
> ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
> {
>   agents: {
>     defaults: {
>       models: {
>         "openai/gpt-5.5": { params: { serviceTier: "priority" } },
>       },
>     },
>   },
> }
> ```
>
> Поддерживаемые значения: `auto`, `default`, `flex`, `priority`.
>
> > [!WARNING]
> >
> > `serviceTier` передаётся только нативным конечным точкам OpenAI
> > (`api.openai.com`) и нативным конечным точкам Codex (`chatgpt.com/backend-api`).
> > Если какой-либо из этих провайдеров направляется через прокси-сервер, OpenClaw
> > оставляет `service_tier` без изменений.

> [accordion] Серверная Compaction (Responses API)
>
> Для моделей прямого OpenAI Responses (`openai/*` в `api.openai.com`)
> потоковая обёртка OpenClaw плагина OpenAI автоматически включает серверную
> Compaction:
>
> * Принудительно задаёт `store: true` (если совместимость модели не задаёт `supportsStore: false`)
> * Внедряет `context_management: [{ type: "compaction", compact_threshold: ... }]`
> * Значение `compact_threshold` по умолчанию: 70% от `contextWindow` (или `80000`, если
>   оно недоступно)
>
> Это относится к пути встроенной среды выполнения OpenClaw и к хукам
> провайдера OpenAI, используемым встроенными запусками. Нативная среда
> app-server Codex управляет собственным контекстом через Codex, и этот
> параметр на неё не влияет.
>
> > [tab] Включить явно
> >
> > Полезно для совместимых конечных точек, например Azure OpenAI Responses:
> >
> > ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
> > {
> >   agents: {
> >     defaults: {
> >       models: {
> >         "azure-openai-responses/gpt-5.5": {
> >           params: { responsesServerCompaction: true },
> >         },
> >       },
> >     },
> >   },
> > }
> > ```
>
> > [tab] Пользовательский порог
> >
> > ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
> > {
> >   agents: {
> >     defaults: {
> >       models: {
> >         "openai/gpt-5.5": {
> >           params: {
> >             responsesServerCompaction: true,
> >             responsesCompactThreshold: 120000,
> >           },
> >         },
> >       },
> >     },
> >   },
> > }
> > ```
>
> > [tab] Отключить
> >
> > ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
> > {
> >   agents: {
> >     defaults: {
> >       models: {
> >         "openai/gpt-5.5": {
> >           params: { responsesServerCompaction: false },
> >         },
> >       },
> >     },
> >   },
> > }
> > ```
>
> > [!NOTE]
> >
> > `responsesServerCompaction` управляет только внедрением `context_management`.
> > Модели прямого OpenAI Responses по-прежнему принудительно задают
> > `store: true`, если совместимость не задаёт `supportsStore: false`.

> [accordion] Строгий агентный режим GPT
>
> Для моделей семейства GPT-5 провайдера `openai`, запускаемых через
> встроенную среду выполнения OpenClaw, OpenClaw уже по умолчанию использует более
> строгий контракт выполнения под названием `strict-agentic`. Он автоматически
> активируется, когда определённым провайдером является `openai`, а
> идентификатор модели соответствует семейству GPT-5, если только конфигурация
> явно не отключает его:
>
> ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
> {
>   agents: {
>     defaults: {
>       embeddedAgent: { executionContract: "default" },
>     },
>   },
> }
> ```
>
> Явная установка `"strict-agentic"` не оказывает никакого действия в поддерживаемом режиме (это
> уже значение по умолчанию) и не влияет на неподдерживаемые пары провайдеров и моделей.
>
> Когда `strict-agentic` активен, OpenClaw:
>
> * Автоматически включает `update_plan` для объёмных задач
> * Повторяет структурно пустые ходы или ходы, содержащие только рассуждения, с продолжением,
>   содержащим видимый ответ
> * Использует явные события плана среды выполнения, когда выбранная среда
>   их предоставляет
>
> OpenClaw не классифицирует текст ассистента, чтобы определить, является ли ход
> планом, обновлением прогресса или окончательным ответом.
>
> > [!NOTE]
> >
> > Этот контракт полностью реализован во встроенном средстве запуска агентов OpenClaw. Он
> > не применяется к нативной среде app-server Codex, которая самостоятельно управляет
> > поведением ходов и планов; для нативных запусков Codex выбор среды имеет большее
> > значение, чем настройка контракта выполнения.

> [accordion] Нативные и OpenAI-совместимые маршруты
>
> OpenClaw обрабатывает прямые конечные точки OpenAI, Codex и Azure OpenAI
> иначе, чем универсальные OpenAI-совместимые прокси `/v1`:
>
> **Нативные маршруты** (`openai/*`, Azure OpenAI):
>
> * Сохраняют `reasoning: { effort: "none" }` только для моделей, поддерживающих
>   степень `none` OpenAI
> * Не передают отключённые рассуждения моделям или прокси, отклоняющим
>   `reasoning.effort: "none"`
> * По умолчанию используют строгий режим для схем инструментов
> * Добавляют скрытые заголовки атрибуции только на проверенных нативных узлах (Azure
>   OpenAI не получает эти заголовки, хотя является нативным маршрутом)
> * Сохраняют формирование запросов, предназначенное только для OpenAI (`service_tier`, `store`,
>   совместимость рассуждений, подсказки для кеша промптов)
>
> **Прокси/совместимые маршруты:**
>
> * Используют менее строгое поведение совместимости
> * Удаляют `store` Completions из ненативных полезных нагрузок `openai-completions`
> * Принимают расширенный сквозной JSON `params.extra_body`/`params.extraBody`
>   для OpenAI-совместимых прокси Completions
> * Принимают `params.chat_template_kwargs` для OpenAI-совместимых прокси Completions,
>   таких как vLLM
> * Не требуют строгих схем инструментов или заголовков только для нативных маршрутов

## Связанные материалы

> [card] [Выбор модели](https://docs2.openclaw.ai/ru/concepts/model-providers.md)
>
> Выбор провайдеров, ссылок на модели и поведения при переключении после сбоя.

> [card] [Генерация изображений](https://docs2.openclaw.ai/ru/tools/image-generation.md)
>
> Общие параметры инструмента генерации изображений и выбор провайдера.

> [card] [Генерация видео](https://docs2.openclaw.ai/ru/tools/video-generation.md)
>
> Общие параметры инструмента генерации видео и выбор провайдера.

> [card] [OAuth и аутентификация](https://docs2.openclaw.ai/ru/gateway/authentication.md)
>
> Сведения об аутентификации и правила повторного использования учётных данных.