OpenResponses Gateway Integration

Kennst du das? Du baust einen KI-Agenten und merkst schnell, dass klassische Chat-APIs an ihre Grenzen stoßen. Wenn es um komplexe Tool-Calls oder präzises Streaming geht, fühlt sich das Verschicken von einfachen Nachrichten-Arrays oft wie eine Notlösung an. Agenten brauchen eine Struktur, die von Grund auf für ihre Arbeitsweise entworfen wurde.

Wir integrieren deshalb den OpenResponses-Standard. Das bedeutet für dich: Weg von flachen Chat-Strukturen hin zu einem System, das Item-basierte Inputs und semantische Streaming-Events nutzt. Es ist der sauberere Weg, um Agenten-Logik und Tool-Orchestrierung zu handhaben, ohne das Rad jedes Mal neu zu erfinden.

Voraussetzungen

• Eine laufende Instanz des OpenClaw Gateway
• Zugriff auf deine Konfigurationsdatei (YAML)
• Einen API-Client wie curl für Tests
• Ein Verständnis für Zod-Schemas (falls du den Code erweitern willst)

Schnellstart

In der ersten Phase unterstützen wir einen Kern-Subset des Standards. So aktivierst du den neuen /v1/responses Endpoint in nur zwei Schritten.

1. Endpoint aktivieren

Standardmäßig ist der neue Endpoint deaktiviert. Öffne deine Konfiguration und setze den entsprechenden Flag. Wir empfehlen, den alten /v1/chat/completions Endpoint vorerst aktiviert zu lassen, bis deine Integration stabil läuft.

gateway:
  http:
    endpoints:
      responses:
        enabled: true
      chatCompletions:
        enabled: true

2. Den ersten Request senden

OpenResponses nutzt das /v1/responses Pattern. Hier ist ein Beispiel für einen Request mit Streaming, der die neuen semantischen Events nutzt:

curl -X POST http://localhost:3000/v1/responses \
  -H "Content-Type: application/json" \
  -H "OpenResponses-Version: latest" \
  -d '{
    "model": "gpt-4",
    "input": [
      {
        "type": "message",
        "role": "user",
        "content": [{ "type": "text", "text": "Berechne die Route." }]
      }
    ],
    "stream": true
  }'

Das Gateway antwortet nun mit einer Sequenz von Events wie response.created, response.output_text.delta und schließt sauber mit [DONE] ab.

Fehlerbehebung

Hier sind die häufigsten Hürden, die im Source-Dokument für die aktuelle Phase identifiziert wurden:

• Fehler: invalid_request_error bei Datei-Uploads In Phase 1 werden Bilder und Dateien noch nicht unterstützt. Das Gateway lehnt Requests mit diesen Content-Parts strikt ab. Beschränke dich vorerst auf Text-Inhalte.
• Fehlende Token-Daten in der Response Die usage-Werte werden aktuell noch mit Nullwerten zurückgegeben. Die Token-Abrechnung wird erst in einer späteren Phase mit der internen Logik verkabelt.
• Streaming bricht ohne Abschluss ab Stelle sicher, dass dein Client das [DONE] Literal als terminales Event korrekt verarbeitet. Das Gateway sendet eine strikte Sequenz von response.completed gefolgt von [DONE].
• Startup-Warnungen im Log Wenn du chatCompletions aktiviert hast, siehst du eine Warnung. Das ist beabsichtigt, da dieser Endpoint nun als Legacy gilt und langfristig entfernt wird.

Brauchst du Hilfe bei der Integration oder hast spezifische Fragen zu den Zod-Schemas? Unser AI Setup Assistant unterstützt dich dabei.

Nächste Schritte

• OpenAI Chat Completions Legacy Dokumentation
• OpenResponses Spezifikation Details