OpenResponses Gateway Integrationsplan

Kontext

OpenClaw Gateway stellt aktuell einen minimalen OpenAI-kompatiblen Chat-Completions-Endpunkt unter /v1/chat/completions bereit (siehe OpenAI Chat Completions).

Open Responses ist ein offener Inferenz-Standard basierend auf der OpenAI Responses API. Er ist für agentische Workflows konzipiert und nutzt item-basierte Eingaben plus semantische Streaming-Events. Die OpenResponses-Spezifikation definiert /v1/responses, nicht /v1/chat/completions.

Ziele

• Einen /v1/responses-Endpunkt hinzufügen, der der OpenResponses-Semantik folgt.
• Chat Completions als Kompatibilitätsschicht beibehalten, die leicht deaktiviert und irgendwann entfernt werden kann.
• Validierung und Parsing mit isolierten, wiederverwendbaren Schemas standardisieren.

Nicht-Ziele

• Volle OpenResponses-Feature-Parität im ersten Durchgang (Bilder, Dateien, gehostete Tools).
• Interne Agent-Ausführungslogik oder Tool-Orchestrierung ersetzen.
• Das bestehende /v1/chat/completions-Verhalten während der ersten Phase ändern.

Forschungszusammenfassung

Quellen: OpenResponses OpenAPI, OpenResponses-Spezifikationsseite und der Hugging-Face-Blogbeitrag.

Extrahierte Kernpunkte:

• POST /v1/responses akzeptiert CreateResponseBody-Felder wie model, input (String oder ItemParam[]), instructions, tools, tool_choice, stream, max_output_tokens und max_tool_calls.
• ItemParam ist eine diskriminierte Union aus:
  • message-Items mit Rollen system, developer, user, assistant
  • function_call und function_call_output
  • reasoning
  • item_reference
• Erfolgreiche Antworten liefern eine ResponseResource mit object: "response", status und output-Items.
• Streaming nutzt semantische Events wie:
  • response.created, response.in_progress, response.completed, response.failed
  • response.output_item.added, response.output_item.done
  • response.content_part.added, response.content_part.done
  • response.output_text.delta, response.output_text.done
• Die Spezifikation erfordert:
  • Content-Type: text/event-stream
  • event: muss dem JSON-type-Feld entsprechen
  • Terminales Event muss wörtlich [DONE] sein
• Reasoning-Items können content, encrypted_content und summary bereitstellen.
• HF-Beispiele enthalten OpenResponses-Version: latest in Requests (optionaler Header).

Vorgeschlagene Architektur

• src/gateway/open-responses.schema.ts mit nur Zod-Schemas hinzufügen (keine Gateway-Imports).
• src/gateway/openresponses-http.ts (oder open-responses-http.ts) für /v1/responses hinzufügen.
• src/gateway/openai-http.ts als Legacy-Kompatibilitätsadapter intakt lassen.
• Config gateway.http.endpoints.responses.enabled hinzufügen (Standard false).
• gateway.http.endpoints.chatCompletions.enabled unabhängig halten; beide Endpunkte separat umschaltbar.
• Beim Start eine Warnung ausgeben wenn Chat Completions aktiviert ist, um den Legacy-Status zu signalisieren.

Deprecation-Pfad für Chat Completions

• Strikte Modulgrenzen beibehalten: keine gemeinsamen Schema-Typen zwischen Responses und Chat Completions.
• Chat Completions per Config opt-in machen, damit es ohne Code-Änderungen deaktiviert werden kann.
• Docs aktualisieren, um Chat Completions als Legacy zu kennzeichnen sobald /v1/responses stabil ist.
• Optionaler zukünftiger Schritt: Chat-Completions-Requests auf den Responses-Handler mappen für einen einfacheren Entfernungspfad.

Phase 1 Support-Subset

• input als String oder ItemParam[] mit Nachrichtenrollen und function_call_output akzeptieren.
• System- und Developer-Nachrichten in extraSystemPrompt extrahieren.
• Die neueste user- oder function_call_output-Nachricht als aktuelle Nachricht für Agent-Runs verwenden.
• Nicht unterstützte Content-Parts (Bild/Datei) mit invalid_request_error ablehnen.
• Eine einzelne Assistenten-Nachricht mit output_text-Inhalt zurückgeben.
• usage mit Nullwerten zurückgeben bis Token-Accounting verbunden ist.

Validierungsstrategie (ohne SDK)

• Zod-Schemas für das unterstützte Subset implementieren:
  • CreateResponseBody
  • ItemParam + Message-Content-Part-Unions
  • ResponseResource
  • Streaming-Event-Formen die vom Gateway genutzt werden
• Schemas in einem einzigen, isolierten Modul halten, um Drift zu vermeiden und zukünftige Codegen zu ermöglichen.

Streaming-Implementierung (Phase 1)

• SSE-Zeilen mit event: und data:.
• Erforderliche Sequenz (Minimum Viable):
  • response.created
  • response.output_item.added
  • response.content_part.added
  • response.output_text.delta (nach Bedarf wiederholen)
  • response.output_text.done
  • response.content_part.done
  • response.completed
  • [DONE]

Tests und Verifikationsplan

• E2E-Coverage für /v1/responses hinzufügen:
  • Auth erforderlich
  • Nicht-Stream-Antwortform
  • Stream-Event-Reihenfolge und [DONE]
  • Session-Routing mit Headern und user
• src/gateway/openai-http.test.ts unverändert lassen.
• Manuell: curl zu /v1/responses mit stream: true und Event-Reihenfolge sowie terminales [DONE] verifizieren.

Docs-Updates (Follow-up)

• Neue Docs-Seite für /v1/responses-Nutzung und Beispiele hinzufügen.
• /gateway/openai-http-api mit Legacy-Hinweis und Verweis auf /v1/responses aktualisieren.