Use this file to discover all available pages before exploring further.

OpenResponses API

OpenClaw’s Gateway can serve an OpenResponses-compatible

text

POST /v1/responses

endpoint.

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

text
POST /v1/responses
Same port as the Gateway (WS + HTTP multiplex):
text
http://<gateway-host>:<port>/v1/responses

Under the hood, requests are executed as a normal Gateway agent run (same codepath as

text

openclaw agent

), so routing/permissions/config match your Gateway.

Authentication, security, and routing

Operational behavior matches OpenAI Chat Completions:

use the matching Gateway HTTP auth path:
- shared-secret auth (
  text
  gateway.auth.mode="token"
  or
  text
  "password"
  ):
  text
  Authorization: Bearer <token-or-password>
- trusted-proxy auth (
  text
  gateway.auth.mode="trusted-proxy"
  ): identity-aware proxy headers from a configured trusted proxy source; same-host loopback proxies require explicit
  text
  gateway.auth.trustedProxy.allowLoopback = true
- private-ingress open auth (
  text
  gateway.auth.mode="none"
  ): no auth header
treat the endpoint as full operator access for the gateway instance
for shared-secret auth modes (
text
token
and
text
password
), ignore narrower bearer-declared
text
x-openclaw-scopes
values and restore the normal full operator defaults
for trusted identity-bearing HTTP modes (for example trusted proxy auth or
text
gateway.auth.mode="none"
), honor
text
x-openclaw-scopes
when present and otherwise fall back to the normal operator default scope set
select agents with
text
model: "openclaw"
,
text
model: "openclaw/default"
,
text
model: "openclaw/<agentId>"
, or
text
x-openclaw-agent-id
use
text
x-openclaw-model
when you want to override the selected agent's backend model
use
text
x-openclaw-session-key
for explicit session routing
use
text
x-openclaw-message-channel
when you want a non-default synthetic ingress channel context

Auth matrix:

text
gateway.auth.mode="token"
or
text
"password"
+
text
Authorization: Bearer ...
- proves possession of the shared gateway operator secret
- ignores narrower
  text
  x-openclaw-scopes
- restores the full default operator scope set:
  text
  operator.admin
  ,
  text
  operator.approvals
  ,
  text
  operator.pairing
  ,
  text
  operator.read
  ,
  text
  operator.talk.secrets
  ,
  text
  operator.write
- treats chat turns on this endpoint as owner-sender turns
trusted identity-bearing HTTP modes (for example trusted proxy auth, or
text
gateway.auth.mode="none"
on private ingress)
- honor
  text
  x-openclaw-scopes
  when the header is present
- fall back to the normal operator default scope set when the header is absent
- only lose owner semantics when the caller explicitly narrows scopes and omits
  text
  operator.admin

Enable or disable this endpoint with

text

gateway.http.endpoints.responses.enabled

The same compatibility surface also includes:

text
GET /v1/models
text
GET /v1/models/{id}
text
POST /v1/embeddings
text
POST /v1/chat/completions

For the canonical explanation of how agent-target models,

text

openclaw/default

, embeddings pass-through, and backend model overrides fit together, see OpenAI Chat Completions and Model list and agent routing.

Session behavior

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

If the request includes an OpenResponses

text

user

string, the Gateway derives a stable session key from it, so repeated calls can share an agent session.

Request shape (supported)

The request follows the OpenResponses API with item-based input. Current support:

text
input
: string or array of item objects.
text
instructions
: merged into the system prompt.
text
tools
: client tool definitions (function tools).
text
tool_choice
: filter or require client tools.
text
stream
: enables SSE streaming.
text
max_output_tokens
: best-effort output limit (provider dependent).
text
user
: stable session routing.

Accepted but currently ignored:

text
max_tool_calls
text
reasoning
text
metadata
text
store
text
truncation

Supported:

text
previous_response_id
: OpenClaw reuses the earlier response session when the request stays within the same agent/user/requested-session scope.

Items (input)

text
`message`

Roles:

text

system

text

developer

text

user

text

assistant

text
system
and
text
developer
are appended to the system prompt.
The most recent
text
user
or
text
function_call_output
item becomes the “current message.”
Earlier user/assistant messages are included as history for context.

text
`function_call_output`
(turn-based tools)

Send tool results back to the model:


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

text
`reasoning`
and
text
`item_reference`

Accepted for schema compatibility but ignored when building the prompt.

Tools (client-side function tools)

Provide tools with

text

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

If the agent decides to call a tool, the response returns a

text

function_call

output item. You then send a follow-up request with

text

function_call_output

to continue the turn.

Images (
text
`input_image`
)

Supports base64 or URL sources:


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

Allowed MIME types (current):

text

image/jpeg

text

image/png

text

image/gif

text

image/webp

text

image/heic

text

image/heif

. Max size (current): 10MB.

Files (
text
`input_file`
)

Supports base64 or URL sources:


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

Allowed MIME types (current):

text

text/plain

text

text/markdown

text

text/html

text

text/csv

text

application/json

text

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).
Decoded file text is wrapped as untrusted external content before it is added, so file bytes are treated as data, not trusted instructions.
The injected block uses explicit boundary markers like
text
<<<EXTERNAL_UNTRUSTED_CONTENT id="...">>>
/
text
<<<END_EXTERNAL_UNTRUSTED_CONTENT id="...">>>
and includes a
text
Source: External
metadata line.
This file-input path intentionally omits the long
text
SECURITY NOTICE:
banner to preserve prompt budget; the boundary markers and metadata still stay in place.
PDFs are parsed for text first. If little text is found, the first pages are rasterized into images and passed to the model, and the injected file block uses the placeholder
text
[PDF content rendered to images]
.

PDF parsing is provided by the bundled

text

document-extract

plugin, which uses the Node-friendly

text

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:

text
files.allowUrl
:
text
true
text
images.allowUrl
:
text
true
text
maxUrlParts
:
text
8
(total URL-based
text
input_file
+
text
input_image
parts per request)
Requests are guarded (DNS resolution, private IP blocking, redirect caps, timeouts).
Optional hostname allowlists are supported per input type (
text
files.urlAllowlist
,
text
images.urlAllowlist
).
- Exact host:
  text
  "cdn.example.com"
- Wildcard subdomains:
  text
  "*.assets.example.com"
  (does not match apex)
- Empty or omitted allowlists mean no hostname allowlist restriction.
To disable URL-based fetches entirely, set
text
files.allowUrl: false
and/or
text
images.allowUrl: false
.

File + image limits (config)

Defaults can be tuned under

text

gateway.http.endpoints.responses


json5
{
  gateway: {
    http: {
      endpoints: {
        responses: {
          enabled: true,
          maxBodyBytes: 20000000,
          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: 200000,
            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,
          },
        },
      },
    },
  },
}

Defaults when omitted:

text
maxBodyBytes
: 20MB
text
maxUrlParts
: 8
text
files.maxBytes
: 5MB
text
files.maxChars
: 200k
text
files.maxRedirects
: 3
text
files.timeoutMs
: 10s
text
files.pdf.maxPages
: 4
text
files.pdf.maxPixels
: 4,000,000
text
files.pdf.minTextChars
: 200
text
images.maxBytes
: 10MB
text
images.maxRedirects
: 3
text
images.timeoutMs
: 10s
HEIC/HEIF
text
input_image
sources are accepted and normalized to JPEG before provider delivery.

Security note:

URL allowlists are enforced before fetch and on redirect hops.
Allowlisting a hostname does not bypass private/internal IP blocking.
For internet-exposed gateways, apply network egress controls in addition to app-level guards. See Security.

Streaming (SSE)

Set

text

stream: true

to receive Server-Sent Events (SSE):

text
Content-Type: text/event-stream
Each event line is
text
event: <type>
and
text
data: <json>
Stream ends with
text
data: [DONE]

Event types currently emitted:

text
response.created
text
response.in_progress
text
response.output_item.added
text
response.content_part.added
text
response.output_text.delta
text
response.output_text.done
text
response.content_part.done
text
response.output_item.done
text
response.completed
text
response.failed
(on error)

Usage

text

usage

is populated when the underlying provider reports token counts. OpenClaw normalizes common OpenAI-style aliases before those counters reach downstream status/session surfaces, including

text

input_tokens

text

output_tokens

and

text

prompt_tokens

text

completion_tokens

Errors

Errors use a JSON object like:


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

Common cases:

text
401
missing/invalid auth
text
400
invalid request body
text
405
wrong method

Examples

Non-streaming:


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

Streaming:


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

OpenClaw Docs

OpenResponses API

Authentication, security, and routing

Session behavior

Request shape (supported)

Items (input)

text
`message`

text
`function_call_output`
(turn-based tools)

text
`reasoning`
and
text
`item_reference`

Tools (client-side function tools)

Images (
text
`input_image`
)

Files (
text
`input_file`
)

File + image limits (config)

Streaming (SSE)

Usage

Errors

Examples

Related

OpenClaw Docs

OpenResponses API

Authentication, security, and routing

Session behavior

Request shape (supported)

Items (input)

textCopymessage

textCopyfunction_call_output (turn-based tools)

textCopyreasoning and textCopyitem_reference

Tools (client-side function tools)

Images (textCopyinput_image)

Files (textCopyinput_file)

File + image limits (config)

Streaming (SSE)

Usage

Errors

Examples

Related

text
`message`

text
`function_call_output`
(turn-based tools)

text
`reasoning`
and
text
`item_reference`

Images (
text
`input_image`
)

Files (
text
`input_file`
)