Zum Inhalt springen
OpenClaw

OpenResponses API: So nutzt du das OpenClaw Gateway über...

Kennst du das? Du willst verschiedene KI-Modelle ansprechen, aber jedes Mal ist die API-Struktur ein bisschen anders. Das nervt und kostet Zeit beim Refactoring, besonders wenn du versuchst, eine konsistente Logik für deine Agents aufzubauen.

Das Gateway von OpenClaw kann einen OpenResponses-kompatiblen POST /v1/responses Endpoint bereitstellen. Damit vereinheitlichst du den Zugriff auf deine Agents über eine standardisierte Schnittstelle.

Dieser Endpoint ist standardmäßig deaktiviert. Aktiviere ihn zuerst in deiner Konfiguration.

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

Im Hintergrund werden Requests als normaler Gateway Agent Run ausgeführt (derselbe Codepfad wie openclaw agent). Daher passen Routing, Berechtigungen, Konfiguration und Sicherheitsregeln exakt zu deinem Gateway.

Authentifizierung, Sicherheit, Routing und Zugriffskontrolle

Abschnitt betitelt „Authentifizierung, Sicherheit, Routing und Zugriffskontrolle“

Das operative Verhalten entspricht der OpenAI Chat Completions API:

  • Verwende Authorization: Bearer <token> mit deiner normalen Gateway Auth-Konfiguration.
  • Behandle den Endpoint als vollen Operator-Zugriff für die Gateway-Instanz.
  • Bei Shared-Secret Auth-Modi (token und password) werden engere x-openclaw-scopes Werte ignoriert und die normalen Operator-Standards wiederhergestellt.
  • Bei Trusted Identity HTTP-Modi (z. B. Trusted Proxy Auth oder gateway.auth.mode="none") werden die deklarierten Operator-Scopes im Request weiterhin berücksichtigt.
  • Wähle Agents mit model: "openclaw", model: "openclaw/default", model: "openclaw/<agentId>" oder x-openclaw-agent-id aus.
  • Nutze x-openclaw-model, wenn du das Backend-Modell des gewählten Agents überschreiben willst.
  • Nutze x-openclaw-session-key für explizites Session-Routing.
  • Nutze x-openclaw-message-channel, wenn du einen benutzerdefinierten Ingress-Channel-Kontext benötigst.

Auth-Matrix:

  • gateway.auth.mode="token" oder "password" + Authorization: Bearer ...
    • Bestätigt den Besitz des Shared Gateway Operator Secrets.
    • Ignoriert engere x-openclaw-scopes.
    • Stellt den vollen Standard-Operator-Scope wieder her.
    • Behandelt Chat-Turns an diesem Endpoint als Owner-Sender Turns.
  • Trusted Identity HTTP-Modi (z. B. Trusted Proxy Auth oder gateway.auth.mode="none" bei privatem Ingress)
    • Berücksichtigt den deklarierten x-openclaw-scopes Header.
    • Erhält Owner-Semantik nur, wenn operator.admin tatsächlich in diesen Scopes vorhanden ist.

Aktiviere oder deaktiviere diesen Endpoint mit gateway.http.endpoints.responses.enabled.

Die Kompatibilität umfasst auch:

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

Für die genaue Erklärung, wie Agent-Target-Modelle, openclaw/default, Embeddings-Pass-Through und Backend-Modell-Overrides zusammenspielen, schau dir OpenAI Chat Completions sowie Model list and agent routing an.

Session-Verhalten

Abschnitt betitelt „Session-Verhalten“

Standardmäßig ist der Endpoint stateless pro Request (bei jedem Aufruf wird ein neuer Session-Key generiert).

Wenn der Request einen OpenResponses user String enthält, leitet das Gateway daraus einen stabilen Session-Key ab. So können aufeinanderfolgende Aufrufe dieselbe Agent-Session nutzen.

Request-Struktur (unterstützt)

Abschnitt betitelt „Request-Struktur (unterstützt)“

Der Request folgt der OpenResponses API mit Item-basiertem Input. Aktuell unterstützt werden:

  • input: String oder Array von Item-Objekten.
  • instructions: Wird in den System-Prompt gemergt.
  • tools: Client-Tool-Definitionen (Function Tools).
  • tool_choice: Filtert oder erzwingt Client-Tools.
  • stream: Aktiviert SSE-Streaming.
  • max_output_tokens: Best-effort Limit für den Output (abhängig vom Provider).
  • user: Stabiles Session-Routing.

Akzeptiert, aber derzeit ignoriert:

  • max_tool_calls
  • reasoning
  • metadata
  • store
  • truncation

Unterstützt:

  • previous_response_id: OpenClaw verwendet die frühere Response-Session wieder, wenn der Request im selben Agent/User/Session-Scope bleibt.

Items (Input)

Abschnitt betitelt „Items (Input)“

message

Abschnitt betitelt „message“

Rollen: system, developer, user, assistant.

  • system und developer werden an den System-Prompt angehängt.
  • Das aktuellste user oder function_call_output Item wird zur “aktuellen Nachricht”.
  • Frühere User/Assistant-Nachrichten werden als Historie für den Kontext einbezogen.

function_call_output (Turn-based Tools)

Abschnitt betitelt „function_call_output (Turn-based Tools)“

Sende Tool-Ergebnisse zurück an das Modell:

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

reasoning und item_reference

Abschnitt betitelt „reasoning und item_reference“

Wird für die Schema-Kompatibilität akzeptiert, aber beim Erstellen des Prompts ignoriert.

Tools (clientseitige Function Tools)

Abschnitt betitelt „Tools (clientseitige Function Tools)“

Stelle Tools bereit über tools: [{ type: "function", function: { name, description?, parameters? } }].

Wenn der Agent entscheidet, ein Tool aufzurufen, gibt die Response ein function_call Output-Item zurück. Du sendest dann einen Folge-Request mit function_call_output, um den Turn fortzusetzen.

Bilder (input_image)

Abschnitt betitelt „Bilder (input_image)“

Unterstützt base64 oder URL-Quellen:

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

Erlaubte MIME-Types (aktuell): image/jpeg, image/png, image/gif, image/webp, image/heic, image/heif. Maximale Größe (aktuell): 10MB.

Dateien (input_file)

Abschnitt betitelt „Dateien (input_file)“

Unterstützt base64 oder URL-Quellen:

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

Erlaubte MIME-Types (aktuell): text/plain, text/markdown, text/html, text/csv, application/json, application/pdf.

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

Aktuelles Verhalten:

  • Dateiinhalte werden dekodiert und zum System-Prompt hinzugefügt, nicht zur User-Nachricht. So bleiben sie ephemeral und werden nicht in der Session-Historie gespeichert.
  • PDFs werden nach Text durchsucht. Wenn wenig Text gefunden wird, werden die ersten Seiten als Bilder gerastert und an das Modell übergeben.

Das PDF-Parsing nutzt den Node-freundlichen pdfjs-dist Legacy-Build. Der moderne PDF.js Build wird im Gateway nicht verwendet, da er Browser-Worker benötigt.

URL-Fetch Standards:

  • files.allowUrl: true
  • images.allowUrl: true
  • maxUrlParts: 8 (Summe aus URL-basierten input_file + input_image Parts pro Request)
  • Requests sind abgesichert (DNS-Auflösung, Blockierung privater IPs, Redirect-Limits, Timeouts).
  • Optionale Hostname-Allowlists werden pro Input-Typ unterstützt (files.urlAllowlist, images.urlAllowlist).
    • Exakter Host: "cdn.example.com"
    • Wildcard-Subdomains: "*.assets.example.com"
    • Leere oder fehlende Allowlists bedeuten keine Einschränkung.
  • Um URL-basierte Abrufe komplett zu deaktivieren, setze files.allowUrl: false und/oder images.allowUrl: false.

Datei- und Bild-Limits (Konfiguration)

Abschnitt betitelt „Datei- und Bild-Limits (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: 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, falls nicht angegeben:

  • maxBodyBytes: 20MB
  • maxUrlParts: 8
  • files.maxBytes: 5MB
  • files.maxChars: 200k
  • files.maxRedirects: 3
  • files.timeoutMs: 10s
  • files.pdf.maxPages: 4
  • files.pdf.maxPixels: 4.000.000
  • files.pdf.minTextChars: 200
  • images.maxBytes: 10MB
  • images.maxRedirects: 3
  • images.timeoutMs: 10s
  • HEIC/HEIF input_image Quellen werden akzeptiert und vor der Auslieferung an den Provider in JPEG umgewandelt.

Sicherheitshinweis:

  • URL-Allowlists werden vor dem Abruf und bei Redirects geprüft.
  • Das Erlauben eines Hostnamens umgeht nicht die Blockierung privater/interner IPs.
  • Für Gateways im öffentlichen Internet solltest du zusätzlich zu den App-Level-Schutzmaßnahmen Netzwerk-Egress-Kontrollen einsetzen. Siehe Security.

Streaming (SSE)

Abschnitt betitelt „Streaming (SSE)“

Setze stream: true, um Server-Sent Events (SSE) zu erhalten:

  • Content-Type: text/event-stream
  • Jede Event-Zeile besteht aus event: <type> und data: <json>
  • Der Stream endet mit data: [DONE]

Aktuell gesendete Event-Typen:

  • 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 Fehlern)

Usage

Abschnitt betitelt „Usage“

Das Feld usage wird gefüllt, wenn der zugrunde liegende Provider Token-Counts meldet.

Fehler

Abschnitt betitelt „Fehler“

Fehler verwenden ein JSON-Objekt wie dieses:

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

Häufige Fälle:

  • 401 Fehlende oder ungültige Authentifizierung
  • 400 Ungültiger Request-Body
  • 405 Falsche HTTP-Methode
  • 500 Interner Serverfehler

Beispiele

Abschnitt betitelt „Beispiele“

Ohne Streaming:

Terminal-Fenster
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:

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

Nächste Schritte

Abschnitt betitelt „Nächste Schritte“

AI Setup Assistant

OpenClaw

OpenClaw Expert

Noch festgefahren?

Wenn diese Seite nicht hilft, frage OpenClaw Expert nach Schritt-fuer-Schritt-Loesungen.