OpenResponses API

​

Authentication, security, and routing

• Auth path matches gateway.auth.mode: shared-secret (token/password) uses Authorization: Bearer <token-or-password>; trusted-proxy uses identity-aware proxy headers (same-host loopback proxies need gateway.auth.trustedProxy.allowLoopback = true, with a same-host direct fallback via gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD when no Forwarded/X-Forwarded-*/X-Real-IP header is present); none on private ingress needs no auth header. See Trusted proxy auth.
• Treat the endpoint as full operator access to the gateway instance.
• Shared-secret auth modes ignore a narrower bearer-declared x-openclaw-scopes and restore the full default operator scope set: operator.admin, operator.approvals, operator.pairing, operator.read, operator.talk.secrets, operator.write. Chat turns on this endpoint are treated as owner-sender turns.
• Trusted identity-bearing HTTP modes (trusted-proxy, or gateway.auth.mode="none") honor x-openclaw-scopes when present, otherwise fall back to the operator default scope set. Owner semantics are lost only when the caller explicitly narrows scopes and omits operator.admin.
• Select agents with model: "openclaw", "openclaw/default", "openclaw/<agentId>", or the x-openclaw-agent-id header.
• Use x-openclaw-model to override the selected agent’s backend model (requires operator.admin on identity-bearing auth paths).
• Use x-openclaw-session-key for explicit session routing (rejected with 400 invalid_request_error if it uses a reserved namespace: subagent:, cron:, acp:).
• Use x-openclaw-message-channel for a non-default synthetic ingress channel context.

​

Session behavior

​

Request shape

​

Items (input)

​

message

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

​

function_call_output (turn-based tools)

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

​

reasoning and item_reference

​

Tools (client-side function tools)

​

Images (input_image)

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

​

Files (input_file)

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

• 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 (<<<EXTERNAL_UNTRUSTED_CONTENT id="...">>> / <<<END_EXTERNAL_UNTRUSTED_CONTENT id="...">>>) and a Source: External metadata line. It intentionally omits the long SECURITY NOTICE: banner to preserve prompt budget; the boundary markers and metadata still apply.
• 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 [PDF content rendered to images].

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

​

File + image limits (config)

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

​

Streaming (SSE)

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

​

Usage

​

Errors

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

​

Examples

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

​

Related

• OpenAI chat completions
• Operator scopes
• OpenAI