OpenResponses API

OpenResponses API 是 Gateway 提供的增强型接口，在 OpenAI Chat Completions 基础上增加了结构化响应、会话持久化和更丰富的事件模型。

概述

与 Chat Completions API 的主要区别：

特性	Chat Completions	OpenResponses
会话管理	无状态	有状态（服务端管理上下文）
响应格式	纯文本/工具调用	结构化事件流
历史管理	客户端维护	服务端持久化
元数据	基础 usage	丰富的执行元数据

端点

POST /v1/responses

请求格式

{
  "model": "gpt-4o",
  "input": "Help me write a Python web server",
  "instructions": "You are a senior Python developer.",
  "session": {
    "id": "sess_abc123",
    "persist": true
  },
  "stream": true,
  "tools": [],
  "metadata": {
    "client": "vscode",
    "project": "my-app"
  }
}

请求参数

参数	类型	必填	说明
model	string	✅	模型标识
input	string/array	✅	用户输入（字符串或消息数组）
instructions	string	❌	系统指令（System Prompt）
session.id	string	❌	会话 ID，不传则创建新会话
session.persist	boolean	❌	是否持久化会话历史
stream	boolean	❌	是否启用流式响应
tools	array	❌	可用工具定义
metadata	object	❌	自定义元数据

非流式响应

{
  "id": "resp_xyz789",
  "object": "response",
  "created": 1705312200,
  "model": "gpt-4o",
  "session": {
    "id": "sess_abc123",
    "turnCount": 3
  },
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "text",
          "text": "Here's a simple Python web server..."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 45,
    "output_tokens": 230,
    "total_tokens": 275
  },
  "metadata": {
    "duration_ms": 2340,
    "channel": "openai-main"
  }
}

流式响应

设置 "stream": true 后，响应以 SSE（Server-Sent Events）事件流返回：

curl -X POST http://127.0.0.1:18789/v1/responses \
  -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","input":"Hello","stream":true}'

事件类型

event: response.created
data: {"type":"response.created","response":{"id":"resp_xyz","status":"in_progress"}}

event: response.output_item.added
data: {"type":"response.output_item.added","item":{"type":"message","role":"assistant"}}

event: response.content.delta
data: {"type":"response.content.delta","delta":{"type":"text","text":"Hello"}}

event: response.content.delta
data: {"type":"response.content.delta","delta":{"type":"text","text":"! How can"}}

event: response.content.done
data: {"type":"response.content.done","content":{"type":"text","text":"Hello! How can I help?"}}

event: response.completed
data: {"type":"response.completed","response":{"id":"resp_xyz","status":"completed","usage":{...}}}

流式事件一览

事件	说明
response.created	响应开始
response.output_item.added	新输出项开始
response.content.delta	内容增量
response.content.done	单项内容完成
response.tool_call.created	工具调用开始
response.tool_call.delta	工具调用参数增量
response.tool_call.done	工具调用完成
response.completed	响应全部完成
response.failed	响应失败

会话管理

创建会话

不传 session.id 时自动创建新会话：

{
  "model": "gpt-4o",
  "input": "Hello",
  "session": { "persist": true }
}

继续会话

传入之前返回的 session.id：

{
  "model": "gpt-4o",
  "input": "Continue from where we left off",
  "session": { "id": "sess_abc123" }
}

会话持久化

启用 persist 后，会话历史保存在 Gateway 端，客户端无需维护完整的消息历史。

查询会话

# 列出活跃会话
curl http://127.0.0.1:18789/v1/sessions \
  -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN"

# 获取会话详情
curl http://127.0.0.1:18789/v1/sessions/sess_abc123 \
  -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN"

# 删除会话
curl -X DELETE http://127.0.0.1:18789/v1/sessions/sess_abc123 \
  -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN"

使用场景

场景	推荐 API	原因
单次问答	Chat Completions	简单高效
多轮对话	OpenResponses	服务端会话管理
IDE 集成	OpenResponses	丰富的事件模型
第三方兼容	Chat Completions	广泛兼容性

何时选择 OpenResponses

如果你需要多轮对话管理、结构化事件流或丰富的元数据，选择 OpenResponses API。如果只需要简单的兼容性，使用 Chat Completions API。

相关文档

• OpenAI Chat Completions API — 兼容接口
• 工具调用 API — 直接工具执行
• 网关协议 — WebSocket 通信规范