English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisहिन्दीالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiРусскийفارسیไทย
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in PerplexityAsk questions about this page

Gateway

OpenResponses-API

OpenClaw's Gateway kann einen OpenResponses-kompatiblen Endpunkt POST /v1/responses bereitstellen.

Dieser Endpunkt ist standardmäßig deaktiviert. Aktivieren Sie ihn zuerst in der Konfiguration.

  • POST /v1/responses
  • Derselbe Port wie der Gateway (WS- + HTTP-Multiplex): http://<gateway-host>:<port>/v1/responses

Im Hintergrund werden Anfragen als normaler Gateway-Agentenlauf ausgeführt (derselbe Codepfad wie openclaw agent), daher entsprechen Routing/Berechtigungen/Konfiguration Ihrem Gateway.

Authentifizierung, Sicherheit und Routing

Das Betriebsverhalten entspricht OpenAI Chat Completions:

  • Verwenden Sie den passenden Gateway-HTTP-Authentifizierungspfad:
    • Shared-Secret-Authentifizierung (gateway.auth.mode="token" oder "password"): Authorization: Bearer <token-or-password>
    • Trusted-Proxy-Authentifizierung (gateway.auth.mode="trusted-proxy"): identitätsbewusste Proxy-Header aus einer konfigurierten vertrauenswürdigen Proxy-Quelle; Same-Host-loopback-Proxys erfordern explizit gateway.auth.trustedProxy.allowLoopback = true
    • lokaler direkter Fallback für trusted-proxy: Same-Host-Aufrufer ohne Forwarded-, X-Forwarded-*- oder X-Real-IP-Header können gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD verwenden
    • offene private-ingress-Authentifizierung (gateway.auth.mode="none"): kein Authentifizierungs-Header
  • Behandeln Sie den Endpunkt als vollständigen Operatorzugriff für die Gateway-Instanz
  • Ignorieren Sie bei Shared-Secret-Authentifizierungsmodi (token und password) engere, vom Bearer deklarierte x-openclaw-scopes-Werte und stellen Sie die normalen vollständigen Operator-Standardwerte wieder her
  • Berücksichtigen Sie bei vertrauenswürdigen identitätstragenden HTTP-Modi (zum Beispiel trusted-proxy-Authentifizierung oder gateway.auth.mode="none") x-openclaw-scopes, wenn vorhanden, und greifen Sie andernfalls auf den normalen Standardscope-Satz für Operatoren zurück
  • Wählen Sie Agenten mit model: "openclaw", model: "openclaw/default", model: "openclaw/<agentId>" oder x-openclaw-agent-id aus
  • Verwenden Sie x-openclaw-model, wenn Sie das Backend-Modell des ausgewählten Agenten überschreiben möchten
  • Verwenden Sie x-openclaw-session-key für explizites Sitzungsrouting
  • Verwenden Sie x-openclaw-message-channel, wenn Sie einen nicht standardmäßigen synthetischen Ingress-Kanalkontext möchten

Auth-Matrix:

  • gateway.auth.mode="token" oder "password" + Authorization: Bearer ...
    • weist den Besitz des gemeinsamen Gateway-Operator-Geheimnisses nach
    • ignoriert engere x-openclaw-scopes
    • stellt den vollständigen Standard-Operator-Scope-Satz wieder her: operator.admin, operator.approvals, operator.pairing, operator.read, operator.talk.secrets, operator.write
    • behandelt Chat-Turns auf diesem Endpunkt als Owner-Sender-Turns
  • Vertrauenswürdige identitätstragende HTTP-Modi (zum Beispiel trusted-proxy-Authentifizierung oder gateway.auth.mode="none" bei privatem Ingress)
    • berücksichtigen x-openclaw-scopes, wenn der Header vorhanden ist
    • greifen auf den normalen Standard-Operator-Scope-Satz zurück, wenn der Header fehlt
    • verlieren Owner-Semantik nur, wenn der Aufrufer Scopes explizit einschränkt und operator.admin auslässt

Aktivieren oder deaktivieren Sie diesen Endpunkt mit gateway.http.endpoints.responses.enabled.

Dieselbe Kompatibilitätsoberfläche enthält außerdem:

  • GET /v1/models
  • GET /v1/models/{id}
  • POST /v1/embeddings
  • POST /v1/chat/completions

Die kanonische Erklärung dazu, wie Agent-Target-Modelle, openclaw/default, Embeddings-Pass-through und Backend-Modellüberschreibungen zusammenpassen, finden Sie unter OpenAI Chat Completions und Modellliste und Agentenrouting.

Sitzungsverhalten

Standardmäßig ist der Endpunkt pro Anfrage zustandslos (bei jedem Aufruf wird ein neuer Sitzungsschlüssel generiert).

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

Anfrageform (unterstützt)

Die Anfrage folgt der OpenResponses-API mit elementbasierter Eingabe. Derzeit unterstützt:

  • input: Zeichenfolge oder Array von Elementobjekten.
  • instructions: wird in den System-Prompt zusammengeführt.
  • tools: Client-Tooldefinitionen (Funktionstools).
  • tool_choice: "auto", "none", "required" oder { "type": "function", "name": "..." }, um Client-Tools zu filtern oder zu erzwingen.
  • stream: aktiviert SSE-Streaming.
  • max_output_tokens: Best-Effort-Ausgabelimit (Provider-abhängig).
  • temperature: Best-Effort-Sampling-Temperatur, die an den Provider weitergeleitet wird. Wird vom ChatGPT-basierten Codex-Responses-Backend ignoriert, das festes serverseitiges Sampling verwendet.
  • top_p: Best-Effort-Nucleus-Sampling, das an den Provider weitergeleitet wird. Dieselbe Einschränkung für Codex Responses wie bei temperature.
  • user: stabiles Sitzungsrouting.

Akzeptiert, aber derzeit ignoriert:

  • max_tool_calls
  • reasoning
  • metadata
  • store
  • truncation

Unterstützt:

  • previous_response_id: OpenClaw verwendet die frühere Antwortsitzung erneut, wenn die Anfrage innerhalb desselben Agent-/Benutzer-/angeforderten Sitzungsbereichs bleibt.

Elemente (Eingabe)

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 Historie für den Kontext einbezogen.

function_call_output (turn-basierte Tools)

Senden Sie Toolergebnisse zurück an das Modell:

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

reasoning und item_reference

Aus Gründen der Schemakompatibilität akzeptiert, aber beim Erstellen des Prompts ignoriert.

Tools (clientseitige Funktionstools)

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

Wenn der Agent entscheidet, ein Tool aufzurufen, gibt die Antwort ein function_call-Ausgabeelement zurück. Anschließend senden Sie eine Folgeanfrage mit function_call_output, um den Turn fortzusetzen.

Bei tool_choice: "required" und funktionsgebundenem tool_choice schränkt der Endpunkt die bereitgestellte Menge clientseitiger Funktionstools ein, weist die Laufzeit an, vor der Antwort ein Client-Tool aufzurufen, und lehnt den Turn ab, wenn er keinen passenden strukturierten Client-Tool-Aufruf enthält. Dieser Vertrag gilt für die vom Aufrufer bereitgestellte HTTP-tools-Liste, nicht für jedes interne OpenClaw-Agententool. Nicht streamende Anfragen geben 502 mit einem api_error zurück; streamende Anfragen geben ein response.failed-Ereignis aus. Dies entspricht dem Vertrag von /v1/chat/completions.

Bilder (input_image)

Unterstützt Base64- oder URL-Quellen:

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

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

Dateien (input_file)

Unterstützt Base64- oder URL-Quellen:

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

Zulässige MIME-Typen (aktuell): text/plain, text/markdown, text/html, text/csv, application/json, application/pdf.

Maximale Größe (aktuell): 5 MB.

Aktuelles Verhalten:

  • Dateiinhalte werden dekodiert und dem System-Prompt hinzugefügt, nicht der Benutzernachricht, sodass sie flüchtig bleiben (nicht in der Sitzungshistorie persistiert).
  • Dekodierter Dateitext wird als nicht vertrauenswürdiger externer Inhalt eingeschlossen, bevor er hinzugefügt wird, sodass Dateibytes als Daten behandelt werden, nicht als vertrauenswürdige Anweisungen.
  • Der injizierte Block verwendet explizite Begrenzungsmarker wie <<&lt;EXTERNAL_UNTRUSTED_CONTENT id=&quot;...&quot;&gt;>> / <<&lt;END_EXTERNAL_UNTRUSTED_CONTENT id=&quot;...&quot;&gt;>> und enthält eine Source: External-Metadatenzeile.
  • Dieser Datei-Eingabepfad lässt das lange SECURITY NOTICE:-Banner bewusst weg, um Prompt-Budget zu sparen; die Begrenzungsmarker und Metadaten bleiben dennoch vorhanden.
  • PDFs werden zuerst auf Text geparst. Wenn wenig Text gefunden wird, werden die ersten Seiten in Bilder gerastert und an das Modell übergeben, und der injizierte Dateiblock verwendet den Platzhalter [PDF content rendered to images].

PDF-Parsing wird vom gebündelten document-extract-Plugin bereitgestellt, das clawpdf und dessen paketierte PDFium-WebAssembly-Laufzeit für Textextraktion und Seitenrendering verwendet.

Standardwerte für URL-Fetches:

  • files.allowUrl: true
  • images.allowUrl: true
  • maxUrlParts: 8 (Gesamtzahl URL-basierter input_file- und input_image-Teile pro Anfrage)
  • Anfragen werden geschützt (DNS-Auflösung, Blockieren privater IPs, Redirect-Obergrenzen, Timeouts).
  • Optionale Hostnamen-Allowlists werden pro Eingabetyp unterstützt (files.urlAllowlist, images.urlAllowlist).
    • Exakter Host: "cdn.example.com"
    • Wildcard-Subdomains: "*.assets.example.com" (entspricht nicht der Apex-Domain)
    • Leere oder ausgelassene Allowlists bedeuten keine Einschränkung durch Hostnamen-Allowlist.
  • Um URL-basierte Fetches vollständig zu deaktivieren, setzen Sie files.allowUrl: false und/oder images.allowUrl: false.

Datei- und Bildlimits (Konfiguration)

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

json5
{  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: 200000,            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:

  • maxBodyBytes: 20 MB
  • maxUrlParts: 8
  • files.maxBytes: 5 MB
  • files.maxChars: 200.000
  • files.maxRedirects: 3
  • files.timeoutMs: 10 s
  • files.pdf.maxPages: 4
  • files.pdf.maxPixels: 4.000.000
  • files.pdf.minTextChars: 200
  • images.maxBytes: 10 MB
  • images.maxRedirects: 3
  • images.timeoutMs: 10 s
  • HEIC/HEIF-input_image-Quellen werden akzeptiert, wenn ein Systemkonverter verfügbar ist, und vor der Provider-Auslieferung zu JPEG normalisiert. Unterstützte Konverter sind macOS-sips, ImageMagick, GraphicsMagick oder ffmpeg.

Sicherheitshinweis:

  • URL-Allowlists werden vor dem Fetch und bei Redirect-Hops durchgesetzt.
  • Das Allowlisting eines Hostnamens umgeht nicht das Blockieren privater/interner IPs.
  • Wenden Sie bei internetexponierten Gateways zusätzlich zu Schutzmechanismen auf Anwendungsebene Netzwerk-Egress-Kontrollen an. Siehe Sicherheit.

Streaming (SSE)

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

  • Content-Type: text/event-stream
  • Jede Ereigniszeile ist event: <type> und data: <json>
  • 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 Fehler)

Nutzung

usage wird gefüllt, wenn der zugrunde liegende Provider Tokenzahlen meldet. OpenClaw normalisiert gängige OpenAI-artige Aliase, bevor diese Zähler nachgelagerte Status-/Sitzungsoberflächen erreichen, einschließlich input_tokens / output_tokens und prompt_tokens / completion_tokens.

Fehler

Fehler verwenden ein JSON-Objekt wie:

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

Häufige Fälle:

  • 401 fehlende/ungültige Authentifizierung
  • 400 ungültiger Anfrage-Body
  • 405 falsche Methode

Beispiele

Nicht streamend:

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

Streaming:

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

Verwandt

Was this useful?
On this page

On this page