---
read_when:
    - Інтеграція інструментів, що очікують OpenAI Chat Completions
summary: Надайте через Gateway HTTP-кінцеву точку `/v1/chat/completions`, сумісну з OpenAI
title: Чат-завершення OpenAI
x-i18n:
    generated_at: "2026-07-12T13:13:37Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 9b1fffd2ce3da881ecd91adbb7c5d10b1d7adbd99af9b2ea4544b62ecbaf1f32
    source_path: gateway/openai-http-api.md
    workflow: 16
---

Gateway може надавати невелику поверхню Chat Completions, сумісну з OpenAI. Вона **вимкнена за замовчуванням**.

Після ввімкнення всі наведені нижче ендпоїнти працюють на тому самому порту, що й Gateway (мультиплексування WS + HTTP):

| Метод | Шлях                   |
| ------ | ---------------------- |
| POST   | `/v1/chat/completions` |
| GET    | `/v1/models`           |
| GET    | `/v1/models/{id}`      |
| POST   | `/v1/embeddings`       |
| POST   | `/v1/responses`        |

Запити виконуються як звичайний запуск агента Gateway (тим самим шляхом коду, що й `openclaw agent`), тому маршрутизація, дозволи та конфігурація відповідають вашому Gateway.

## Увімкнення ендпоїнта

```json5
{
  gateway: {
    http: {
      endpoints: {
        chatCompletions: { enabled: true },
      },
    },
  },
}
```

Щоб вимкнути, установіть `enabled: false` (або не вказуйте цей параметр).

## Межа безпеки (важливо)

Вважайте цей ендпоїнт таким, що надає **повний операторський доступ** до екземпляра Gateway:

- Чинний токен або пароль Gateway для цього ендпоїнта еквівалентний обліковим даним власника чи оператора, а не вузькій області доступу окремого користувача.
- Запити проходять тим самим шляхом агента площини керування, що й довірені дії оператора, тому, якщо політика цільового агента дозволяє чутливі інструменти, цей ендпоїнт може їх використовувати.
- Залишайте його доступним лише через local loopback, tailnet або приватну точку входу. Не відкривайте його для загальнодоступного Інтернету.

Матриця автентифікації:

| Шлях автентифікації                                                                                  | Поведінка                                                                                                                                                                                                                                                                                                                                                                         |
| ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `gateway.auth.mode="token"` або `"password"` + `Authorization: Bearer ...`                           | Підтверджує володіння спільним секретом Gateway. Ігнорує будь-який заголовок `x-openclaw-scopes` і відновлює повний стандартний набір операторських областей доступу: `operator.admin`, `operator.approvals`, `operator.pairing`, `operator.read`, `operator.talk.secrets`, `operator.write`. Вважає репліки чату репліками від власника. |
| Довірений HTTP із даними ідентичності (автентифікація через довірений проксі або `gateway.auth.mode="none"` у приватній точці входу) | Ураховує `x-openclaw-scopes`, якщо його вказано; за його відсутності використовує стандартний набір операторських областей доступу. Втрачає семантику власника, лише коли викликач явно звужує області доступу та не додає `operator.admin`. Для елементів керування рівня власника, як-от `x-openclaw-model`, потрібна область `operator.admin`. |

Див. [Операторські області доступу](/uk/gateway/operator-scopes), [Безпека](/uk/gateway/security) та [Віддалений доступ](/uk/gateway/remote).

## Автентифікація

Використовує конфігурацію автентифікації Gateway (подробиці про відповідний режим див. у розділі [Автентифікація через довірений проксі](/uk/gateway/trusted-proxy-auth)):

| Режим                              | Спосіб автентифікації                                                                                                                                                                                                 |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `gateway.auth.mode="token"`         | `Authorization: Bearer <token>`. Задається через `gateway.auth.token` або `OPENCLAW_GATEWAY_TOKEN`.                                                                                                                    |
| `gateway.auth.mode="password"`      | `Authorization: Bearer <password>`. Задається через `gateway.auth.password` або `OPENCLAW_GATEWAY_PASSWORD`.                                                                                                           |
| `gateway.auth.mode="trusted-proxy"` | Маршрутизуйте через налаштований проксі з підтримкою ідентичності; він додає необхідні заголовки ідентичності. Для проксі local loopback на тому самому хості потрібно явно встановити `gateway.auth.trustedProxy.allowLoopback = true`. |
| `gateway.auth.mode="none"`          | Заголовок автентифікації не потрібен (лише приватна точка входу).                                                                                                                                                      |

Примітки:

- Викликачі на тому самому хості, які оминають проксі в Gateway із режимом `trusted-proxy`, можуть безпосередньо використовувати резервний варіант `gateway.auth.password` / `OPENCLAW_GATEWAY_PASSWORD`. Наявність у запиті будь-якого заголовка `Forwarded`, `X-Forwarded-*` або `X-Real-IP` натомість залишає запит на шляху довіреного проксі.
- Якщо налаштовано `gateway.auth.rateLimit` і забагато спроб автентифікації завершуються невдало, ендпоїнт повертає `429` із заголовком `Retry-After`.

## Коли використовувати цей ендпоїнт

- Віддавайте йому перевагу перед додаванням нового вбудованого каналу, якщо ваша інтеграція є лише ще однією операторською або клієнтською поверхнею для того самого Gateway.
- Для нативних мобільних клієнтів, які безпосередньо підключаються до віддаленого Gateway, віддавайте перевагу [WebChat](/uk/web/webchat) або [протоколу Gateway](/uk/gateway/protocol) із початковим налаштуванням спареного пристрою та потоком токена пристрою, щоб пристрою не був потрібен спільний HTTP-токен або пароль.
- Натомість створіть Plugin каналу, якщо інтегруєте зовнішню мережу обміну повідомленнями з власними користувачами, кімнатами, доставленням через Webhook або вихідним транспортом. Див. [Створення плагінів](/uk/plugins/building-plugins).

## Контракт моделі з пріоритетом агента

OpenClaw трактує поле OpenAI `model` як **цільового агента**, а не як необроблений ідентифікатор моделі постачальника.

| Значення `model`                              | Куди маршрутизується                                                                                                                             |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `openclaw`                                    | Налаштований агент за замовчуванням                                                                                                               |
| `openclaw/default`                            | Налаштований агент за замовчуванням (стабільний псевдонім; його безпечно жорстко задавати, навіть якщо справжній ідентифікатор агента за замовчуванням відрізняється між середовищами) |
| `openclaw/<agentId>` або `openclaw:<agentId>` | Конкретний агент                                                                                                                                 |
| `agent:<agentId>`                             | Конкретний агент (псевдонім для сумісності)                                                                                                      |

Необов’язкові заголовки запиту:

| Заголовок                                       | Дія                                                                                                                                                                                                                                                                                                                                               |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `x-openclaw-model: <provider/model-or-bare-id>` | Перевизначає серверну модель для вибраного агента. Викликачі з токеном спільного секрету можуть використовувати його безпосередньо; викликачам із даними ідентичності (`trusted-proxy` або приватна точка входу без автентифікації з `x-openclaw-scopes`) потрібна область `operator.admin`, інакше повертається `403 missing scope: operator.admin`. |
| `x-openclaw-agent-id: <agentId>`                | Перевизначення вибору агента для сумісності.                                                                                                                                                                                                                                                                                                      |
| `x-openclaw-session-key: <sessionKey>`          | Явна маршрутизація сеансу. Відхиляється з помилкою `400 invalid_request_error`, якщо використовується зарезервований внутрішній простір імен (`subagent:`, `cron:`, `acp:`).                                                                                                                                                                         |
| `x-openclaw-message-channel: <channel>`         | Установлює синтетичний контекст вхідного каналу для запитів і політик, що враховують канал.                                                                                                                                                                                                                                                        |

`/v1/models` перелічує цілі агентів верхнього рівня (`openclaw`, `openclaw/default`, `openclaw/<agentId>`), а не серверні моделі постачальників чи підагентів; підагенти залишаються внутрішньою топологією виконання. Якщо не вказати `x-openclaw-model`, вибраний агент працюватиме зі своєю звичайною налаштованою моделлю.

`/v1/embeddings` використовує ті самі ідентифікатори `model`, що позначають цільового агента. Надішліть `x-openclaw-model` (від викликача зі спільним секретом або викликача з даними ідентичності та областю `operator.admin`), щоб вибрати конкретну модель вбудовування; інакше запит використовуватиме звичайну конфігурацію вбудовування вибраного агента.

## Поведінка сеансу

За замовчуванням ендпоїнт є **безстанним для кожного запиту** (для кожного виклику створюється новий ключ сеансу).

Якщо запит містить рядок OpenAI `user`, Gateway виводить із нього стабільний ключ сеансу, завдяки чому повторні виклики можуть спільно використовувати сеанс агента. Для власних застосунків повторно використовуйте те саме значення `user` для кожної гілки розмови; уникайте ідентифікаторів рівня облікового запису, якщо не хочете, щоб кілька розмов або пристроїв спільно використовували один сеанс OpenClaw. Використовуйте `x-openclaw-session-key` лише тоді, коли потрібен явний контроль маршрутизації між кількома клієнтами або гілками, із ключами, що належать застосунку й не використовують зарезервовані вище простори імен.

## Обмеження запитів (конфігурація)

Стандартні значення можна налаштувати в `gateway.http.endpoints.chatCompletions`:

```json5
{
  gateway: {
    http: {
      endpoints: {
        chatCompletions: {
          enabled: true,
          maxBodyBytes: 20000000,
          maxImageParts: 8,
          maxTotalImageBytes: 20000000,
          images: {
            allowUrl: false,
            urlAllowlist: ["cdn.example.com", "*.assets.example.com"],
            allowedMimes: [
              "image/jpeg",
              "image/png",
              "image/gif",
              "image/webp",
              "image/heic",
              "image/heif",
            ],
            maxBytes: 10485760,
            maxRedirects: 3,
            timeoutMs: 10000,
          },
        },
      },
    },
  },
}
```

Стандартні значення, якщо параметри не вказано:

| Ключ                  | Стандартне значення                                                                                 |
| --------------------- | --------------------------------------------------------------------------------------------------- |
| `maxBodyBytes`        | 20 МБ                                                                                               |
| `maxImageParts`       | 8 (максимальна кількість частин `image_url`, прочитаних з останнього повідомлення користувача)       |
| `maxTotalImageBytes`  | 20 МБ (загальний обсяг декодованих байтів у всіх частинах `image_url` одного запиту)                 |
| `images.allowUrl`     | `false` (частини `image_url`, отримані з URL, відхиляються, якщо їх явно не дозволено)               |
| `images.maxBytes`     | 10 МБ на зображення                                                                                 |
| `images.maxRedirects` | 3                                                                                                   |
| `images.timeoutMs`    | 10 с                                                                                                |

Джерела `image_url` у форматах HEIC/HEIF приймаються та нормалізуються до JPEG перед передаванням постачальнику через спільний обробник зображень OpenClaw (Rastermill), який для форматів, що потребують підтримки зовнішнього кодека, резервно використовує системний конвертер (`sips`, ImageMagick, GraphicsMagick або ffmpeg).

Примітка щодо безпеки: додавання імені хоста до списку дозволених не обходить блокування приватних/внутрішніх IP-адрес. Для Gateway, доступних з інтернету, застосовуйте засоби контролю вихідного мережевого трафіку на додачу до захисту на рівні застосунку. Див. [Безпека](/uk/gateway/security).

## Контракт інструментів чату

`/v1/chat/completions` підтримує підмножину функціональних інструментів, сумісну з поширеними клієнтами OpenAI Chat.

### Підтримувані поля запиту

| Поле                       | Примітки                                                                                                                                                    |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tools`                    | Масив `{ "type": "function", "function": { ... } }`                                                                                                         |
| `tool_choice`              | `"auto"`, `"none"`, `"required"` або `{ "type": "function", "function": { "name": "..." } }`                                                                 |
| `messages[*].role: "tool"` | Наступні запити                                                                                                                                             |
| `messages[*].tool_call_id` | Прив’язує результат інструмента до попереднього виклику інструмента                                                                                          |
| `max_completion_tokens`    | Число; обмеження загальної кількості токенів завершення на один виклик (включно з токенами міркування). Поточна назва поля; використовується, коли надіслано і його, і `max_tokens`. |
| `max_tokens`               | Число; застарілий псевдонім, ігнорується, якщо також указано `max_completion_tokens`.                                                                        |
| `temperature`              | Число від 0 до 2; застосовується за можливості та передається вищому провайдеру. `400 invalid_request_error`, якщо значення поза діапазоном.                  |
| `top_p`                    | Число від 0 до 1; застосовується за можливості. `400 invalid_request_error`, якщо значення поза діапазоном.                                                  |
| `frequency_penalty`        | Число від -2.0 до 2.0; застосовується за можливості. `400 invalid_request_error`, якщо значення поза діапазоном.                                             |
| `presence_penalty`         | Число від -2.0 до 2.0; застосовується за можливості. `400 invalid_request_error`, якщо значення поза діапазоном.                                             |
| `seed`                     | Ціле число; застосовується за можливості. `400 invalid_request_error` для нецілих значень.                                                                   |
| `stop`                     | Рядок або масив із щонайбільше 4 рядків; застосовується за можливості. `400 invalid_request_error` для понад 4 послідовностей або нерядкових чи порожніх елементів. |

Усі поля вибірки та обмеження токенів передаються через той самий канал параметрів потоку агента й пересилаються за можливості:

- Обмеження токенів: назву поля в протоколі визначає транспорт провайдера: `max_completion_tokens` для кінцевих точок сімейства OpenAI, `max_tokens` для провайдерів, які приймають лише застарілу назву (Mistral, Chutes).
- `stop` зіставляється з полем зупинки транспорту: `stop` для серверних частин Chat Completions, `stop_sequences` для Anthropic. OpenAI Responses API не має параметра зупинки, тому `stop` не застосовується до моделей на основі Responses.
- Серверна частина Codex Responses на основі ChatGPT використовує фіксовані серверні параметри вибірки та видаляє `temperature`/`top_p` (разом із `max_output_tokens`, `metadata`, `prompt_cache_retention`, `service_tier`) до того, як запит досягне цієї серверної частини.

### Непідтримувані варіанти

Повертає `400 invalid_request_error` для:

- `tools`, що не є масивом, елементів інструментів, що не є функціями, або відсутнього `tool.function.name`
- варіантів `tool_choice`, як-от `allowed_tools` і `custom`
- значень `tool_choice.function.name`, які не відповідають наданому інструменту

Для `tool_choice: "required"` і `tool_choice` із зафіксованою функцією кінцева точка звужує доступний набір клієнтських функціональних інструментів, указує середовищу виконання викликати клієнтський інструмент перед відповіддю та повертає помилку, якщо відповідь агента не містить відповідного структурованого виклику клієнтського інструмента. Це стосується переданого викликачем HTTP-списку `tools`, а не всіх внутрішніх інструментів агента OpenClaw.

### Формат непотокової відповіді інструмента

Коли агент викликає інструменти, відповідь містить:

- `choices[0].finish_reason = "tool_calls"`
- елементи `choices[0].message.tool_calls[]` із `id`, `type: "function"`, `function.name`, `function.arguments` (рядок JSON)
- Коментар асистента перед викликом інструмента в `choices[0].message.content` (може бути порожнім)

### Формат потокової відповіді інструмента

Коли `stream: true`, виклики інструментів надходять як послідовні фрагменти SSE: початковий фрагмент ролі асистента, необов’язкові фрагменти коментаря асистента, один або кілька фрагментів `delta.tool_calls`, що містять ідентифікатор інструмента й частини аргументів, а потім завершальний фрагмент із `finish_reason: "tool_calls"` і `data: [DONE]`.

Якщо `stream_options.include_usage=true`, перед `[DONE]` надсилається завершальний фрагмент із даними про використання.

### Цикл наступних запитів інструмента

Після отримання `tool_calls` виконайте запитані функції та надішліть наступний запит, який містить попереднє повідомлення асистента з викликами інструментів і одне або кілька повідомлень із `role: "tool"` та відповідним `tool_call_id`. Це продовжує той самий цикл міркування агента для формування остаточної відповіді.

## Потокове передавання (SSE)

Установіть `stream: true`, щоб отримувати події, надіслані сервером:

- `Content-Type: text/event-stream`
- Кожен рядок події має формат `data: <json>`
- Потік завершується рядком `data: [DONE]`

## Швидке налаштування Open WebUI

- Базова URL-адреса: `http://127.0.0.1:18789/v1`
- Базова URL-адреса Docker у macOS: `http://host.docker.internal:18789/v1`
- Ключ API: ваш токен-носій Gateway
- Модель: `openclaw/default`

Очікувана поведінка: `GET /v1/models` виводить `openclaw/default`, а Open WebUI використовує його як ідентифікатор моделі чату. Для конкретного серверного провайдера/моделі встановіть звичайну модель агента за замовчуванням або надішліть `x-openclaw-model` (викликач зі спільним секретом або викликач із підтвердженою ідентичністю та `operator.admin`).

Швидка базова перевірка:

```bash
curl -sS http://127.0.0.1:18789/v1/models \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

Якщо запит повертає `openclaw/default`, більшість конфігурацій Open WebUI зможуть підключитися з тією самою базовою URL-адресою та токеном.

## Приклади

Стабільний сеанс для однієї розмови в застосунку:

```bash
curl -sS http://127.0.0.1:18789/v1/chat/completions \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "openclaw/default",
    "user": "conv:YOUR_CONVERSATION_ID",
    "messages": [{"role":"user","content":"Summarize my tasks for today"}]
  }'
```

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

Без потокового передавання:

```bash
curl -sS http://127.0.0.1:18789/v1/chat/completions \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "openclaw/default",
    "messages": [{"role":"user","content":"hi"}]
  }'
```

Потокове передавання:

```bash
curl -N http://127.0.0.1:18789/v1/chat/completions \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'x-openclaw-model: openai/gpt-5.4' \
  -d '{
    "model": "openclaw/research",
    "stream": true,
    "messages": [{"role":"user","content":"hi"}]
  }'
```

Переглянути список моделей:

```bash
curl -sS http://127.0.0.1:18789/v1/models \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

Отримати одну модель:

```bash
curl -sS http://127.0.0.1:18789/v1/models/openclaw%2Fdefault \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

Створити векторні подання:

```bash
curl -sS http://127.0.0.1:18789/v1/embeddings \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'x-openclaw-model: openai/text-embedding-3-small' \
  -d '{
    "model": "openclaw/default",
    "input": ["alpha", "beta"]
  }'
```

`/v1/embeddings` підтримує `input` як рядок або масив рядків.

## Пов’язані матеріали

- [Довідник із конфігурації](/uk/gateway/configuration-reference)
- [Області доступу оператора](/uk/gateway/operator-scopes)
- [OpenAI](/uk/providers/openai)
