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

• POST /v1/chat/completions
• Тот же порт, что и у Gateway (мультиплексирование WS + HTTP): http://<gateway-host>:<port>/v1/chat/completions

• GET /v1/models
• GET /v1/models/{id}
• POST /v1/embeddings
• POST /v1/responses

​

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

• аутентификация с общим секретом (gateway.auth.mode="token" или "password"): Authorization: Bearer <token-or-password>
• доверенная HTTP-аутентификация с идентичностью (gateway.auth.mode="trusted-proxy"): направьте через настроенный прокси с поддержкой идентичности и позвольте ему внедрить необходимые заголовки идентичности
• открытая аутентификация для приватного входа (gateway.auth.mode="none"): заголовок аутентификации не требуется

• Когда gateway.auth.mode="token", используйте gateway.auth.token (или OPENCLAW_GATEWAY_TOKEN).
• Когда gateway.auth.mode="password", используйте gateway.auth.password (или OPENCLAW_GATEWAY_PASSWORD).
• Когда gateway.auth.mode="trusted-proxy", HTTP-запрос должен поступать из настроенного доверенного источника прокси; same-host loopback proxies требуют явного gateway.auth.trustedProxy.allowLoopback = true.
• Внутренние вызывающие стороны на том же хосте, которые обходят прокси, могут использовать gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD как локальный прямой резервный вариант. Любые свидетельства в заголовках Forwarded, X-Forwarded-* или X-Real-IP вместо этого оставляют запрос на пути trusted-proxy.
• Если настроен gateway.auth.rateLimit и происходит слишком много неудачных попыток аутентификации, эндпоинт возвращает 429 с Retry-After.

​

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

• HTTP bearer auth здесь не является узкой моделью областей действия для каждого пользователя.
• Действительный токен/пароль Gateway для этого эндпоинта следует считать учетными данными владельца/оператора.
• Запросы выполняются через тот же агентский путь control-plane, что и доверенные операторские действия.
• На этом эндпоинте нет отдельной инструментальной границы для не-владельцев/отдельных пользователей; как только вызывающая сторона проходит здесь аутентификацию Gateway, OpenClaw считает эту вызывающую сторону доверенным оператором для этого Gateway.
• Для режимов аутентификации с общим секретом (token и password) эндпоинт восстанавливает обычные полные операторские значения по умолчанию, даже если вызывающая сторона отправляет более узкий заголовок x-openclaw-scopes.
• Доверенные HTTP-режимы с идентичностью (например, аутентификация через доверенный прокси или gateway.auth.mode="none") учитывают x-openclaw-scopes, когда он присутствует, и иначе возвращаются к обычному набору операторских областей по умолчанию.
• Если политика целевого агента разрешает чувствительные инструменты, этот эндпоинт может их использовать.
• Держите этот эндпоинт только на loopback/tailnet/private ingress; не открывайте его напрямую в публичный интернет.

• 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
  • требуют operator.admin для элементов управления запросом уровня владельца, таких как x-openclaw-model

​

Когда использовать этот эндпоинт

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

​

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

• model: "openclaw" направляет к настроенному агенту по умолчанию.
• model: "openclaw/default" также направляет к настроенному агенту по умолчанию.
• model: "openclaw/<agentId>" направляет к конкретному агенту.

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

• model: "openclaw:<agentId>"
• model: "agent:<agentId>"

​

Включение эндпоинта

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

​

Отключение эндпоинта

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

​

Поведение сессии

​

Почему эта поверхность важна

• Большинство установок Open WebUI, LobeChat и LibreChat ожидают /v1/models.
• Многие RAG-системы ожидают /v1/embeddings.
• Существующие клиенты чата OpenAI обычно могут начать с /v1/chat/completions.
• Более agent-native клиенты все чаще предпочитают /v1/responses.

​

Список моделей и маршрутизация агентов

​

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

• Content-Type: text/event-stream
• Каждая строка события имеет вид data: <json>
• Поток завершается data: [DONE]

​

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

​

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

• tools: массив { "type": "function", "function": { ... } }
• tool_choice: "auto", "none", "required" или { "type": "function", "function": { "name": "..." } }
• messages[*].role: "tool" последующие ходы
• messages[*].tool_call_id для привязки результатов инструмента к предыдущему вызову инструмента
• max_completion_tokens: число; лимит на общий объем токенов completion для каждого вызова (включая reasoning-токены). Текущее имя поля OpenAI Chat Completions; предпочтительно, когда отправлены и max_completion_tokens, и max_tokens.
• max_tokens: число; legacy-псевдоним, принимаемый для обратной совместимости. Игнорируется, когда также присутствует max_completion_tokens.
• temperature: число; best-effort температура сэмплирования, передаваемая upstream-провайдеру через канал stream-param агента.
• top_p: число; best-effort nucleus sampling, передаваемый upstream-провайдеру через канал stream-param агента.
• frequency_penalty: число; best-effort штраф частоты, передаваемый upstream-провайдеру через канал stream-param агента. Допустимый диапазон: от -2.0 до 2.0. Возвращает 400 invalid_request_error для значений вне диапазона.
• presence_penalty: число; best-effort штраф присутствия, передаваемый upstream-провайдеру через канал stream-param агента. Допустимый диапазон: от -2.0 до 2.0. Возвращает 400 invalid_request_error для значений вне диапазона.
• seed: число (целое); best-effort seed, передаваемый upstream-провайдеру через канал stream-param агента. Возвращает 400 invalid_request_error для нецелых значений.
• stop: строка или массив до 4 строк; best-effort stop-последовательности, передаваемые upstream-провайдеру через канал stream-param агента. Возвращает 400 invalid_request_error для более чем 4 последовательностей или нестроковых/пустых элементов.

​

Неподдерживаемые варианты

• tools, не являющийся массивом
• записи инструментов, не являющиеся функциями
• отсутствующий tool.function.name
• варианты tool_choice, такие как allowed_tools и custom
• значения tool_choice.function.name, которые не совпадают с предоставленными tools

​

Форма ответа инструмента без потоковой передачи

• записи choices[0].finish_reason = "tool_calls"
• choices[0].message.tool_calls[] с:
  • id
  • type: "function"
  • function.name
  • function.arguments (строка JSON)

​

Форма ответа инструмента при потоковой передаче

• начальная delta роли ассистента
• необязательные delta комментариев ассистента
• один или несколько фрагментов delta.tool_calls, содержащих идентификатор инструмента и фрагменты аргументов
• финальный фрагмент с finish_reason: "tool_calls"
• data: [DONE]

​

Цикл продолжения после инструмента

• предыдущее сообщение ассистента с вызовом инструмента
• одно или несколько сообщений role: "tool" с соответствующим tool_call_id

​

Быстрая настройка 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 должен использовать openclaw/default как id чат-модели
• Если для этого агента нужен конкретный backend-провайдер/модель, задайте обычную модель по умолчанию агента или отправьте x-openclaw-model от вызывающей стороны с общим секретом либо от вызывающей стороны с идентификацией и operator.admin

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

​

Примеры

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"}]
  }'

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"}]
  }'

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"}]
  }'

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": ["alpha", "beta"]
  }'

• /v1/models возвращает целевые агенты OpenClaw, а не необработанные каталоги провайдеров.
• openclaw/default всегда присутствует, поэтому один стабильный id работает в разных окружениях.
• Переопределения backend-провайдера/модели должны находиться в x-openclaw-model, а не в поле OpenAI model. В HTTP-путях аутентификации с идентификацией этот заголовок требует operator.admin.
• /v1/embeddings поддерживает input как строку или массив строк.

​

Связанные материалы

• Справочник по конфигурации
• OpenAI