Завершення чату OpenAI

OpenClaw Gateway може обслуговувати невелику OpenAI-сумісну кінцеву точку Chat Completions.

Цю кінцеву точку вимкнено за замовчуванням. Спершу увімкніть її в конфігурації.

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

Коли OpenAI-сумісну HTTP-поверхню Gateway увімкнено, вона також обслуговує:

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

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

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

Використовує конфігурацію автентифікації Gateway.

Поширені шляхи HTTP-автентифікації:

• автентифікація зі спільним секретом (gateway.auth.mode="token" або "password"): Authorization: Bearer <token-or-password>
• довірена HTTP-автентифікація з передаванням ідентичності (gateway.auth.mode="trusted-proxy"): маршрутизуйте через налаштований identity-aware проксі й дозвольте йому вставити потрібні заголовки ідентичності
• відкрита автентифікація для приватного ingress (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-запит має надходити з налаштованого довіреного джерела проксі; loopback-проксі на тому самому хості потребують явного gateway.auth.trustedProxy.allowLoopback = true.
• Якщо налаштовано gateway.auth.rateLimit і стається забагато помилок автентифікації, кінцева точка повертає 429 з Retry-After.

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

Розглядайте цю кінцеву точку як поверхню з повним операторським доступом до екземпляра Gateway.

• HTTP bearer-автентифікація тут не є вузькою моделлю областей дії для окремих користувачів.
• Дійсний токен/пароль Gateway для цієї кінцевої точки слід розглядати як облікові дані власника/оператора.
• Запити проходять через той самий агентський шлях control-plane, що й довірені операторські дії.
• Для цієї кінцевої точки немає окремої межі інструментів для не-власника/окремого користувача; щойно викликач проходить тут автентифікацію Gateway, OpenClaw вважає цього викликача довіреним оператором для цього Gateway.
• Для режимів автентифікації зі спільним секретом (token і password) кінцева точка відновлює звичайні повні операторські стандартні значення, навіть якщо викликач надсилає вужчий заголовок x-openclaw-scopes.
• Довірені HTTP-режими з передаванням ідентичності (наприклад, автентифікація через довірений проксі або gateway.auth.mode="none") враховують x-openclaw-scopes, коли він присутній, а інакше повертаються до звичайного стандартного набору операторських областей дії.
• Якщо політика цільового агента дозволяє чутливі інструменти, ця кінцева точка може їх використовувати.
• Тримайте цю кінцеву точку лише на loopback/tailnet/приватному 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" на приватному ingress)
  • автентифікують певну зовнішню довірену ідентичність або межу розгортання
  • враховують x-openclaw-scopes, коли заголовок присутній
  • повертаються до звичайного стандартного набору операторських областей дії, коли заголовок відсутній
  • втрачають семантику власника лише тоді, коли викликач явно звужує області дії та пропускає operator.admin

Див. Безпека і Віддалений доступ.

# Контракт моделі, де агент на першому місці

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

• model: "openclaw" маршрутизує до налаштованого стандартного агента.
• model: "openclaw/default" також маршрутизує до налаштованого стандартного агента.
• model: "openclaw/<agentId>" маршрутизує до конкретного агента.

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

• x-openclaw-model: <provider/model-or-bare-id> перевизначає бекенд-модель для вибраного агента.
• x-openclaw-agent-id: <agentId> залишається підтримуваним як сумісне перевизначення.
• x-openclaw-session-key: <sessionKey> повністю керує маршрутизацією сеансу.
• x-openclaw-message-channel: <channel> задає синтетичний контекст ingress-каналу для підказок і політик, що враховують канал.

Сумісні псевдоніми все ще приймаються:

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

# Увімкнення кінцевої точки

Установіть gateway.http.endpoints.chatCompletions.enabled у true:

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

# Вимкнення кінцевої точки

Установіть gateway.http.endpoints.chatCompletions.enabled у false:

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

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

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

Якщо запит містить рядок OpenAI user, Gateway виводить із нього стабільний ключ сеансу, тож повторні виклики можуть спільно використовувати сеанс агента.

# Чому ця поверхня важлива

Це найефективніший набір сумісності для self-hosted фронтендів та інструментів:

• Більшість налаштувань Open WebUI, LobeChat і LibreChat очікують /v1/models.
• Багато RAG-систем очікують /v1/embeddings.
• Наявні чат-клієнти OpenAI зазвичай можуть почати з /v1/chat/completions.
• Більш agent-native клієнти дедалі частіше віддають перевагу /v1/responses.

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

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

Установіть stream: true, щоб отримувати Server-Sent Events (SSE):

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

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

Для базового підключення 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 чат-моделі
• Якщо вам потрібен конкретний бекенд-провайдер/модель для цього агента, установіть звичайну стандартну модель агента або надішліть x-openclaw-model

Швидка smoke-перевірка:

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",
    "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'

Створити embeddings:

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 працює в різних середовищах.
• Перевизначення бекенд-провайдера/моделі належать до x-openclaw-model, а не до поля OpenAI model.
• /v1/embeddings підтримує input як рядок або масив рядків.

# Пов’язане

• Довідник конфігурації
• OpenAI