本页内容
本页内容
网关
OpenResponses API
网关可以提供一个兼容 OpenResponses 的 POST /v1/responses 端点。它默认禁用,并与网关共享同一个端口(WS + HTTP 多路复用):http://<gateway-host>:<port>/v1/responses。
请求作为正常网关代理运行(与 openclaw agent 相同的代码路径)运行,因此路由、权限和配置与您的网关匹配。
使用 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 聊天 Completions。
身份验证、安全性和路由
运行行为与 OpenAI Chat Completions 一致:
- Auth path matches
gateway.auth.mode: shared-secret (token/password) usesAuthorization: Bearer <token-or-password>; trusted-proxy uses identity-aware proxy headers (same-host loopback proxies needgateway.auth.trustedProxy.allowLoopback = true, with a same-host direct fallback viagateway.auth.password/OPENCLAW_GATEWAY_PASSWORDwhen noForwarded/X-Forwarded-*/X-Real-IPheader is present);noneon private ingress needs no auth header. See 受信任代理认证。 - 将该端点视为对网关实例的完整运维访问权限。
- 共享密钥认证模式会忽略更窄的 bearer 声明的
x-openclaw-scopes,并恢复完整的默认运维权限范围集合:operator.admin、operator.approvals、operator.pairing、operator.read、operator.talk.secrets、operator.write。此端点上的聊天轮次会被视为 owner-sender 轮次。 - 受信任的、携带身份的 HTTP 模式(trusted-proxy,或
gateway.auth.mode="none")在存在x-openclaw-scopes时会予以尊重,否则回退到运维默认权限范围集合。只有当调用方显式缩小权限范围并省略operator.admin时,owner 语义才会丢失。 - 使用
model: "openclaw"、"openclaw/default"、"openclaw/<agentId>",或x-openclaw-agent-id标头来选择 agent。 - 使用
x-openclaw-model覆盖所选 agent 的后端模型(在携带身份的认证路径上需要operator.admin)。 - 使用
x-openclaw-session-key进行显式会话路由(如果使用保留的命名空间,则会被400 invalid_request_error拒绝:subagent:、cron:、acp:)。 - 使用
x-openclaw-message-channel指定非默认的合成入口通道上下文。
有关代理目标模型、openclaw/default、嵌入传递和后端模型覆盖的共享说明,请参阅 OpenAI 聊天 Completions。
另请参见 Operator scopes 和 Security。
会话行为
默认情况下,端点按请求为 无状态(每次调用都会生成新的会话密钥)。
如果路由会话已存档,非流式请求将返回 HTTP 409 和 invalid_request_error 以及在 Control UI 中恢复它的指导。流请求在流中报告相同的错误。在重试之前取消存档会话;被拒绝的请求保留其存档状态和历史记录。
如果请求包含 OpenResponses 的 user 字符串,Gateway 会根据它派生出一个稳定的会话键,以便重复调用可以共享同一个代理会话。
当请求停留在相同的 agent/user/requested-session 范围内(由身份验证主题、代理 ID 和 x-openclaw-session-key 匹配)时,previous_response_id 会重用先前响应的会话。
连续映射在共享状态数据库的核心键控存储(core:openresponses,命名空间 response-sessions)中网关重新启动后仍可保存长达 30 天,上限为网关上最新的 5,000 个响应。这与默认会话维护期限和计数相匹配;它不会延长基础会话或脚本的生命周期。映射仅包含 response/session 标识符、身份验证主体(安装密钥承载 HMAC 或经过验证的代理身份)、代理和请求的会话范围以及存储管理的时间戳。不会复制响应内容,也不需要单独的表或架构迁移。键控存储在查找时立即拒绝过期映射,并在后续写入该命名空间时分批删除过期行。空闲网关不运行插件状态到期扫描;即使在删除行之前,过期的映射仍然不可用。如果连续性持久性在成功运行后失败,端点将返回 HTTP 500 或流 response.failed,而不是报告其响应 ID 无法继续的成功。
未知、已过期、已驱逐或超出范围的 previous_response_id 返回与 invalid_request_error 相同的 HTTP 400,包括 stream: true 时。要恢复,请重新发送完整的输入历史记录并省略 previous_response_id;网关绝不会默默地为未解决的延续开始新的对话。旧网关退出后,无法恢复在此存储更改之前发出的响应。
隐身响应永远不会创建连续映射。当隐身会话处于活动状态时,使用相同的 x-openclaw-session-key 显式地继续它们;使用他们的响应 ID 返回与未知 ID 相同的 400。
显式隐身会话继续
显式选择或继续与 x-openclaw-session-key 的隐身对话(sessionKey 覆盖)需要有效的 operator.admin 权限。此规则遵循权限,而不是入口:它拒绝没有 owner/admin 权限的可信代理调用者和明确将 x-openclaw-scopes 缩小到管理员以下(例如,operator.write)的私人 gateway.auth.mode="none" 调用者。任一接收到 HTTP 403 并出现 forbidden 错误。此路径上的无配置文件私有无身份验证调用者将获得 missing scope: operator.admin;对于配置文件支持的调用方,响应会隐藏具有以下错误形状的私有目标(其中 <sessionKey> 是请求的覆盖):
Owner/admin 呼叫者保持显式隐身会话继续。没有 x-openclaw-scopes 的私有无身份验证请求接收默认运算符范围,包括 operator.admin,因此被视为 owner/admin. 保留的内部命名空间覆盖(subagent:、cron:、acp:)仍然是单独的验证失败,并且仍然返回 HTTP 400 与 invalid_request_error。
请求格式
| 字段 | 支持 |
|---|---|
input |
字符串或条目对象数组。 |
instructions |
合并到系统提示中。 |
tools |
客户端工具定义(函数工具)。 |
tool_choice |
"auto"、"none"、"required",或 { "type": "function", "name": "..." },用于筛选或强制使用客户端工具。 |
stream |
启用 SSE 流式传输。 |
max_output_tokens |
尽力而为的输出上限(取决于提供方)。 |
temperature |
尽力采样温度。被基于 ChatGPT- 的 Codex 响应后端忽略,该后端使用固定服务器端采样。 |
top_p |
尽力而为的核采样。与 temperature 一样,Codex Responses 也有同样的注意事项。 |
user |
稳定的会话路由。 |
previous_response_id |
会话连续性(见上文)。 |
max_tool_calls, reasoning, metadata, store, truncation |
已接受,但当前被忽略。 |
条目(input)
message
角色:system、developer、user、assistant。
system和developer会追加到系统提示中。- 最近的
user或function_call_output项会成为“当前消息”。 - 更早的 user/assistant 消息会作为上下文历史包含进来。
function_call_output(基于轮次的工具)
将工具结果发送回模型:
reasoning 和 item_reference
为兼容 schema 而接受,但在构建提示时会被忽略。
工具(客户端侧函数工具)
通过 tools: [{ type: "function", name, description?, parameters? }] 提供工具。
如果代理调用了工具,响应会返回一个 function_call 输出项。发送后续请求时使用 function_call_output 以继续该轮对话。
如果工具未生成文本,则返回 output: "" 及其 call_id。空结果仍然完成该工具调用,并且可以是延续中唯一的新输入项。
管理自己历史记录的客户端可以将 response.output 附加到 input,然后附加新用户消息或 function_call_output 项目。保持返回的助手元数据和函数调用 ID、名称和参数不变。或者,提供 previous_response_id 并且仅提供新的输入项目。
对于 tool_choice: "required" 和功能固定的 tool_choice,端点缩小了公开的客户端功能工具集,指示运行时在响应之前调用客户端工具,如果不包含匹配的结构化客户端工具调用(与 /v1/chat/completions 合约匹配),则拒绝轮流。非流式请求返回 502 和 api_error;流请求发出 response.failed 事件。
图像(input_image)
支持 base64 或 URL 来源:
允许的 MIME 类型(默认):image/jpeg、image/png、image/gif、image/webp、image/heic、image/heif。最大大小(默认):10MB。
文件(input_file)
支持 base64 或 URL 来源:
允许的 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: falseand/orimages.allowUrl: false。
文件+图像限制
端点使用内置的 20 MB 请求正文限制和 60 秒正文读取截止时间。超过截止时间的上传返回 HTTP 408。文件和图像源策略在 gateway.http.endpoints.responses 下仍然可配置:
省略时的默认值:
| 键 | 默认值 |
|---|---|
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 允许列表在提取之前和重定向跃点上强制执行。将主机名列入白名单不会绕过 private/internal IP 阻止。对于暴露在互联网上的网关,除了应用程序级防护之外,还应应用网络出口控制。请参阅 Security。
流式传输(SSE)
流式传输保留了单独的助理消息中的重复内容。如果无法通过附加到已发送的文本来表示更正,则流会发出 response.failed 而不是以不一致的内容完成。
设置 stream: true 以接收服务器发送的事件:
Content-Type: text/event-stream- 每条事件行的格式为
event: <type>和data: <json> - Stream 以
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(错误)。
失败的代理运行(包括整个代理超时)会返回失败的响应。流式传输失败会发出 response.failed,后跟 [DONE];部分内容可能已经到达客户端。超时设置遵循 代理循环 。
由于代理达到其输出令牌预算而结束的回复将返回 status: "incomplete" 和 incomplete_details: { "reason": "max_output_tokens" },并且其最终消息项携带 status: "incomplete"。流在终端 response.incomplete 事件上发出这些字段,因此按事件类型调度的客户端也会观察到截断。这反映了 /v1/chat/completions 上的 finish_reason: "length" 投影。
断开连接HTTP客户端取消活动源-URL下载并运行代理。如果在准备输入时发生取消,网关将释放该下载,并且不会启动另一个输入下载或代理运行。这适用于流式请求和非流式请求。如果网关本身在客户端仍处于连接状态时取消代理运行,则请求将返回失败的响应(HTTP 500当不流式传输时)和消息agent run was cancelled,而不是提供者超时。
用法
当底层提供商报告令牌计数时,将填充 usage。 OpenClaw 在这些计数器到达下游 status/session 表面(包括 input_tokens / output_tokens 和 prompt_tokens / completion_tokens)之前对常见的 OpenAI-style 别名进行标准化。
如果响应在完全使用到达之前结束,则 JSON 响应和终端流资源将省略 usage,而不是呈现零或临时计数作为完成。流完成不依赖于使用报告的到达。
错误
错误使用如下 JSON 对象:
常见情况:400 无效的请求正文、401 missing/invalid 身份验证、403 缺少运算符范围、405 方法错误、429 失败的身份验证尝试次数过多(使用 Retry-After)。
示例
非流式:
流媒体: