OpenResponses API (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''

- Same port as the Gateway (WS + HTTP multiplex): ''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.

Uses the Gateway auth configuration. Send a bearer token:

- ''Authorization: Bearer <token>''

Notes:

- When ''gateway.auth.mode="token"'', use ''gateway.auth.token'' (or ''OPENCLAW_GATEWAY_TOKEN'').

- When ''gateway.auth.mode="password"'', use ''gateway.auth.password'' (or ''OPENCLAW_GATEWAY_PASSWORD'').

No custom headers required: encode the agent id in the OpenResponses ''model'' field:

- ''model: "openclaw:<agentId>"'' (example: ''"openclaw:main"'', ''"openclaw:beta"'')

- ''model: "agent:<agentId>"''（Aliases）

Or target a specific OpenClaw agent by header:

- ''x-openclaw-agent-id: <agentId>''（Defaults:''main''）

Advanced:

- ''x-openclaw-session-key: '''' to fully control session routing.

Set ''gateway.http.endpoints.responses.enabled'' to ''true'':

{
  gateway: {
    http: {
      endpoints: {
        responses: { enabled: true },
      },
    },
  },
}

Set ''gateway.http.endpoints.responses.enabled'' to ''false'':

{
  gateway: {
    http: {
      endpoints: {
        responses: { enabled: false },
      },
    },
  },
}

By default the endpoint is stateless per request (a new session key is generated each call).

If the request includes an OpenResponses ''user'' string, the Gateway derives a stable session key from it, so repeated calls can share an agent session.

Requests follow the OpenResponses API with item-based input. Currently supported:

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

- ''instructions'': will be merged into system prompt.

- ''tools'': client tool definitions (function tools).

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

- ''stream'': enable SSE streaming.

- ''max_output_tokens'': best-effort output limit (provider-dependent).

- ''user'': stable session routing.

Accepted but currently ignored:

- ''max_tool_calls''

- ''reasoning''

- ''metadata''

- ''store''

- ''previous_response_id''

- ''truncation''

#

role: ''system'', ''developer'', ''user'', ''assistant''.

- ''system'' and ''developer'' are added after the system prompt.

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

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

#

Send tool results back to the model:

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

#

Accepted for compatibility but ignored when constructing the prompt.

Provide tools via tools: [{ type: "function", function: { name, description?, parameters? } }].

If the agent decides to call a tool, the response returns a ''function_call'' output item.

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

Supports base64 or URL sources:

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

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

Max size (current): 10MB.

Supports base64 or URL sources:

{
  "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''.

Max size (current): 5MB.

Current behavior:

- 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).

Defaults can be tuned under ''gateway.http.endpoints.responses'':

{
  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,
          },
        },
      },
    },
  },
}

Defaults when omitted:

- ''maxBodyBytes''：20MB

- ''files.maxBytes''：5MB

- ''files.maxChars''：200k

- ''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

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

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

- Each event line is ''event: <type>'' and ''data: <json>''

- Stream ends with ''data: [DONE]''

Event types currently emitted:

- ''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'' (on error)

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

Errors use a JSON object. Example:

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

Common cases:

- ''401'' missing/invalid auth

- ''400'' invalid request body

- ''405'' wrong method

Non-streaming:

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

Streaming:

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