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

Gateway може надавати невелику поверхню Chat Completions, сумісну з OpenAI. Вона вимкнена за замовчуванням.

Після ввімкнення всі наведені нижче ендпоїнти працюють на тому самому порту, що й Gateway (мультиплексування WS + HTTP):

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

Увімкнення ендпоїнта

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

Щоб вимкнути, установіть enabled: false (або не вказуйте цей параметр).

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

Вважайте цей ендпоїнт таким, що надає повний операторський доступ до екземпляра Gateway:

• Чинний токен або пароль Gateway для цього ендпоїнта еквівалентний обліковим даним власника чи оператора, а не вузькій області доступу окремого користувача.
• Запити проходять тим самим шляхом агента площини керування, що й довірені дії оператора, тому, якщо політика цільового агента дозволяє чутливі інструменти, цей ендпоїнт може їх використовувати.
• Залишайте його доступним лише через local 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-токен або пароль.
• Натомість створіть Plugin каналу, якщо інтегруєте зовнішню мережу обміну повідомленнями з власними користувачами, кімнатами, доставленням через 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, щоб отримувати події, надіслані сервером:

• 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: ваш токен-носій 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":"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'

Створити векторні подання:

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/embeddings підтримує input як рядок або масив рядків.

Пов’язані матеріали

• Довідник із конфігурації
• Області доступу оператора
• OpenAI