OpenResponses-API

Das Gateway kann einen OpenResponses-kompatiblen Endpunkt POST /v1/responses bereitstellen. Er ist standardmäßig deaktiviert und verwendet denselben Port wie das Gateway (WS- und HTTP-Multiplexing): http://<gateway-host>:<port>/v1/responses.

Anfragen werden als normale Gateway-Agentenausführung verarbeitet (derselbe Codepfad wie bei openclaw agent), sodass Routing, Berechtigungen und Konfiguration Ihrem Gateway entsprechen.

Aktivieren oder deaktivieren Sie den Endpunkt mit gateway.http.endpoints.responses.enabled. Wenn er aktiviert ist, stellt dieselbe Kompatibilitätsschnittstelle auch GET /v1/models, GET /v1/models/{id}, POST /v1/embeddings und POST /v1/chat/completions bereit.

Authentifizierung, Sicherheit und Routing

Das Betriebsverhalten entspricht OpenAI Chat Completions:

• Der Authentifizierungspfad entspricht gateway.auth.mode: Ein gemeinsames Geheimnis (token/password) verwendet Authorization: Bearer <token-or-password>; ein vertrauenswürdiger Proxy verwendet identitätsbezogene Proxy-Header (Loopback-Proxys auf demselben Host benötigen gateway.auth.trustedProxy.allowLoopback = true, mit einem direkten Fallback auf demselben Host über gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD, wenn kein Forwarded-/X-Forwarded-*-/X-Real-IP-Header vorhanden ist); none benötigt bei privatem Eingang keinen Authentifizierungs-Header. Siehe Authentifizierung über vertrauenswürdige Proxys.
• Behandeln Sie den Endpunkt als vollständigen Operatorzugriff auf die Gateway-Instanz.
• Authentifizierungsmodi mit gemeinsamem Geheimnis ignorieren enger gefasste, per Bearer deklarierte x-openclaw-scopes und stellen den vollständigen Standardsatz an Operator-Berechtigungsbereichen wieder her: operator.admin, operator.approvals, operator.pairing, operator.read, operator.talk.secrets, operator.write. Chat-Interaktionen an diesem Endpunkt werden als Interaktionen eines Eigentümer-Absenders behandelt.
• Vertrauenswürdige identitätsführende HTTP-Modi (vertrauenswürdiger Proxy oder gateway.auth.mode="none") berücksichtigen x-openclaw-scopes, wenn dieser Header vorhanden ist, und greifen andernfalls auf den Standardsatz der Operator-Berechtigungsbereiche zurück. Die Eigentümersemantik geht nur verloren, wenn der Aufrufer die Berechtigungsbereiche ausdrücklich einschränkt und operator.admin auslässt.
• Wählen Sie Agenten mit model: "openclaw", "openclaw/default", "openclaw/<agentId>" oder dem Header x-openclaw-agent-id aus.
• Verwenden Sie x-openclaw-model, um das Backend-Modell des ausgewählten Agenten zu überschreiben (erfordert operator.admin bei identitätsführenden Authentifizierungspfaden).
• Verwenden Sie x-openclaw-session-key für explizites Sitzungs-Routing (wird mit 400 invalid_request_error abgelehnt, wenn ein reservierter Namensraum verwendet wird: subagent:, cron:, acp:).
• Verwenden Sie x-openclaw-message-channel für einen vom Standard abweichenden synthetischen Eingangskanalkontext.

Die maßgebliche Erläuterung zu Agentenzielmodellen, openclaw/default, der Durchleitung von Einbettungen und Überschreibungen von Backend-Modellen finden Sie unter OpenAI Chat Completions.

Siehe Operator-Berechtigungsbereiche und Sicherheit.

Sitzungsverhalten

Standardmäßig ist der Endpunkt für jede Anfrage zustandslos (bei jedem Aufruf wird ein neuer Sitzungsschlüssel erzeugt).

Wenn die Anfrage eine OpenResponses-user-Zeichenfolge enthält, leitet das Gateway daraus einen stabilen Sitzungsschlüssel ab, sodass wiederholte Aufrufe eine Agentensitzung gemeinsam verwenden können.

previous_response_id verwendet die Sitzung der vorherigen Antwort erneut, wenn die Anfrage im selben Agenten-/Benutzer-/angeforderten Sitzungsbereich bleibt (Abgleich anhand von Authentifizierungssubjekt, Agenten-ID und x-openclaw-session-key).

Anfragestruktur

Elemente (input)

message

Rollen: system, developer, user, assistant.

• system und developer werden an den System-Prompt angehängt.
• Das neueste user- oder function_call_output-Element wird zur „aktuellen Nachricht“.
• Frühere Benutzer-/Assistentennachrichten werden als Verlauf für den Kontext einbezogen.

function_call_output (interaktionsbasierte Werkzeuge)

Senden Sie Werkzeugergebnisse an das Modell zurück:

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

reasoning und item_reference

Werden aus Gründen der Schemakompatibilität akzeptiert, beim Erstellen des Prompts jedoch ignoriert.

Werkzeuge (clientseitige Funktionswerkzeuge)

Stellen Sie Werkzeuge mit tools: [{ type: "function", name, description?, parameters? }] bereit.

Wenn der Agent ein Werkzeug aufruft, enthält die Antwort ein function_call-Ausgabeelement. Senden Sie zum Fortsetzen der Interaktion eine Folgeanfrage mit function_call_output.

Bei tool_choice: "required" und einem auf eine Funktion festgelegten tool_choice schränkt der Endpunkt die bereitgestellte Menge clientseitiger Funktionswerkzeuge ein, weist die Laufzeit an, vor der Antwort ein clientseitiges Werkzeug aufzurufen, und lehnt die Interaktion ab, wenn sie keinen passenden strukturierten Aufruf eines clientseitigen Werkzeugs enthält. Dies entspricht dem Vertrag von /v1/chat/completions. Nicht streamende Anfragen geben 502 mit einem api_error zurück; streamende Anfragen senden ein response.failed-Ereignis.

Bilder (input_image)

Unterstützt Base64- oder URL-Quellen:

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

Zulässige MIME-Typen (Standard): image/jpeg, image/png, image/gif, image/webp, image/heic, image/heif. Maximale Größe (Standard): 10 MB.

Dateien (input_file)

Unterstützt Base64- oder URL-Quellen:

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

Zulässige MIME-Typen (Standard): text/plain, text/markdown, text/html, text/csv, application/json, application/pdf. Maximale Größe (Standard): 5 MB.

Aktuelles Verhalten:

• Der Dateiinhalt wird dekodiert und dem System-Prompt hinzugefügt, nicht der Benutzernachricht. Dadurch bleibt er flüchtig und wird nicht im Sitzungsverlauf gespeichert.
• Der dekodierte Dateitext wird vor dem Hinzufügen als nicht vertrauenswürdiger externer Inhalt eingeschlossen, sodass Dateibytes als Daten und nicht als vertrauenswürdige Anweisungen behandelt werden. Der eingefügte Block verwendet explizite Begrenzungsmarkierungen (<<&lt;EXTERNAL_UNTRUSTED_CONTENT id=&quot;...&quot;&gt;>> / <<&lt;END_EXTERNAL_UNTRUSTED_CONTENT id=&quot;...&quot;&gt;>>) und eine Metadatenzeile Source: External. Das lange Banner SECURITY NOTICE: wird absichtlich weggelassen, um das Prompt-Budget zu schonen; die Begrenzungsmarkierungen und Metadaten gelten weiterhin.
• PDFs werden zunächst auf Text analysiert. Wenn nur wenig Text gefunden wird, werden die ersten Seiten in Rasterbilder umgewandelt und an das Modell übergeben; der eingefügte Dateiblock verwendet dann den Platzhalter [PDF content rendered to images].

Die PDF-Analyse wird vom gebündelten Plugin document-extract bereitgestellt, das clawpdf und dessen mitgelieferte PDFium-WebAssembly-Laufzeit für Textextraktion und Seitendarstellung verwendet.

Standardeinstellungen für URL-Abrufe:

• files.allowUrl: true
• images.allowUrl: true
• maxUrlParts: 8 (Gesamtzahl der URL-basierten input_file- und input_image-Teile pro Anfrage)
• Anfragen werden abgesichert (DNS-Auflösung, Blockierung privater IP-Adressen, Begrenzung von Weiterleitungen, Zeitüberschreitungen).
• Optionale Hostnamen-Zulassungslisten werden pro Eingabetyp unterstützt (files.urlAllowlist, images.urlAllowlist): exakter Host ("cdn.example.com") oder Platzhalter für Subdomains ("*.assets.example.com", stimmt nicht mit der Stammdomain überein). Leere oder ausgelassene Zulassungslisten bedeuten, dass keine Einschränkung durch eine Hostnamen-Zulassungsliste gilt.
• Um URL-basierte Abrufe vollständig zu deaktivieren, setzen Sie files.allowUrl: false und/oder images.allowUrl: false.

Datei- und Bildlimits (Konfiguration)

Die Standardwerte können unter gateway.http.endpoints.responses angepasst werden:

{  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,          },        },      },    },  },}

Standardwerte bei Auslassung:

HEIC-/HEIF-input_image-Quellen werden vor der Übergabe an den Provider durch den gemeinsamen OpenClaw-Bildprozessor (Rastermill) in JPEG normalisiert. Für Formate, die externe Codec-Unterstützung benötigen, greift dieser auf einen Systemkonverter (sips, ImageMagick, GraphicsMagick oder ffmpeg) zurück.

Sicherheitshinweis: URL-Zulassungslisten werden vor dem Abruf und bei jedem Weiterleitungsschritt durchgesetzt. Die Aufnahme eines Hostnamens in die Zulassungsliste umgeht nicht die Blockierung privater oder interner IP-Adressen. Wenden Sie bei über das Internet erreichbaren Gateways zusätzlich zu den Schutzmaßnahmen auf Anwendungsebene Kontrollen für ausgehenden Netzwerkverkehr an. Siehe Sicherheit.

Streaming (SSE)

Setzen Sie stream: true, um Server-Sent Events zu empfangen:

• Content-Type: text/event-stream
• Jede Ereigniszeile hat das Format event: <type> und data: <json>
• Der Stream endet mit data: [DONE]

Derzeit ausgegebene Ereignistypen: 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 (bei einem Fehler).

Verwendung

usage wird ausgefüllt, wenn der zugrunde liegende Provider Token-Anzahlen meldet. OpenClaw normalisiert gängige Aliasnamen im OpenAI-Stil, bevor diese Zähler nachgelagerte Status- und Sitzungsoberflächen erreichen, darunter input_tokens / output_tokens und prompt_tokens / completion_tokens.

Fehler

Fehler verwenden ein JSON-Objekt wie dieses:

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

Häufige Fälle: 400 ungültiger Anfrageinhalt, 401 fehlende/ungültige Authentifizierung, 403 fehlender Operator-Berechtigungsumfang, 405 falsche Methode, 429 zu viele fehlgeschlagene Authentifizierungsversuche (mit Retry-After).

Beispiele

Ohne Streaming:

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

Mit Streaming:

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

Verwandte Themen

• OpenAI-Chatvervollständigungen
• Operator-Berechtigungsumfänge
• OpenAI