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

​

Коли використовувати цю кінцеву точку

• Надавайте перевагу цьому замість додавання нового вбудованого каналу, коли ваша інтеграція є просто ще однією операторською/клієнтською поверхнею для того самого gateway.
• Для нативних мобільних клієнтів, які підключаються напряму до віддаленого gateway, надавайте перевагу WebChat або Gateway Protocol і реалізуйте потік paired-device bootstrap/device-token, щоб пристрою не був потрібен спільний HTTP-токен/пароль.
• Натомість створіть Plugin каналу, коли інтегруєте зовнішню мережу повідомлень із власними користувачами, кімнатами, доставкою Webhook або вихідним транспортом. Див. Створення Plugin.

​

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

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

• x-openclaw-model: <provider/model-or-bare-id> перевизначає бекенд-модель для вибраного агента. Викликачі зі спільним секретом 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.
• Клієнти, більш нативні для агентів, дедалі частіше надають перевагу /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: число; ліміт на виклик для загальної кількості токенів завершення (включно з reasoning-токенами). Поточна назва поля OpenAI Chat Completions; бажана, коли надсилаються і max_completion_tokens, і max_tokens.
• max_tokens: число; застарілий псевдонім, прийнятий для зворотної сумісності. Ігнорується, коли також присутній 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 стоп-послідовності, що передаються upstream-провайдеру через канал stream-param агента. Повертає 400 invalid_request_error для понад 4 послідовностей або нерядкових/порожніх елементів.

​

Непідтримувані варіанти

• tools, що не є масивом
• записи інструментів, що не є function
• відсутній 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)

​

Форма відповіді інструмента зі стримінгом

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

​

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

• попереднє повідомлення assistant із викликом інструмента
• одне або кілька повідомлень 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 від викликача зі shared-secret чи викликача з ідентичністю та 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