OpenResponses Gateway 整合計畫

背景

OpenClaw Gateway 目前提供一個最小化的 OpenAI 相容 Chat Completions 端點，位於 /v1/chat/completions（參見 OpenAI Chat Completions）。

Open Responses 是基於 OpenAI Responses API 的開放推論標準，專為代理工作流設計，使用基於項目的輸入加上語義化串流事件。OpenResponses 規格定義 /v1/responses，而非 /v1/chat/completions。

目標

• 新增遵循 OpenResponses 語義的 /v1/responses 端點。
• 將 Chat Completions 保留為可輕易停用且最終移除的相容層。
• 以隔離、可重用的 schema 標準化驗證與解析。

非目標

• 第一版不求完整的 OpenResponses 功能對齊（圖片、檔案、託管工具）。
• 不替換內部代理執行邏輯或工具協調。
• 第一階段不改變既有的 /v1/chat/completions 行為。

研究摘要

來源：OpenResponses OpenAPI、OpenResponses 規格網站、Hugging Face 部落格文章。

關鍵重點：

• POST /v1/responses 接受 CreateResponseBody 欄位如 model、input（字串或 ItemParam[]）、instructions、tools、tool_choice、stream、max_output_tokens 和 max_tool_calls。
• ItemParam 是以下型別的判別聯集：
  • 角色為 system、developer、user、assistant 的 message 項目
  • function_call 和 function_call_output
  • reasoning
  • item_reference
• 成功回應回傳含 object: "response"、status 和 output 項目的 ResponseResource。
• 串流使用語義化事件如：
  • 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
• 規格要求：
  • Content-Type: text/event-stream
  • event: 必須匹配 JSON 的 type 欄位
  • 終止事件必須為文字值 [DONE]
• Reasoning 項目可公開 content、encrypted_content 和 summary。
• HF 範例在請求中包含 OpenResponses-Version: latest（選用標頭）。

提議的架構

• 新增 src/gateway/open-responses.schema.ts，僅包含 Zod schema（不匯入 gateway）。
• 新增 src/gateway/openresponses-http.ts（或 open-responses-http.ts）用於 /v1/responses。
• 保留 src/gateway/openai-http.ts 作為舊版相容轉接器。
• 新增設定 gateway.http.endpoints.responses.enabled（預設 false）。
• 保持 gateway.http.endpoints.chatCompletions.enabled 獨立；允許兩個端點分別切換。
• 啟用 Chat Completions 時在啟動時發出警告，表明其為舊版。

Chat Completions 的淘汰路徑

• 維持嚴格的模組邊界：responses 和 chat completions 之間不共用 schema 型別。
• 讓 Chat Completions 透過設定成為選擇加入，可在不改程式碼的情況下停用。
• /v1/responses 穩定後更新文件，將 Chat Completions 標記為舊版。
• 選用的未來步驟：將 Chat Completions 請求對應至 Responses 處理器，簡化移除路徑。

第 1 階段支援子集

• 接受 input 為字串或含訊息角色和 function_call_output 的 ItemParam[]。
• 將 system 和 developer 訊息抽取至 extraSystemPrompt。
• 使用最近的 user 或 function_call_output 作為代理執行的當前訊息。
• 拒絕不支援的內容部分（圖片/檔案），回傳 invalid_request_error。
• 回傳含 output_text 內容的單一 assistant 訊息。
• 回傳 usage，token 計量串接完成前以零值填充。

驗證策略（不使用 SDK）

• 為以下支援子集實作 Zod schema：
  • CreateResponseBody
  • ItemParam + 訊息內容部分聯集
  • ResponseResource
  • gateway 使用的串流事件結構
• 將 schema 保持在單一隔離模組中，避免偏差並允許未來的程式碼生成。

串流實作（第 1 階段）

• SSE 行包含 event: 和 data:。
• 必要序列（最小可行）：
  • response.created
  • response.output_item.added
  • response.content_part.added
  • response.output_text.delta（依需要重複）
  • response.output_text.done
  • response.content_part.done
  • response.completed
  • [DONE]

測試與驗證計畫

• 新增 /v1/responses 的端對端覆蓋：
  • 需要驗證
  • 非串流回應結構
  • 串流事件排序與 [DONE]
  • 透過標頭和 user 的 session 路由
• 保持 src/gateway/openai-http.test.ts 不變。
• 手動：curl 至 /v1/responses 搭配 stream: true，驗證事件排序和終止的 [DONE]。

文件更新（後續）

• 新增 /v1/responses 使用與範例的文件頁面。
• 更新 /gateway/openai-http-api 加入舊版說明和指向 /v1/responses 的指引。