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 описаны требования к владельцу организации и явному разрешению Usage Dashboard для доступа к данным об использовании.

Провайдер, модель, среда выполнения и канал — отдельные уровни. Если эти понятия смешиваются, прочитайте раздел Среды выполнения агентов, прежде чем изменять конфигурацию.

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

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

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

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

Явное нестандартное значение 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.

Ограниченная предварительная версия 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 и руководство по доступу.

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

openclaw models list --provider openai

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

openclaw models set openai/gpt-5.5

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

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

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

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

{  agents: {    defaults: {      memorySearch: {        provider: "openai",        model: "text-embedding-3-small",      },    },  },}

Для совместимых с OpenAI конечных точек, которым требуются разные метки эмбеддингов, задайте queryInputType и documentInputType в memorySearch. OpenClaw передаёт их как специфичные для провайдера поля запроса input_type: для эмбеддингов запросов используется queryInputType; для индексируемых фрагментов памяти и пакетного индексирования — documentInputType. Полный пример см. в справочнике по конфигурации памяти.

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

openclaw onboard --auth-choice openai-api-key

openclaw onboard --openai-api-key "$OPENAI_API_KEY"

openclaw models list --provider openai

{  env: { OPENAI_API_KEY: "example-openai-key-not-real" },  agents: { defaults: { model: { primary: "openai/gpt-5.6" } } },}

{  env: { OPENAI_API_KEY: "example-openai-key-not-real" },  agents: { defaults: { model: { primary: "openai/chat-latest" } } },}

openclaw onboard --auth-choice openai

openclaw models auth login --provider openai

openclaw models auth login --provider openai --device-code

openclaw config set agents.defaults.model.primary openai/gpt-5.6-sol

openclaw models list --provider openai

{  plugins: { entries: { codex: { enabled: true } } },  agents: {    defaults: {      model: { primary: "openai/gpt-5.6-sol" },    },  },}

{  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",      ],    },  },}

openclaw models statusopenclaw models auth list --provider openaiopenclaw config get agents.defaults.model --jsonopenclaw config get models.providers.openai.agentRuntime --json

openclaw models status --agent <id>openclaw models auth list --agent <id> --provider openai

openclaw doctor --fixopenclaw config validate

openclaw models auth login --provider openaiopenclaw models status --probe --probe-provider openai

openclaw models auth login --provider openai --profile-id openai:ritsukoopenclaw models auth login --provider openai --profile-id openai:lain

{  models: {    providers: {      openai: {        models: [{ id: "gpt-5.5", contextTokens: 160000 }],      },    },  },}

Аутентификация нативного 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.

{  agents: {    defaults: {      imageGenerationModel: { primary: "openai/gpt-image-2" },    },  },}

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:

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 на преобразование изображения в видео используют POST /v1/videos с изображением input_reference. Для редактирования одного видео используется POST /v1/videos/edits с загруженным видео в поле video.

{  agents: {    defaults: {      videoGenerationModel: { primary: "openai/sora-2" },    },  },}

Дополнение к промпту 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 и политике исходящей доставки. Слой дружественного стиля взаимодействия настраивается отдельно.

{  agents: {    defaults: {      promptOverlays: {        gpt5: { personality: "friendly" },      },    },  },}

openclaw config set agents.defaults.promptOverlays.gpt5.personality off

Голос и речь

{  messages: {    tts: {      providers: {        openai: { model: "gpt-4o-mini-tts", speakerVoice: "coral" },      },    },  },}

{  tools: {    media: {      audio: {        models: [          {            type: "provider",            provider: "openai",            model: "gpt-4o-transcribe",          },        ],      },    },  },}

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

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

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

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

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

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

{  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 для изображений.

Версия API

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

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.

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

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

{  agents: {    defaults: {      models: {        "openai/gpt-5.5": {          params: { transport: "auto" },        },      },    },  },}

{  agents: {    defaults: {      models: {        "openai/gpt-5.5": { params: { fastMode: "auto", fastAutoOnSeconds: 30 } },      },    },  },}

{  agents: {    defaults: {      models: {        "openai/gpt-5.5": { params: { serviceTier: "priority" } },      },    },  },}

{  agents: {    defaults: {      models: {        "azure-openai-responses/gpt-5.5": {          params: { responsesServerCompaction: true },        },      },    },  },}

{  agents: {    defaults: {      models: {        "openai/gpt-5.5": {          params: {            responsesServerCompaction: true,            responsesCompactThreshold: 120000,          },        },      },    },  },}

{  agents: {    defaults: {      models: {        "openai/gpt-5.5": {          params: { responsesServerCompaction: false },        },      },    },  },}

{  agents: {    defaults: {      embeddedAgent: { executionContract: "default" },    },  },}

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