Die OpenResponses-API von OpenClaw

Die OpenResponses-Oberfläche ist die zweite HTTP-Tür in ein OpenClaw-Gateway. Sie teilt Port, Authentifizierungsregeln und den agentenzentrierten Modellvertrag mit dem Chat-Completions-Endpunkt, nimmt aber itembasierte Eingaben entgegen, gibt Funktionsaufrufe als Ausgabe-Items zurück und akzeptiert Dateien. Hier ist, was sie laut Dokumentation tut, samt den geltenden Limits.

Aktivierung und Vertrauen

• Die Einstellung für den responses-Endpunkt schaltet die responses-Route auf dem Gateway-Port ein und damit auch die Modellliste, die Abfrage eines einzelnen Modells und Embeddings; Chat Completions wird separat aktiviert, und jede Anfrage läuft als normaler Agent-Run des Gateways, sodass Routing, Berechtigungen und Konfiguration denen des Gateways entsprechen.
• Die Authentifizierung folgt dem Gateway-Modus: Bearer-Token oder Passwort für Shared-Secret-Modi, Header eines identitätsbewussten Proxys für Trusted-Proxy (Loopback-Proxys auf demselben Host brauchen das Loopback-Opt-in, mit einem direkten Passwort-Fallback, wenn kein weitergeleiteter Header vorhanden ist), kein Header für none bei privatem Ingress; der Endpunkt bedeutet vollen Operator-Zugriff, Shared-Secret-Modi ignorieren einen enger deklarierten Scopes-Header und stellen den Standardsatz an Operator-Scopes wieder her, und Modi mit Identität beachten den Header, wenn er vorhanden ist.
• Agenten werden gewählt, indem model auf openclaw, openclaw/default oder openclaw/ plus die Agent-ID gesetzt wird, oder über den Agent-ID-Header; der Modell-Header überschreibt das Backend-Modell (auf Pfaden mit Identität nur mit Admin-Rechten), der Sitzungs-Key-Header routet explizit und wird in den reservierten Namespaces subagent, cron und acp mit einem 400 abgewiesen, und der Message-Channel-Header setzt einen synthetischen Ingress-Kanal.
• Der Endpunkt ist standardmäßig pro Anfrage zustandslos; ein user-String leitet einen stabilen Sitzungsschlüssel ab, und previous_response_id verwendet die Sitzung der früheren Antwort wieder, wenn die Anfrage im selben Bereich aus Agent, Benutzer und angeforderter Sitzung bleibt, abgeglichen über Auth-Subjekt, Agent-ID und den Sitzungs-Key-Header; das explizite Fortsetzen einer Inkognito-Sitzung erfordert wirksame Admin-Berechtigung und liefert andernfalls ein 403 forbidden, das das Ziel verbirgt.

Dateiinhalte werden dekodiert und dem System-Prompt hinzugefügt, nicht der Benutzernachricht, und bleiben so flüchtig (nicht im Sitzungsverlauf gespeichert).

Items, Tools und Dateien

Das Feld input ist ein String oder ein Array von Items. Message-Items tragen die Rollen system, developer, user und assistant: system und developer werden an den System-Prompt angehängt, das jüngste Item vom Typ user oder function_call_output wird zur aktuellen Nachricht, und frühere Turns sind Verlauf. Instructions fließen in den System-Prompt ein; Tools sind clientseitige Funktions-Tools, die Tool-Auswahl akzeptiert auto, none, required oder eine benannte Funktion, die Obergrenze für Ausgabe-Tokens gilt nach bestem Bemühen, temperature und top_p ebenso, wobei das auf ChatGPT basierende Codex-Responses-Backend beide ignoriert, und die Obergrenze für Tool-Aufrufe, reasoning, metadata, store und truncation werden akzeptiert, aber ignoriert. Ruft der Agent ein Tool auf, liefert die Antwort ein Ausgabe-Item function_call, und der Client setzt den Turn mit einem function_call_output fort, das die Call-ID trägt; auch eine leere Ausgabe schließt den Aufruf ab. Clients, die ihren eigenen Verlauf führen, hängen die Ausgabe der Antwort unverändert an die nächste Eingabe an oder senden previous_response_id nur mit den neuen Items. Eine erzwungene oder fest vorgegebene Tool-Auswahl, die keinen passenden Aufruf ergibt, liefert einen 502 api_error bzw. beim Streaming ein Ereignis für eine fehlgeschlagene Antwort.

Dateien, Bilder und Limits

• Bild-Items akzeptieren Base64- oder URL-Quellen, wobei JPEG, PNG, GIF, WebP, HEIC und HEIF standardmäßig erlaubt sind, mit 10 MB pro Bild und HEIC und HEIF zu JPEG normalisiert; Datei-Items akzeptieren Base64 oder URL, wobei reiner Text, Markdown, HTML, CSV, JSON und PDF standardmäßig erlaubt sind, mit 5 MB und 60k Zeichen, Text wird mit seiner erkannten Kodierung dekodiert, und PDFs werden zuerst auf Text geparst, wobei die ersten Seiten zu Bildern gerastert werden, wenn wenig Text gefunden wird (standardmäßig 4 Seiten, 4 Millionen Pixel, mindestens 200 Zeichen).
• Dekodierter Dateitext wird als nicht vertrauenswürdiger externer Inhalt mit expliziten Grenzmarkierungen und einer Quellzeile umschlossen, bevor er in den Prompt gelangt, sodass Datei-Bytes Daten und keine Anweisungen sind; URL-Abrufe sind für Dateien und Bilder standardmäßig aktiv, mit 8 URL-Teilen pro Anfrage, abgesichert durch DNS-Auflösung, Blockierung privater Adressen, Obergrenzen für Weiterleitungen und Timeouts sowie optionale Hostnamen-Zulassungslisten pro Typ, die exakte Hosts oder Wildcard-Subdomains akzeptieren und vor dem Abruf und bei jedem Weiterleitungsschritt durchgesetzt werden.
• Der Request-Body ist auf 20 MB begrenzt; bei aktiviertem Streaming sind die Ereignisse typisiert (created, in progress, output item added, content part added, output text delta und done, output item done, completed, incomplete bei Kürzung durch das Ausgabebudget und failed bei Fehlern) und enden mit DONE; eine durch das Ausgabe-Token-Budget abgeschnittene Antwort liefert den Status incomplete mit dem Grund max output tokens, usage wird befüllt, wenn der Anbieter Zählungen meldet, und die Fehler sind 400, 401, 403 bei fehlendem Scope, 405 und 429 mit einem Retry-Header nach zu vielen fehlgeschlagenen Authentifizierungsversuchen.

Den Schwester-Endpunkt, dessen Modellvertrag dieser wiederverwendet, beschreibt der Beitrag zur OpenAI-kompatiblen HTTP-API von OpenClaw, den Scope-Satz, den beide wiederherstellen oder einschränken, erklärt der Beitrag zu den Operator-Scopes von OpenClaw.

Wann Sie ihn einsetzen

Das Item-Modell passt zu Clients, die bereits ihren eigenen Konversationsverlauf führen und ihn wortgetreu wiedergeben wollen, oder die Dateien und Bilder an einen Agenten übergeben müssen, ohne sie in der Sitzung zu speichern. Der Chat-Completions-Endpunkt passt zu Tools, die nur das ältere Format kennen. Beide führen darunter denselben Agent-Run aus, die Wahl hängt also vom Client ab, nicht vom Agenten. Die breitere Gateway-API behandelt der Beitrag zur OpenClaw-API, was der Agent selbst mit URLs macht, sobald eine Anfrage ihn erreicht, der Beitrag zu Web Fetch in OpenClaw.

Auf Diali

Auf Diali sitzt das Gateway hinter dem Ingress der Plattform, mit einer Laufzeitkonfiguration, die aus dem Dashboard generiert und bei jedem Release ersetzt wird; eine der beiden HTTP-Oberflächen zu aktivieren ist daher eine Konfigurationsentscheidung und kein Port, den man öffnet. Den gehosteten Assistenten beschreibt die Seite zu gehostetem OpenClaw auf Diali, die Tarife, in denen er enthalten ist, die Preisseite von Diali.

• Items rein, Funktionsaufrufe raus, Ergebnisse zurück als function_call_output.
• Dateien landen als nicht vertrauenswürdiger Inhalt im System-Prompt.
• Derselbe Port, dieselbe Authentifizierung, dasselbe Vertrauen auf Eigentümerebene wie bei Chat Completions.