OpenResponses Gateway 集成计划

背景

OpenClaw Gateway 目前在 /v1/chat/completions 暴露了一个最小化的 OpenAI 兼容 Chat Completions 端点（参见 OpenAI Chat Completions）。

Open Responses 是一个基于 OpenAI Responses API 的开放推理标准。它专为 agentic 工作流设计，使用基于 item 的输入和语义化的流式事件。OpenResponses 规范定义了 /v1/responses，而非 /v1/chat/completions。

目标

添加遵循 OpenResponses 语义的 /v1/responses 端点。
保留 Chat Completions 作为兼容层，便于禁用和最终移除。
使用隔离的、可复用的 schema 标准化验证和解析。

不做的事

第一轮不做完整的 OpenResponses 功能对齐（图片、文件、hosted tools）。
不替换内部 agent 执行逻辑或工具编排。
第一阶段不改变现有 /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 是区分联合体：message items（角色 system、developer、user、assistant）、function_call/function_call_output、reasoning、item_reference。
成功响应返回 ResponseResource，包含 object: "response"、status 和 output items。
流式使用语义化事件，如 response.created、response.output_text.delta、response.completed 等。
规范要求：Content-Type: text/event-stream，event: 必须匹配 JSON type 字段，终止事件必须是字面量 [DONE]。

提案架构

添加 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 处理器，简化移除路径。

第一阶段支持子集

接受 input 为字符串或 ItemParam[]，包含消息角色和 function_call_output。
将 system 和 developer 消息提取到 extraSystemPrompt。
使用最近的 user 或 function_call_output 作为 agent 运行的当前消息。
用 invalid_request_error 拒绝不支持的内容部分（图片/文件）。
返回带 output_text 内容的单个 assistant 消息。
返回 usage，在 token 计费接入之前使用零值。

验证策略（无 SDK）

为支持的子集实现 Zod schema：CreateResponseBody、ItemParam + 消息内容部分联合体、ResponseResource、Gateway 使用的流式事件形状。
将 schema 保持在单一隔离模块中避免漂移，并允许未来的代码生成。

流式实现（第一阶段）

带 event: 和 data: 的 SSE 行。
必需的最小可用序列：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]、带 header 和 user 的会话路由。
保持 src/gateway/openai-http.test.ts 不变。
手动：用 stream: true curl /v1/responses，验证事件排序和终止 [DONE]。

文档更新（后续）

添加 /v1/responses 的使用和示例文档页面。
更新 /gateway/openai-http-api 加遗留说明和指向 /v1/responses 的引用。