OpenAI

OpenAI надає API для розробників для моделей GPT, а Codex також доступний як агент для програмування в межах плану ChatGPT через клієнти Codex від OpenAI. OpenClaw зберігає ці поверхні окремими, щоб конфігурація залишалася передбачуваною.

OpenClaw використовує openai/* як канонічний маршрут моделей OpenAI. Вбудовані ходи агента на моделях OpenAI за замовчуванням виконуються через нативне середовище виконання app-server Codex; пряма автентифікація ключем OpenAI API залишається доступною для неагентних поверхонь OpenAI, як-от зображення, embeddings, мовлення та realtime.

• Моделі агентів - моделі openai/* через середовище виконання Codex; увійдіть через автентифікацію Codex для використання підписки ChatGPT/Codex або налаштуйте Codex-сумісний резервний ключ OpenAI API, якщо ви навмисно хочете автентифікацію ключем API.
• Неагентні API OpenAI - прямий доступ до OpenAI Platform з оплатою за використання через OPENAI_API_KEY або онбординг ключа OpenAI API.
• Застаріла конфігурація - посилання на моделі openai-codex/* виправляються командою openclaw doctor --fix до openai/* плюс середовище виконання Codex.

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

Провайдер, модель, середовище виконання та канал - це окремі шари. Якщо ці мітки змішуються між собою, прочитайте Середовища виконання агентів, перш ніж змінювати конфігурацію.

Швидкий вибір

Мапа назв

Назви схожі, але не взаємозамінні:

Це означає, що конфігурація може навмисно містити посилання на моделі openai/*, тоді як профілі автентифікації все ще вказують на Codex-сумісні облікові дані. Для нової конфігурації надавайте перевагу auth.order.openai; наявні профілі openai-codex:* і auth.order.openai-codex залишаються підтримуваними. openclaw doctor --fix переписує застарілі посилання на моделі openai-codex/* до канонічного маршруту моделей OpenAI.

Покриття функцій OpenClaw

Embeddings пам’яті

OpenClaw може використовувати OpenAI або OpenAI-сумісну endpoint embeddings для індексування memory_search і embeddings запитів:

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

Для OpenAI-сумісних endpoint, які потребують асиметричних міток embeddings, задайте queryInputType і documentInputType у memorySearch. OpenClaw передає їх як специфічні для провайдера поля запиту input_type: embeddings запитів використовують 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: "sk-..." },  agents: { defaults: { model: { primary: "openai/gpt-5.5" } } },}

{  env: { OPENAI_API_KEY: "sk-..." },  agents: { defaults: { model: { primary: "openai/chat-latest" } } },}

openclaw onboard --auth-choice openai-codex

openclaw models auth login --provider openai-codex

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

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

openclaw models list --provider openai-codex

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

{  plugins: { entries: { codex: { enabled: true } } },  agents: {    defaults: {      model: { primary: "openai/gpt-5.5" },    },  },  auth: {    order: {      openai: [        "openai-codex:[email protected]",        "openai:api-key-backup",      ],    },  },}

openclaw models statusopenclaw models auth list --provider openai-codexopenclaw 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-codex

openclaw doctor --fixopenclaw config validate

openclaw models auth login --provider openai-codexopenclaw models status --probe --probe-provider openai-codex

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

Нативна автентифікація app-server Codex

Нативний harness app-server Codex використовує посилання на моделі openai/* плюс пропущену конфігурацію runtime або provider/model agentRuntime.id: "codex", але його автентифікація все ще базується на обліковому записі. OpenClaw вибирає автентифікацію в такому порядку:

1. Впорядковані профілі автентифікації OpenAI для агента, бажано в auth.order.openai. Наявні профілі openai-codex:* і auth.order.openai-codex залишаються чинними для старіших інсталяцій.
2. Наявний обліковий запис app-server, наприклад локальний вхід Codex CLI ChatGPT.
3. Лише для локальних запусків app-server stdio: CODEX_API_KEY, потім OPENAI_API_KEY, коли app-server повідомляє, що облікового запису немає, але все ще потребує автентифікації OpenAI.

Це означає, що локальний вхід за підпискою ChatGPT/Codex не замінюється лише тому, що процес gateway також має OPENAI_API_KEY для прямих моделей OpenAI або embeddings. Резервний API-ключ із env використовується лише в локальному stdio-шляху без облікового запису; він не надсилається до WebSocket-з'єднань app-server. Коли вибрано профіль Codex у стилі підписки, OpenClaw також прибирає CODEX_API_KEY і OPENAI_API_KEY із породженого дочірнього процесу stdio app-server і надсилає вибрані облікові дані через RPC входу app-server. Коли цей профіль підписки заблоковано лімітом використання Codex, OpenClaw може перейти до наступного впорядкованого профілю API-ключа openai:* без зміни вибраної моделі або виходу з harness Codex. Після проходження часу скидання підписки профіль підписки знову стає придатним.

Генерація зображень

Вбудований plugin 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-сумісні endpoints зберігають свої налаштовані deployment/model names.

Те саме налаштування доступне для headless запусків CLI:

openclaw infer image generate \  --model openai/gpt-image-1.5 \  --output-format png \  --background transparent \  --prompt "A simple red circle sticker on a transparent background" \  --json

Використовуйте ті самі прапорці --output-format і --background з openclaw infer image edit, коли починаєте з вхідного файлу. --openai-background залишається доступним як специфічний для OpenAI alias.

Для інсталяцій Codex OAuth залишайте те саме посилання openai/gpt-image-2. Коли налаштовано OAuth-профіль openai-codex, OpenClaw розв'язує цей збережений access token OAuth і надсилає запити зображень через backend Codex Responses. Він не пробує спершу OPENAI_API_KEY і не переходить мовчки на API-ключ для цього запиту. Налаштуйте models.providers.openai явно з API-ключем, власним base URL або Azure endpoint, коли потрібен прямий маршрут OpenAI Images API. Якщо цей власний image endpoint перебуває в довіреній LAN/приватній адресі, також установіть browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true; OpenClaw залишає приватні/внутрішні OpenAI-сумісні image endpoints заблокованими, якщо ця opt-in опція відсутня.

Згенерувати:

/tool image_generate model=openai/gpt-image-2 prompt="A polished launch poster for OpenClaw on macOS" size=3840x2160 count=1

Згенерувати прозорий PNG:

/tool image_generate model=openai/gpt-image-1.5 prompt="A simple red circle sticker on a transparent background" outputFormat=png background=transparent

Редагувати:

/tool image_generate model=openai/gpt-image-2 prompt="Preserve the object shape, change the material to translucent glass" image=/path/to/reference.png size=1024x1536

Генерація відео

Вбудований Plugin openai реєструє генерацію відео через інструмент video_generate.

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

Внесок промпта GPT-5

OpenClaw додає спільний внесок промпта GPT-5 для запусків сімейства GPT-5 у різних постачальників. Він застосовується за ідентифікатором моделі, тому openai/gpt-5.5, застарілі refs до repair, як-от openai-codex/gpt-5.5, openrouter/openai/gpt-5.5, opencode/gpt-5.5, та інші сумісні refs GPT-5 отримують той самий overlay. Старіші моделі GPT-4.x не отримують його.

Вбудований нативний harness Codex використовує ту саму поведінку GPT-5 і overlay heartbeat через інструкції розробника app-server Codex, тому сеанси openai/gpt-5.x, спрямовані через Codex, зберігають ті самі настанови щодо доведення дій до кінця та проактивного heartbeat, хоча рештою промпта harness володіє Codex.

Внесок GPT-5 додає тегований контракт поведінки для сталості persona, безпеки виконання, дисципліни інструментів, форми виводу, перевірок завершення та верифікації. Поведінка відповідей для конкретних каналів і тихих повідомлень лишається у спільному системному промпті OpenClaw та політиці вихідної доставки. Настанови GPT-5 завжди ввімкнені для відповідних моделей. Дружній шар стилю взаємодії є окремим і налаштовуваним.

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

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

Голос і мовлення

{  messages: {    tts: {      providers: {        openai: { model: "gpt-4o-mini-tts", voice: "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=... до кожного запиту
• Використовує типовий тайм-аут запиту 600 с для викликів генерації зображень Azure. Значення timeoutMs для окремих викликів усе ще перевизначають це типове значення.

Інші базові URL-адреси (публічний OpenAI, OpenAI-сумісні проксі) зберігають стандартну форму запиту зображень OpenAI.

Версія API

Установіть AZURE_OPENAI_API_VERSION, щоб зафіксувати конкретну preview- або GA-версію 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="A clean poster" size=1024x1024 count=1

Те саме правило щодо назви розгортання застосовується до викликів генерації зображень, маршрутизованих через вбудований провайдер openai.

Регіональна доступність

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

Відмінності параметрів

Azure OpenAI і публічний OpenAI не завжди приймають однакові параметри зображень. Azure може відхиляти параметри, які дозволяє публічний OpenAI (наприклад, певні значення background для gpt-image-2), або надавати їх лише для конкретних версій моделей. Ці відмінності походять від Azure і базової моделі, а не від OpenClaw. Якщо запит Azure завершується помилкою валідації, перевірте набір параметрів, підтримуваний вашим конкретним розгортанням і версією API на порталі Azure.

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

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

{  agents: {    defaults: {      models: {        "openai/gpt-5.5": { params: { fastMode: true } },      },    },  },}

{  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: {      embeddedPi: { executionContract: "strict-agentic" },    },  },}

Пов’язане