Чат-завершения OpenAI

Gateway может предоставлять небольшой интерфейс Chat Completions, совместимый с OpenAI. Он по умолчанию отключен.

После включения все перечисленные ниже конечные точки обслуживаются на том же порту, что и Gateway (мультиплексирование WS + HTTP):

Запросы выполняются как обычный запуск агента Gateway (по тому же пути выполнения кода, что и openclaw agent), поэтому маршрутизация, разрешения и конфигурация соответствуют вашему Gateway.

Включение конечной точки

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

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

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

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

• Действительный токен/пароль Gateway для этой конечной точки эквивалентен учетным данным владельца/оператора, а не узкой области доступа отдельного пользователя.
• Запросы проходят по тому же пути агента плоскости управления, что и доверенные действия оператора, поэтому, если политика целевого агента разрешает чувствительные инструменты, эта конечная точка может их использовать.
• Оставляйте ее доступной только через loopback-интерфейс, tailnet или частную точку входа. Не предоставляйте к ней доступ из общедоступного интернета.

Матрица аутентификации:

См. Операторские области доступа, Безопасность и Удаленный доступ.

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

Используется конфигурация аутентификации Gateway (подробности об этом режиме см. в разделе Аутентификация через доверенный прокси):

Примечания:

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

Когда использовать эту конечную точку

• Предпочитайте ее добавлению нового встроенного канала, если ваша интеграция представляет собой лишь еще один операторский/клиентский интерфейс для того же Gateway.
• Для нативных мобильных клиентов, напрямую подключающихся к удаленному Gateway, предпочитайте WebChat или протокол Gateway с начальной настройкой сопряженного устройства и потоком токенов устройства, чтобы устройству не требовался общий HTTP-токен/пароль.
• Вместо этого создайте плагин канала, если интегрируете внешнюю сеть обмена сообщениями с собственными пользователями, комнатами, доставкой через Webhook или исходящим транспортом. См. Создание плагинов.

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

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

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

/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:

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

Значения по умолчанию, если параметры не указаны:

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

Примечание по безопасности: добавление имени хоста в список разрешённых не отменяет блокировку частных/внутренних IP-адресов. Для Gateway, доступных из интернета, применяйте средства контроля исходящего сетевого трафика в дополнение к защите на уровне приложения. См. раздел Безопасность.

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

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

Поддерживаемые поля запроса

Все поля семплирования и ограничения токенов передаются через один и тот же канал потоковых параметров агента и пересылаются по возможности:

• Ограничение токенов: имя поля в протоколе выбирается транспортом провайдера: 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).

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

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

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

Примеры

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

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 в последующих вызовах для этого диалога, чтобы продолжить тот же сеанс агента.

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

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":"привет"}]  }'

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

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":"привет"}]  }'

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

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

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

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

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

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 в виде строки или массива строк.

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

• Справочник по конфигурации
• Области доступа оператора
• OpenAI