OpenResponses API
Gateway 可以提供兼容 OpenResponses 的 POST /v1/responses 端点。它默认禁用,并与 Gateway 共享端口(WS + HTTP 复用):http://<gateway-host>:<port>/v1/responses。
请求作为普通的 Gateway agent 运行执行(与 openclaw agent 相同的代码路径),因此路由、权限和配置与你的 Gateway 一致。
使用 gateway.http.endpoints.responses.enabled 启用或禁用。启用后,同一兼容接口还提供 GET /v1/models、GET /v1/models/{id} 和 POST /v1/embeddings。
POST /v1/chat/completions 通过 gateway.http.endpoints.chatCompletions.enabled 单独启用。参见 OpenAI Chat Completions。
身份验证、安全性和路由¶
运行行为与 OpenAI Chat Completions 一致:
- 身份验证路径与
gateway.auth.mode匹配:共享密钥(token/password)使用Authorization: Bearer <token-or-password>;trusted-proxy 使用身份感知代理头(同主机回环代理需要gateway.auth.trustedProxy.allowLoopback = true,当不存在Forwarded/X-Forwarded-*/X-Real-IP头时,通过gateway.auth.password/OPENCLAW_GATEWAY_PASSWORD进行同主机直接回退);私有入口上的none无需身份验证头。参见 可信代理身份验证。 - 将该端点视为对 Gateway 实例的完整操作员访问权限。
- 共享密钥身份验证模式会忽略更窄的 bearer 声明的
x-openclaw-scopes,并恢复完整的默认操作员作用域集合:operator.admin、operator.approvals、operator.pairing、operator.read、operator.talk.secrets、operator.write。此端点上的聊天轮次被视为所有者发送者轮次。 - 可信身份承载 HTTP 模式(trusted-proxy 或
gateway.auth.mode="none")在存在x-openclaw-scopes时遵循它,否则回退到操作员默认作用域集合。只有当调用方显式缩小作用域并省略operator.admin时,才会丢失所有者语义。 - 使用
model: "openclaw"、"openclaw/default"、"openclaw/<agentId>"或x-openclaw-agent-id头选择 agent。 - 使用
x-openclaw-model覆盖所选 agent 的后端模型(在身份承载身份验证路径上需要operator.admin)。 - 使用
x-openclaw-session-key进行显式会话路由(如果使用了保留命名空间:subagent:、cron:、acp:,则会被拒绝并返回400 invalid_request_error)。 - 使用
x-openclaw-message-channel指定非默认的合成入口通道上下文。
关于 agent 目标模型、openclaw/default、embeddings 直通和后端模型覆盖的权威说明,参见 OpenAI Chat Completions。
会话行为¶
默认情况下,该端点按请求无状态(每次调用都会生成新的会话密钥)。
如果请求包含 OpenResponses user 字符串,Gateway 会从中派生稳定的会话密钥,以便重复调用可以共享一个 agent 会话。
当请求保持在同一 agent/user/请求会话范围内(通过身份验证主体、agent id 和 x-openclaw-session-key 匹配)时,previous_response_id 会复用先前响应的会话。
延续映射在共享状态数据库的核心键控存储(core:openresponses,命名空间 response-sessions)中于 Gateway 重启后保留,最长 30 天,并在整个 Gateway 范围内以最新的 5,000 个响应为上限。这与默认会话维护年龄和数量一致;它不会延长底层会话或转录的生命周期。映射仅包含响应/会话标识符、身份验证主体(基于安装密钥的 bearer HMAC 或已验证的代理身份)、agent 和请求会话范围,以及存储管理的时间戳。不会复制响应内容,也不需要单独的表或架构迁移。键控存储在查找时立即拒绝过期映射,并在后续写入以及共享插件状态维护扫描中删除过期行;该扫描每分钟运行一次,以有界批次执行。如果其他方面成功的运行之后连续性持久化失败,端点会返回 HTTP 500 或流式 response.failed,而不是报告一个其响应 ID 无法继续的成功。
未知、过期、被驱逐或超出范围的 previous_response_id 会返回相同的 HTTP 400 和 invalid_request_error,包括 stream: true 时。要恢复,请重新发送完整的输入历史并省略 previous_response_id;Gateway 绝不会为未解决的延续静默开始新对话。在此存储更改之前发出的响应在旧 Gateway 退出后无法恢复。
隐身响应从不创建延续映射。在隐身会话存活期间,使用相同的 x-openclaw-session-key 显式继续它们;使用其响应 ID 会像未知 ID 一样返回相同的 400。
显式隐身会话延续¶
使用 x-openclaw-session-key(sessionKey 覆盖)显式选择或继续隐身对话需要有效的 operator.admin 权限。此规则遵循权限,而非入口:它拒绝没有所有者/管理员权限的 trusted-proxy 调用方,以及显式将 x-openclaw-scopes 缩小到管理员以下(例如缩小到 operator.write)的私有 gateway.auth.mode="none" 调用方。两者都会收到带有 forbidden 错误的 HTTP 403。在此路径上,无配置文件的私有无身份验证调用方会得到 missing scope: operator.admin;对于有配置文件支持的调用方,响应会以以下错误格式隐藏私有目标(其中 <sessionKey> 是请求的覆盖值):
{
"error": {
"message": "Incognito session \"<sessionKey>\" was not found.",
"type": "forbidden"
}
}
所有者/管理员调用方保留显式隐身会话延续。没有 x-openclaw-scopes 的私有无身份验证请求会获得默认操作员作用域,包括 operator.admin,因此被视为所有者/管理员。保留的内部命名空间覆盖(subagent:、cron:、acp:)仍然是单独的验证失败,并仍返回带有 invalid_request_error 的 HTTP 400。
请求格式¶
| 字段 | 支持 |
|---|---|
input |
字符串或条目对象数组。 |
instructions |
合并到系统提示中。 |
tools |
客户端工具定义(函数工具)。 |
tool_choice |
"auto"、"none"、"required",或 { "type": "function", "name": "..." },用于筛选或要求使用客户端工具。 |
stream |
启用 SSE 流式传输。 |
max_output_tokens |
尽力而为的输出限制(取决于提供商)。 |
temperature |
尽力而为的采样温度。基于 ChatGPT 的 Codex Responses 后端会忽略该参数,其使用固定的服务端采样。 |
top_p |
尽力而为的核采样。与 temperature 相同的 Codex Responses 注意事项。 |
user |
稳定的会话路由。 |
previous_response_id |
会话连续性(见上文)。 |
max_tool_calls、reasoning、metadata、store、truncation |
已接受但当前被忽略。 |
条目(输入)¶
message¶
角色:system、developer、user、assistant。
system和developer会追加到系统提示中。- 最近的
user或function_call_output条目会成为“当前消息”。 - 较早的用户/助手消息会作为上下文历史包含在内。
function_call_output(基于轮次的工具)¶
将工具结果返回给模型:
reasoning 和 item_reference¶
为保持模式兼容性而接受,但在构建提示时会被忽略。
工具(客户端函数工具)¶
通过 tools: [{ type: "function", name, description?, parameters? }] 提供工具。
如果代理调用了工具,响应会返回一个 function_call 输出条目。发送包含 function_call_output 的后续请求以继续该轮次。
如果工具未产生文本,请连同其 call_id 返回 output: ""。空结果仍会完成该工具调用,并且可以成为续接请求中唯一的新输入条目。
自行管理历史的客户端可以将 response.output 追加到 input,然后追加新的用户消息或 function_call_output 条目。保持返回的助手元数据以及函数调用 ID、名称和参数不变。或者,提供 previous_response_id,并且只提供新的输入条目。
对于 tool_choice: "required" 和固定函数的 tool_choice,端点会缩小暴露的客户端函数工具集,指示运行时在响应前调用客户端工具,并且如果响应不包含匹配的、结构化的客户端工具调用,则拒绝该轮次,以符合 /v1/chat/completions 契约。非流式请求会返回带有 api_error 的 502;流式请求会发出 response.failed 事件。
图像(input_image)¶
支持 base64 或 URL 来源:
允许的 MIME 类型(默认):image/jpeg、image/png、image/gif、image/webp、image/heic、image/heif。最大大小(默认):10MB。
文件(input_file)¶
支持 base64 或 URL 来源:
{
"type": "input_file",
"source": {
"type": "base64",
"media_type": "text/plain",
"data": "SGVsbG8gV29ybGQh",
"filename": "hello.txt"
}
}
允许的 MIME 类型(默认):text/plain、text/markdown、text/html、text/csv、application/json、application/pdf。最大大小(默认):5MB。
当前行为:
- 从其他未指定类型的字节推断出的文本会保留其检测到的编码,包括 UTF-16 和 Windows-1252。声明的文本字符集仍受支持。
- 文件内容会被解码并添加到系统提示中,而不是用户消息中,因此它是临时的(不会持久化到会话历史中)。
- 解码后的文件文本在添加前会被包装为不受信任的外部内容,因此文件字节被视为数据,而不是受信任的指令。注入的块使用显式边界标记(
<<<EXTERNAL_UNTRUSTED_CONTENT id="...">>>/<<<END_EXTERNAL_UNTRUSTED_CONTENT id="...">>>)和一行Source: External元数据。它有意省略一行数据边界说明,以保留提示预算;边界标记和元数据仍然适用。 - 首先会解析 PDF 中的文本。如果找到的文本很少,则会将前几页栅格化为图像并传递给模型,注入的文件块会使用占位符
[PDF content rendered to images]。 - 当页面、文本或图像限制导致提取不完整时,注入的文件块会以一个有界的
[Partial document: ...]标记开头,该标记位于不受信任的文件内容边界之外。
PDF 解析由内置的 document-extract 插件提供,该插件使用 clawpdf 及其打包的 PDFium WebAssembly 运行时进行文本提取和页面渲染。
URL 获取默认值:
files.allowUrl:trueimages.allowUrl:truemaxUrlParts:8(每个请求中基于 URL 的input_file+input_image部分总数)- 请求受到保护(DNS 解析、私有 IP 阻止、重定向上限、超时)。
- 每个输入类型都支持可选的主机名允许列表(
files.urlAllowlist、images.urlAllowlist):精确主机("cdn.example.com")或通配符子域("*.assets.example.com",不匹配根域)。空允许列表或省略允许列表表示没有主机名允许列表限制。 - 若要完全禁用基于 URL 的获取,请设置
files.allowUrl: false和/或images.allowUrl: false。
文件与图像限制¶
该端点使用内置的 20 MB 请求体限制。文件和图像源策略仍可在 gateway.http.endpoints.responses 下配置:
{
gateway: {
http: {
endpoints: {
responses: {
enabled: true,
maxUrlParts: 8,
files: {
allowUrl: true,
urlAllowlist: ["cdn.example.com", "*.assets.example.com"],
allowedMimes: [
"text/plain",
"text/markdown",
"text/html",
"text/csv",
"application/json",
"application/pdf",
],
maxBytes: 5242880,
maxChars: 60000,
maxRedirects: 3,
timeoutMs: 10000,
pdf: {
maxPages: 4,
maxPixels: 4000000,
minTextChars: 200,
},
},
images: {
allowUrl: true,
urlAllowlist: ["images.example.com"],
allowedMimes: [
"image/jpeg",
"image/png",
"image/gif",
"image/webp",
"image/heic",
"image/heif",
],
maxBytes: 10485760,
maxRedirects: 3,
timeoutMs: 10000,
},
},
},
},
},
}
省略时的默认值:
| 键 | 默认值 |
|---|---|
maxUrlParts |
8 |
files.maxBytes |
5MB |
files.maxChars |
60k |
files.maxRedirects |
3 |
files.timeoutMs |
10s |
files.pdf.maxPages |
4 |
files.pdf.maxPixels |
4,000,000 |
files.pdf.minTextChars |
200 |
images.maxBytes |
10MB |
images.maxRedirects |
3 |
images.timeoutMs |
10s |
HEIC/HEIF input_image 源在通过共享 OpenClaw 图像处理器(Rastermill)交付给提供商之前会被规范化为 JPEG;对于需要外部编解码器支持的格式,它会回退到系统转换器(sips、ImageMagick、GraphicsMagick 或 ffmpeg)。
安全说明:URL 允许列表在获取前和重定向跳转时强制执行。将主机名加入允许列表不会绕过私有/内部 IP 阻止。对于暴露在互联网上的网关,除应用层防护外,还应应用网络出口控制。参见 安全。
流式传输(SSE)¶
流式传输会保留来自不同助手消息的重复内容。如果更正无法通过追加到已发送文本来表示,流将发出 response.failed,而不是以不一致的内容完成。
设置 stream: true 以接收服务器发送事件(SSE):
Content-Type: text/event-stream- 每个事件行是
event: <type>和data: <json> - 流以
data: [DONE]结束
当前发出的事件类型:response.created、response.in_progress、response.output_item.added、response.content_part.added、response.output_text.delta、response.output_text.done、response.content_part.done、response.output_item.done、response.completed、response.incomplete(在输出预算截断时)、response.failed(出错时)。
失败的 agent 运行(包括整个 agent 超时)会返回失败响应。流式失败会发出 response.failed,随后是 [DONE];部分内容可能已经到达客户端。超时设置遵循 agent 循环。
因 agent 达到其输出 token 预算而结束的回包会以 status: "incomplete" 和 incomplete_details: { "reason": "max_output_tokens" } 返回,并且其最终消息项携带 status: "incomplete"。流式传输会在终止的 response.incomplete 事件上发出这些字段,因此按事件类型分发的客户端也能观察到截断。这与 /v1/chat/completions 上的 finish_reason: "length" 投影相对应。
断开 HTTP 客户端会取消正在进行的源 URL 下载和 agent 运行。如果取消发生在准备输入期间,Gateway 会释放该下载,并且不会启动另一个输入下载或 agent 运行。这适用于流式和非流式请求。如果 Gateway 本身在客户端仍连接时取消了 agent 运行,请求将返回失败响应(非流式时为 HTTP 500),消息为 agent run was cancelled,而不是提供商超时。
用量¶
当底层提供商报告 token 计数时,会填充 usage。OpenClaw 会在这些计数器到达下游状态/会话界面之前规范化常见的 OpenAI 风格别名,包括 input_tokens / output_tokens 和 prompt_tokens / completion_tokens。
错误¶
错误使用如下 JSON 对象:
常见情况:400 无效请求体、401 缺少/无效认证、403 缺少 operator 范围、405 方法错误、429 认证失败次数过多(带有 Retry-After)。
示例¶
非流式:
curl -sS http://127.0.0.1:18789/v1/responses \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-H 'x-openclaw-agent-id: main' \
-d '{
"model": "openclaw",
"input": "hi"
}'
流式传输:
curl -N http://127.0.0.1:18789/v1/responses \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-H 'x-openclaw-agent-id: main' \
-d '{
"model": "openclaw",
"stream": true,
"input": "hi"
}'
相关¶
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw