OpenClawSkills
GitHub
Gateway / 运用 • TutorialHeader.readTime

OpenResponses API（兼容API）

Gateway 从 OpenResponses 兼容的 /v1/responses HTTP 端点公开执行。

OpenClaw's Gateway can serve an OpenResponses-compatible ''POST /v1/responses'' endpoint.

This endpoint is disabled by default. Enable it in config first.

- ''POST /v1/responses''

- 网关和同自端口（WS + HTTP 多重化）：''http://<gateway-host>:<port>/v1/responses''

Under the hood, requests are executed as a normal Gateway agent run (same codepath as ''openclaw agent''), so routing/permissions/config match your Gateway.

Tutorial.step

认证

Uses the Gateway auth configuration. Send a bearer token:

- ''Authorization: Bearer <token>''

注意：

- ''gateway.auth.mode="token"'' 的場合、''gateway.auth.token''（或 ''OPENCLAW_GATEWAY_TOKEN''）使用执行。

- ''gateway.auth.mode="password"'' 的場合、''gateway.auth.password''（或 ''OPENCLAW_GATEWAY_PASSWORD''）使用执行。

Tutorial.step

代理的选择

无需自定义标头：在 OpenResponses ''model'' 字段中编码代理 ID：

- ''model: "openclaw:<agentId>"''（例：''"openclaw:main"''、''"openclaw:beta"''）

- ''model: "agent:<agentId>"''（别名）

或者通过标头指定特定的 OpenClaw 代理：

- ''x-openclaw-agent-id: <agentId>''（默认：''main''）

高度：

- ''x-openclaw-session-key: '''' 在会话路由完全在控制执行。

Tutorial.step

端点的启用

''gateway.http.endpoints.responses.enabled'' ''true'' 在设置执行：

Json5
{
  gateway: {
    http: {
      endpoints: {
        responses: { enabled: true },
      },
    },
  },
}
Tutorial.step

端点的禁用

''gateway.http.endpoints.responses.enabled'' ''false'' 在设置执行：

Json5
{
  gateway: {
    http: {
      endpoints: {
        responses: { enabled: false },
      },
    },
  },
}
Tutorial.step

会话动作

默认情况下，端点对每个请求是无状态的（每次调用都会生成新的会话密钥）。

如果请求包含 OpenResponses ''user'' 字符串，网关会从中派生一个稳定的会话密钥，这样重复调用可以共享代理会话。

Tutorial.step

请求形状（支持）

请求遵循 OpenResponses API，使用基于项目的输入。目前支持：

- ''input'': string or array of item objects.

- ''instructions''：系统提示词在合并被。

- ''tools''：客户端工具定義（函数工具）。

- ''tool_choice'': filter or require client tools.

- ''stream''：SSE 流媒体启用在执行。

- ''max_output_tokens''：尽力而为输出限制（提供商依赖）。

- ''user''：安定已执行会话路由。

Accepted but currently ignored:

- ''max_tool_calls''

- ''reasoning''

- ''metadata''

- ''store''

- ''previous_response_id''

- ''truncation''

Tutorial.step

Items (input)

#

Tutorial.step

`message`

角色：''system''、''developer''、''user''、''assistant''。

- ''system'' 和 ''developer'' 是系统提示词的後在添加被。

- The most recent ''user'' or ''function_call_output'' item becomes the "current message".

- Earlier user/assistant messages are included as context history.

#

Tutorial.step

`function_call_output`（轮基础工具）

工具的结果模型在送里返执行：

Json
{
  "type": "function_call_output",
  "call_id": "call_123",
  "output": "{\"temperature\": \"72F\"}"
}

#

Tutorial.step

`reasoning` 和 `item_reference`

为兼容性而接受，但在构建提示时被忽略。

Tutorial.step

工具（客户端函数工具）

tools: [{ type: "function", function: { name, description?, parameters? } }] 在工具提供执行。

如果代理决定调用工具，响应将返回 ''function_call'' 输出项。

After that, send a follow-up request via ''function_call_output'' to continue the turn.

Tutorial.step

画像 (`input_image`)

base64 或 URL 源支持执行：

Json
{
  "type": "input_image",
  "source": { "type": "url", "url": "https://example.com/image.png" }
}

Allowed MIME types (current): ''image/jpeg'', ''image/png'', ''image/gif'', ''image/webp''.

最大大小（现在）：10MB。

Tutorial.step

文件 (`input_file`)

base64 或 URL 源支持执行：

Json
{
  "type": "input_file",
  "source": {
    "type": "base64",
    "media_type": "text/plain",
    "data": "SGVsbG8gV29ybGQh",
    "filename": "hello.txt"
  }
}

Allowed MIME types (current): ''text/plain'', ''text/markdown'', ''text/html'', ''text/csv'', ''application/json'', ''application/pdf''.

最大大小（现在）：5MB。

现在的动作：

- File content is decoded and added to the system prompt, not the user message, so it stays ephemeral (not persisted in session history).

- PDFs are parsed for text. If little text is found, the first pages are rasterized into images and passed to the model.

- PDF parsing uses the Node-friendly ''pdfjs-dist'' legacy build (no worker). The modern PDF.js build expects browser workers/DOM globals, so it is not used in the Gateway.

URL fetch defaults:

- ''files.allowUrl''：''true''

- ''images.allowUrl''：''true''

- Requests are guarded (DNS resolution, private IP blocking, redirect caps, timeouts).

Tutorial.step

文件+图像的限制（设置）

默认值可以在 ''gateway.http.endpoints.responses'' 下调整：

Json5
{
  gateway: {
    http: {
      endpoints: {
        responses: {
          enabled: true,
          maxBodyBytes: 20000000,
          files: {
            allowUrl: true,
            allowedMimes: [
              "text/plain",
              "text/markdown",
              "text/html",
              "text/csv",
              "application/json",
              "application/pdf",
            ],
            maxBytes: 5242880,
            maxChars: 200000,
            maxRedirects: 3,
            timeoutMs: 10000,
            pdf: {
              maxPages: 4,
              maxPixels: 4000000,
              minTextChars: 200,
            },
          },
          images: {
            allowUrl: true,
            allowedMimes: ["image/jpeg", "image/png", "image/gif", "image/webp"],
            maxBytes: 10485760,
            maxRedirects: 3,
            timeoutMs: 10000,
          },
        },
      },
    },
  },
}

省略時的默认：

- ''maxBodyBytes''：20MB

- ''files.maxBytes''：5MB

- ''files.maxChars''：200k

- ''files.maxRedirects''：3

- ''files.timeoutMs''：10秒

- ''files.pdf.maxPages''：4

- ''files.pdf.maxPixels''：4,000,000

- ''files.pdf.minTextChars''：200

- ''images.maxBytes''：10MB

- ''images.maxRedirects''：3

- ''images.timeoutMs''：10秒

Tutorial.step

流媒体 (SSE)

Set ''stream: true'' to receive Server-Sent Events (SSE):

- ''Content-Type: text/event-stream''

- 每个活动行是 ''event: <type>'' 和 ''data: <json>''

- Stream ends with ''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.failed''（错误時）

Tutorial.step

使用法

''usage'' is populated when the underlying provider reports token counts.

Tutorial.step

错误

错误是 JSON 对象使用执行。示示例：

Json
{ "error": { "message": "...", "type": "invalid_request_error" } }

Common cases:

- ''401'' missing/invalid auth

- ''400'' 请求正文但禁用

- ''405'' wrong method

Tutorial.step

例

非流媒体：

Bash
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"
  }

流媒体：

Bash
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"
  }