Завершення чату 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"): маршрутизуйте через налаштований проксі з підтримкою ідентичності й дозвольте йому вставити потрібні заголовки ідентичності
• відкрита автентифікація для приватного входу (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.

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

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

• 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

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

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

Використовуйте /v1/chat/completions, коли інтегруєте інструменти або довірений бекенд на боці застосунку з наявним gateway і можете безпечно зберігати операторські облікові дані gateway.

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

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

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

• 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: true },      },    },  },}

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

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

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

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

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

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

Для користувацьких застосунків найбезпечніше за замовчуванням повторно використовувати те саме значення user для кожної гілки розмови. Уникайте ідентифікаторів рівня облікового запису, якщо ви явно не хочете, щоб кілька розмов або пристроїв спільно використовували одну сесію OpenClaw. Використовуйте x-openclaw-session-key лише тоді, коли вам потрібен явний контроль маршрутизації між кількома клієнтами або гілками, і вибирайте ключі, що належать застосунку та не починаються із зарезервованих внутрішніх просторів імен, як-от subagent:, cron: або acp:.

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

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

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

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

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

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

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

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

/v1/chat/completions підтримує підмножину function-tool, сумісну з поширеними клієнтами 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: число; ліміт на виклик для загальної кількості токенів завершення (включно з 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 послідовностей або нерядкових/порожніх елементів.

Коли задано будь-яке поле обмеження токенів, значення передається upstream-провайдеру через канал stream-param агента. Фактичну назву wire-поля, яку надсилають upstream-провайдеру, вибирає транспорт провайдера: max_completion_tokens для endpoint-ів сімейства OpenAI і max_tokens для провайдерів, які приймають лише застарілу назву (наприклад, Mistral і Chutes). Поля семплінгу (temperature, top_p, frequency_penalty, presence_penalty, seed) проходять тим самим каналом stream-param; backend Codex Responses на основі ChatGPT вилучає їх на боці сервера, оскільки використовує фіксований семплінг. stop також передається каналом stream-param і зіставляється з полем stop транспорту (stop для backend-ів Chat Completions, stop_sequences для Anthropic); OpenAI Responses API не має параметра stop, тому stop не застосовується до моделей на основі Responses.

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

Endpoint повертає 400 invalid_request_error для непідтримуваних варіантів інструментів, зокрема:

• tools, що не є масивом
• записи інструментів, що не є function
• відсутній tool.function.name
• варіанти tool_choice, як-от allowed_tools і custom
• значення tool_choice.function.name, які не відповідають наданим tools

Для tool_choice: "required" і прив’язаного до function tool_choice endpoint звужує відкритий клієнту набір function-tool, наказує runtime викликати клієнтський інструмент перед відповіддю та повертає помилку, якщо відповідь агента не містить відповідного структурованого виклику клієнтського інструмента. Цей контракт застосовується до наданого викликачем HTTP-списку tools, а не до кожного внутрішнього інструмента агента OpenClaw.

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

Коли агент вирішує викликати інструменти, відповідь використовує:

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

Коментар assistant перед викликом інструмента повертається в choices[0].message.content (можливо, порожньому).

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

Коли stream: true, виклики інструментів надсилаються як інкрементальні SSE-фрагменти:

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

Якщо stream_options.include_usage=true, кінцевий фрагмент usage надсилається перед [DONE].

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

Після отримання tool_calls клієнт має виконати запитані function(s) і надіслати подальший запит, який містить:

• попереднє повідомлення assistant із викликом інструмента
• одне або кілька повідомлень role: "tool" з відповідним tool_call_id

Це дає змогу запуску агента Gateway продовжити той самий цикл міркування та створити фінальну відповідь assistant.

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

Швидка 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",    "user": "conv:YOUR_CONVERSATION_ID",    "messages": [{"role":"user","content":"Summarize my tasks for today"}]  }'

Повторно використовуйте те саме значення 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":"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 працює в різних середовищах.
• Перевизначення backend-провайдера/моделі мають бути в x-openclaw-model, а не в полі OpenAI model. На HTTP-шляхах автентифікації з ідентичністю цей заголовок потребує operator.admin.
• /v1/embeddings підтримує input як рядок або масив рядків.

Пов’язане

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