--- read_when: - Интеграция инструментов, рассчитанных на OpenAI Chat Completions summary: Предоставление через Gateway HTTP-эндпоинта `/v1/chat/completions`, совместимого с OpenAI title: Чат-завершения OpenAI x-i18n: generated_at: "2026-07-13T19:48:38Z" model: gpt-5.6 postprocess_version: locale-links-v1 prompt_version: 24 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 для этой конечной точки эквивалентен учетным данным владельца/оператора, а не узкой области доступа отдельного пользователя. - Запросы проходят по тому же пути агента плоскости управления, что и доверенные действия оператора, поэтому, если политика целевого агента разрешает чувствительные инструменты, эта конечная точка может их использовать. - Оставляйте ее доступной только через 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`. | См. [Операторские области доступа](/ru/gateway/operator-scopes), [Безопасность](/ru/gateway/security) и [Удаленный доступ](/ru/gateway/remote). ## Аутентификация Используется конфигурация аутентификации Gateway (подробности об этом режиме см. в разделе [Аутентификация через доверенный прокси](/ru/gateway/trusted-proxy-auth)): | Режим | Способ аутентификации | | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `gateway.auth.mode="token"` | `Authorization: Bearer `. Задается через `gateway.auth.token` или `OPENCLAW_GATEWAY_TOKEN`. | | `gateway.auth.mode="password"` | `Authorization: Bearer `. Задается через `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](/ru/web/webchat) или [протокол Gateway](/ru/gateway/protocol) с начальной настройкой сопряженного устройства и потоком токенов устройства, чтобы устройству не требовался общий HTTP-токен/пароль. - Вместо этого создайте плагин канала, если интегрируете внешнюю сеть обмена сообщениями с собственными пользователями, комнатами, доставкой через Webhook или исходящим транспортом. См. [Создание плагинов](/ru/plugins/building-plugins). ## Контракт модели с приоритетом агента OpenClaw рассматривает поле OpenAI `model` как **целевой агент**, а не как необработанный идентификатор модели провайдера. | Значение `model` | Направляется к | | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | `openclaw` | Настроенному агенту по умолчанию | | `openclaw/default` | Настроенному агенту по умолчанию (стабильный псевдоним; его можно безопасно жестко задавать, даже если фактический идентификатор агента по умолчанию различается в разных средах) | | `openclaw/` или `openclaw:` | Конкретному агенту | | `agent:` | Конкретному агенту (псевдоним для совместимости) | Необязательные заголовки запроса: | Заголовок | Эффект | | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `x-openclaw-model: ` | Переопределяет серверную модель для выбранного агента. Вызывающие стороны с общим секретом Bearer могут использовать его напрямую; вызывающим сторонам с идентификационными данными (доверенный прокси или частная точка входа без аутентификации с `x-openclaw-scopes`) требуется `operator.admin`, иначе — `403 missing scope: operator.admin`. | | `x-openclaw-agent-id: ` | Переопределение выбора агента для совместимости. | | `x-openclaw-session-key: ` | Явная маршрутизация сеанса. Отклоняется с `400 invalid_request_error`, если используется зарезервированное внутреннее пространство имен (`subagent:`, `cron:`, `acp:`). | | `x-openclaw-message-channel: ` | Задает контекст синтетического входного канала для учитывающих канал запросов/политик. | `/v1/models` перечисляет цели агентов верхнего уровня (`openclaw`, `openclaw/default`, `openclaw/`), а не серверные модели провайдеров и не субагентов; субагенты остаются частью внутренней топологии выполнения. Если не указать `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` | 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, доступных из интернета, применяйте средства контроля исходящего сетевого трафика в дополнение к защите на уровне приложения. См. раздел [Безопасность](/ru/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`, чтобы получать события Server-Sent Events: - `Content-Type: text/event-stream` - Каждая строка события имеет вид `data: ` - Поток завершается значением `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 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":"Составь сводку моих задач на сегодня"}] }' ``` Повторно используйте то же значение `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":"привет"}] }' ``` С потоковой передачей: ```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":"привет"}] }' ``` Получить список моделей: ```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": ["альфа", "бета"] }' ``` `/v1/embeddings` поддерживает `input` в виде строки или массива строк. ## Связанные разделы - [Справочник по конфигурации](/ru/gateway/configuration-reference) - [Области доступа оператора](/ru/gateway/operator-scopes) - [OpenAI](/ru/providers/openai)