API OpenResponses

Gateway może udostępniać zgodny z OpenResponses punkt końcowy POST /v1/responses. Jest on domyślnie wyłączony i współdzieli port z Gateway (multipleksowanie WS + HTTP): http://<gateway-host>:<port>/v1/responses.

Żądania są wykonywane jak zwykłe uruchomienie agenta Gateway (tą samą ścieżką kodu co openclaw agent), więc routing, uprawnienia i konfiguracja odpowiadają ustawieniom Gateway.

Włącz lub wyłącz tę funkcję za pomocą gateway.http.endpoints.responses.enabled. Po włączeniu ta sama warstwa zgodności udostępnia również GET /v1/models, GET /v1/models/{id}, POST /v1/embeddings i POST /v1/chat/completions.

Uwierzytelnianie, bezpieczeństwo i routing

Działanie jest zgodne z opisem w sekcji OpenAI Chat Completions:

• Ścieżka uwierzytelniania odpowiada gateway.auth.mode: tryb wspólnego sekretu (token/password) używa Authorization: Bearer <token-or-password>; tryb zaufanego serwera proxy używa nagłówków proxy uwzględniających tożsamość (serwery proxy działające na tym samym hoście w trybie local loopback wymagają gateway.auth.trustedProxy.allowLoopback = true, a gdy nie ma nagłówka Forwarded/X-Forwarded-*/X-Real-IP, dostępny jest bezpośredni mechanizm rezerwowy na tym samym hoście przez gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD); tryb none przy prywatnym ruchu przychodzącym nie wymaga nagłówka uwierzytelniania. Zobacz Uwierzytelnianie przez zaufany serwer proxy.
• Traktuj ten punkt końcowy jako pełny dostęp operatora do instancji Gateway.
• Tryby uwierzytelniania wspólnym sekretem ignorują węższy zakres zadeklarowany przez token okaziciela w x-openclaw-scopes i przywracają pełny domyślny zestaw zakresów operatora: operator.admin, operator.approvals, operator.pairing, operator.read, operator.talk.secrets, operator.write. Tury czatu w tym punkcie końcowym są traktowane jako tury nadawcy będącego właścicielem.
• Tryby HTTP przekazujące zaufaną tożsamość (zaufany serwer proxy lub gateway.auth.mode="none") respektują x-openclaw-scopes, jeśli jest obecny, a w przeciwnym razie używają domyślnego zestawu zakresów operatora. Semantyka właściciela zostaje utracona tylko wtedy, gdy wywołujący jawnie zawęzi zakresy i pominie operator.admin.
• Wybieraj agentów za pomocą model: "openclaw", "openclaw/default", "openclaw/<agentId>" lub nagłówka x-openclaw-agent-id.
• Użyj x-openclaw-model, aby zastąpić model zaplecza wybranego agenta (w ścieżkach uwierzytelniania przekazujących tożsamość wymaga operator.admin).
• Użyj x-openclaw-session-key do jawnego routingu sesji (wartość zostanie odrzucona z błędem 400 invalid_request_error, jeśli używa zastrzeżonej przestrzeni nazw: subagent:, cron:, acp:).
• Użyj x-openclaw-message-channel, aby ustawić kontekst syntetycznego kanału ruchu przychodzącego inny niż domyślny.

Kanoniczne wyjaśnienie modeli docelowych agentów, openclaw/default, przekazywania osadzeń i zastępowania modelu zaplecza zawiera sekcja OpenAI Chat Completions.

Zobacz Zakresy operatora i Bezpieczeństwo.

Działanie sesji

Domyślnie punkt końcowy jest bezstanowy dla każdego żądania (przy każdym wywołaniu generowany jest nowy klucz sesji).

Jeśli żądanie zawiera ciąg OpenResponses user, Gateway wyprowadza z niego stabilny klucz sesji, dzięki czemu powtarzane wywołania mogą współdzielić sesję agenta.

previous_response_id ponownie wykorzystuje sesję wcześniejszej odpowiedzi, jeśli żądanie pozostaje w tym samym zakresie agenta, użytkownika i żądanej sesji (dopasowanie według podmiotu uwierzytelniania, identyfikatora agenta i x-openclaw-session-key).

Struktura żądania

Elementy (input)

message

Role: system, developer, user, assistant.

• system i developer są dołączane do monitu systemowego.
• Najnowszy element user lub function_call_output staje się „bieżącą wiadomością”.
• Wcześniejsze wiadomości użytkownika i asystenta są dołączane jako historia zapewniająca kontekst.

function_call_output (narzędzia działające w turach)

Odeślij wyniki narzędzi do modelu:

{  "type": "function_call_output",  "call_id": "call_123",  "output": "{\"temperature\": \"72F\"}"}

reasoning i item_reference

Akceptowane w celu zachowania zgodności ze schematem, ale ignorowane podczas tworzenia monitu.

Narzędzia (narzędzia funkcyjne po stronie klienta)

Przekaż narzędzia za pomocą tools: [{ type: "function", name, description?, parameters? }].

Jeśli agent wywoła narzędzie, odpowiedź zwróci element wyjściowy function_call. Aby kontynuować turę, wyślij kolejne żądanie z function_call_output.

W przypadku tool_choice: "required" oraz tool_choice przypiętego do funkcji punkt końcowy zawęża udostępniony zestaw funkcyjnych narzędzi klienta, nakazuje środowisku wykonawczemu wywołanie narzędzia klienta przed udzieleniem odpowiedzi i odrzuca turę, jeśli nie zawiera ona pasującego ustrukturyzowanego wywołania narzędzia klienta, zgodnie z kontraktem /v1/chat/completions. Żądania niestrumieniowe zwracają 502 z błędem api_error; żądania strumieniowe emitują zdarzenie response.failed.

Obrazy (input_image)

Obsługuje źródła base64 lub adresy URL:

{  "type": "input_image",  "source": { "type": "url", "url": "https://example.com/image.png" }}

Dozwolone typy MIME (domyślnie): image/jpeg, image/png, image/gif, image/webp, image/heic, image/heif. Maksymalny rozmiar (domyślnie): 10 MB.

Pliki (input_file)

Obsługuje źródła base64 lub adresy URL:

{  "type": "input_file",  "source": {    "type": "base64",    "media_type": "text/plain",    "data": "SGVsbG8gV29ybGQh",    "filename": "hello.txt"  }}

Dozwolone typy MIME (domyślnie): text/plain, text/markdown, text/html, text/csv, application/json, application/pdf. Maksymalny rozmiar (domyślnie): 5 MB.

Bieżące działanie:

• Zawartość pliku jest dekodowana i dodawana do monitu systemowego, a nie do wiadomości użytkownika, dzięki czemu pozostaje tymczasowa (nie jest utrwalana w historii sesji).
• Zdekodowany tekst pliku jest opakowywany jako niezaufana zawartość zewnętrzna przed dodaniem, dzięki czemu bajty pliku są traktowane jako dane, a nie zaufane instrukcje. Wstrzyknięty blok używa jawnych znaczników granic (<<&lt;EXTERNAL_UNTRUSTED_CONTENT id=&quot;...&quot;&gt;>> / <<&lt;END_EXTERNAL_UNTRUSTED_CONTENT id=&quot;...&quot;&gt;>>) oraz wiersza metadanych Source: External. Celowo pomija długi baner SECURITY NOTICE:, aby oszczędzić budżet monitu; znaczniki granic i metadane nadal obowiązują.
• Pliki PDF są najpierw analizowane w celu wyodrębnienia tekstu. Jeśli znaleziono niewiele tekstu, pierwsze strony są rasteryzowane do obrazów i przekazywane do modelu, a wstrzyknięty blok pliku używa symbolu zastępczego [PDF content rendered to images].

Analizowanie plików PDF zapewnia dołączony Plugin document-extract, który używa clawpdf i dołączonego do niego środowiska wykonawczego PDFium WebAssembly do wyodrębniania tekstu i renderowania stron.

Domyślne ustawienia pobierania z adresów URL:

• files.allowUrl: true
• images.allowUrl: true
• maxUrlParts: 8 (łączna liczba części input_file i input_image opartych na adresach URL w jednym żądaniu)
• Żądania są zabezpieczone (rozwiązywanie DNS, blokowanie prywatnych adresów IP, limity przekierowań i limity czasu).
• Dla każdego typu danych wejściowych obsługiwane są opcjonalne listy dozwolonych nazw hostów (files.urlAllowlist, images.urlAllowlist): dokładny host ("cdn.example.com") lub wieloznaczne subdomeny ("*.assets.example.com", bez dopasowania domeny głównej). Puste lub pominięte listy dozwolonych oznaczają brak ograniczeń według nazwy hosta.
• Aby całkowicie wyłączyć pobieranie z adresów URL, ustaw files.allowUrl: false lub images.allowUrl: false, albo obie te wartości.

Limity plików i obrazów (konfiguracja)

Wartości domyślne można dostosować w gateway.http.endpoints.responses:

{  gateway: {    http: {      endpoints: {        responses: {          enabled: true,          maxBodyBytes: 20000000,          maxUrlParts: 8,          files: {            allowUrl: true,            urlAllowlist: ["cdn.example.com", "*.assets.example.com"],            allowedMimes: [              "text/plain",              "text/markdown",              "text/html",              "text/csv",              "application/json",              "application/pdf",            ],            maxBytes: 5242880,            maxChars: 60000,            maxRedirects: 3,            timeoutMs: 10000,            pdf: {              maxPages: 4,              maxPixels: 4000000,              minTextChars: 200,            },          },          images: {            allowUrl: true,            urlAllowlist: ["images.example.com"],            allowedMimes: [              "image/jpeg",              "image/png",              "image/gif",              "image/webp",              "image/heic",              "image/heif",            ],            maxBytes: 10485760,            maxRedirects: 3,            timeoutMs: 10000,          },        },      },    },  },}

Wartości domyślne w przypadku pominięcia:

Źródła input_image w formatach HEIC/HEIF są normalizowane do JPEG przed przekazaniem dostawcy przez współdzielony procesor obrazów OpenClaw (Rastermill), który w przypadku formatów wymagających obsługi zewnętrznych kodeków używa rezerwowo konwertera systemowego (sips, ImageMagick, GraphicsMagick lub ffmpeg).

Uwaga dotycząca bezpieczeństwa: listy dozwolonych adresów URL są egzekwowane przed pobraniem i na kolejnych etapach przekierowań. Dodanie nazwy hosta do listy dozwolonych nie omija blokowania prywatnych ani wewnętrznych adresów IP. W przypadku instancji Gateway dostępnych z Internetu oprócz zabezpieczeń na poziomie aplikacji zastosuj kontrolę wychodzącego ruchu sieciowego. Zobacz Bezpieczeństwo.

Strumieniowanie (SSE)

Ustaw stream: true, aby odbierać zdarzenia wysyłane przez serwer:

• Content-Type: text/event-stream
• Każdy wiersz zdarzenia ma postać event: <type> i data: <json>
• Strumień kończy się wpisem data: [DONE]

Obecnie emitowane typy zdarzeń: response.created, response.in_progress, response.output_item.added, response.content_part.added, response.output_text.delta, response.output_text.done, response.content_part.done, response.output_item.done, response.completed, response.failed (w przypadku błędu).

Użycie

Pole usage jest wypełniane, gdy bazowy dostawca raportuje liczbę tokenów. OpenClaw normalizuje typowe aliasy w stylu OpenAI, zanim te liczniki trafią do podrzędnych interfejsów stanu i sesji, w tym input_tokens / output_tokens oraz prompt_tokens / completion_tokens.

Błędy

Błędy używają obiektu JSON w postaci:

{ "error": { "message": "...", "type": "invalid_request_error" } }

Typowe przypadki: 400 nieprawidłowa treść żądania, 401 brakujące lub nieprawidłowe uwierzytelnienie, 403 brak zakresu operatora, 405 nieprawidłowa metoda, 429 zbyt wiele nieudanych prób uwierzytelnienia (z nagłówkiem Retry-After).

Przykłady

Bez strumieniowania:

curl -sS http://127.0.0.1:18789/v1/responses \  -H 'Authorization: Bearer YOUR_TOKEN' \  -H 'Content-Type: application/json' \  -H 'x-openclaw-agent-id: main' \  -d '{    "model": "openclaw",    "input": "hi"  }'

Ze strumieniowaniem:

curl -N http://127.0.0.1:18789/v1/responses \  -H 'Authorization: Bearer YOUR_TOKEN' \  -H 'Content-Type: application/json' \  -H 'x-openclaw-agent-id: main' \  -d '{    "model": "openclaw",    "stream": true,    "input": "hi"  }'

Powiązane

• Uzupełnienia czatu OpenAI
• Zakresy operatora
• OpenAI