> ## 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

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 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  gateway: {
    http: {
      endpoints: {
        chatCompletions: { enabled: true },
      },
    },
  },
}
```

Чтобы отключить, задайте `enabled: false` (или не указывайте его).

## Граница безопасности (важно)

Рассматривайте эту конечную точку как предоставляющую **полный операторский доступ** к экземпляру Gateway:

* Действительный токен/пароль Gateway для этой конечной точки эквивалентен учетным данным владельца/оператора, а не узкой области доступа отдельного пользователя.
* Запросы проходят по тому же пути агента плоскости управления, что и доверенные действия оператора, поэтому, если политика целевого агента разрешает чувствительные инструменты, эта конечная точка может их использовать.
* Оставляйте ее доступной только через 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`. |

См. [Операторские области доступа](https://docs2.openclaw.ai/ru/gateway/operator-scopes.md), [Безопасность](https://docs2.openclaw.ai/ru/gateway/security.md) и [Удаленный доступ](https://docs2.openclaw.ai/ru/gateway/remote.md).

## Аутентификация

Используется конфигурация аутентификации Gateway (подробности об этом режиме см. в разделе [Аутентификация через доверенный прокси](https://docs2.openclaw.ai/ru/gateway/trusted-proxy-auth.md)):

| Режим | Способ аутентификации |
| - | - |
| `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"` | Направьте запрос через настроенный прокси с поддержкой идентификации; он добавит необходимые заголовки с идентификационными данными. Для 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](https://docs2.openclaw.ai/ru/web/webchat.md) или [протокол Gateway](https://docs2.openclaw.ai/ru/gateway/protocol.md) с начальной настройкой сопряженного устройства и потоком токенов устройства, чтобы устройству не требовался общий HTTP-токен/пароль.
* Вместо этого создайте плагин канала, если интегрируете внешнюю сеть обмена сообщениями с собственными пользователями, комнатами, доставкой через Webhook или исходящим транспортом. См. [Создание плагинов](https://docs2.openclaw.ai/ru/plugins/building-plugins.md).

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

OpenClaw рассматривает поле OpenAI `model` как **целевой агент**, а не как необработанный идентификатор модели провайдера.

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

Необязательные заголовки запроса:

| Заголовок | Эффект |
| - | - |
| `x-openclaw-model: <provider/model-or-bare-id>` | Переопределяет серверную модель для выбранного агента. Вызывающие стороны с общим секретом Bearer могут использовать его напрямую; вызывающим сторонам с идентификационными данными (доверенный прокси или частная точка входа без аутентификации с `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 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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` | 20MB |
| `maxImageParts` | 8 (максимальное количество частей `image_url`, считываемых из последнего сообщения пользователя) |
| `maxTotalImageBytes` | 20MB (суммарный объем декодированных байтов во всех частях `image_url` одного запроса) |
| `images.allowUrl` | `false` (части `image_url`, загружаемые по URL, отклоняются, если параметр не включен) |
| `images.maxBytes` | 10MB на изображение |
| `images.maxRedirects` | 3 |
| `images.timeoutMs` | 10s |

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

Примечание по безопасности: добавление имени хоста в список разрешённых не отменяет блокировку частных/внутренних IP-адресов. Для Gateway, доступных из интернета, применяйте средства контроля исходящего сетевого трафика в дополнение к защите на уровне приложения. См. раздел [Безопасность](https://docs2.openclaw.ai/ru/gateway/security.md).

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

`/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`, чтобы получать события Server-Sent Events:

* `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: ваш bearer-токен Gateway
* Модель: `openclaw/default`

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

Быстрая базовая проверка:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -sS http://127.0.0.1:18789/v1/models \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

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

## Примеры

Стабильный сеанс для одного диалога приложения:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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":"Составь сводку моих задач на сегодня"}]
  }'
```

Повторно используйте то же значение `user` в последующих вызовах для этого диалога, чтобы продолжить тот же сеанс агента.

Без потоковой передачи:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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":"привет"}]
  }'
```

С потоковой передачей:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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":"привет"}]
  }'
```

Получить список моделей:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -sS http://127.0.0.1:18789/v1/models \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

Получить одну модель:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -sS http://127.0.0.1:18789/v1/models/openclaw%2Fdefault \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

Создать векторные представления:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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": ["альфа", "бета"]
  }'
```

`/v1/embeddings` поддерживает `input` в виде строки или массива строк.

## Связанные разделы

* [Справочник по конфигурации](https://docs2.openclaw.ai/ru/gateway/configuration-reference.md)
* [Области доступа оператора](https://docs2.openclaw.ai/ru/gateway/operator-scopes.md)
* [OpenAI](https://docs2.openclaw.ai/ru/providers/openai.md)