OpenClaw OpenResponses API

The OpenResponses surface is the second HTTP door into an OpenClaw gateway. It shares its port, its auth rules and its agent-first model contract with the chat completions endpoint, but it takes item-based input, returns function calls as output items and accepts files. Here is what the docs say it does, with the limits that apply.

Enabling and trusting it

• The responses endpoint setting turns on the responses route on the gateway port and, with it, the models list, a single-model lookup and embeddings; chat completions is enabled separately, and every request runs as a normal gateway agent run so routing, permissions and config match the gateway.
• Auth follows the gateway mode: bearer token or password for shared-secret modes, identity-aware proxy headers for trusted-proxy (same-host loopback proxies need the loopback opt-in, with a direct password fallback when no forwarded header is present), no header for none on private ingress; the endpoint is full operator access, shared-secret modes ignore a narrower declared scope header and restore the default operator scope set, and identity-bearing modes honor the header when present.
• Agents are selected with model set to openclaw, openclaw/default, openclaw/ plus the agent id, or the agent-id header; the model header overrides the backend model (admin on identity-bearing paths), the session-key header routes explicitly and is rejected with a 400 in the reserved subagent, cron and acp namespaces, and the message-channel header sets a synthetic ingress channel.
• The endpoint is stateless per request by default; a user string derives a stable session key, and previous_response_id reuses the earlier response session when the request stays within the same agent, user and requested-session scope, matched by auth subject, agent id and the session-key header; continuing an incognito session explicitly needs effective admin authority and otherwise returns a 403 forbidden that hides the target.

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

Items, tools and files

The input field is a string or an array of items. Message items carry the system, developer, user and assistant roles: system and developer are appended to the system prompt, the most recent user or function_call_output item becomes the current message, and earlier turns are history. Instructions merge into the system prompt; tools are client function tools, the tool choice takes auto, none, required or a named function, the output-token cap is best-effort, temperature and top_p are best-effort and ignored by the ChatGPT-based Codex Responses backend, and the tool-call cap, reasoning, metadata, store and truncation are accepted but ignored. When the agent calls a tool, the response returns a function_call output item and the client continues the turn with a function_call_output carrying the call id; an empty output still completes the call. Clients that keep their own history append the response output to the next input unchanged, or send previous_response_id with only the new items. A required or pinned tool choice that yields no matching call returns a 502 api_error, or a failed response event when streaming.

Files, images and limits

• Image items accept base64 or URL sources with JPEG, PNG, GIF, WebP, HEIC and HEIF allowed by default and 10 MB per image, HEIC and HEIF normalized to JPEG; file items accept base64 or URL with plain text, markdown, HTML, CSV, JSON and PDF allowed by default, 5 MB and 60k characters, text decoded with its detected encoding, and PDFs parsed for text first with the first pages rasterized into images when little text is found (4 pages, 4 million pixels, 200 characters minimum by default).
• Decoded file text is wrapped as untrusted external content with explicit boundary markers and a source line before it enters the prompt, so file bytes are data rather than instructions; URL fetches are on by default for files and images with 8 URL parts per request, guarded by DNS resolution, private address blocking, redirect caps and timeouts, and optional per-type hostname allowlists that take exact hosts or wildcard subdomains and are enforced before fetch and on every redirect hop.
• The request body is capped at 20 MB; with streaming on, the events are typed (created, in progress, output item added, content part added, output text delta and done, output item done, completed, incomplete on output-budget truncation and failed on error) and end with DONE; a reply cut by the output-token budget returns an incomplete status with the max output tokens reason, usage is populated when the provider reports counts, and errors are 400, 401, 403 for a missing scope, 405 and 429 with a retry header after too many failed auth attempts.

OpenClaw OpenAI-compatible HTTP API is the sibling endpoint whose model contract this one reuses and OpenClaw operator scopes explains the scope set both restore or narrow.

When to reach for it

The item model fits clients that already keep their own conversation history and want to replay it verbatim, or that need to hand files and images to an agent without persisting them in the session. The chat completions endpoint fits tools that only know the older shape. Both run the same agent run underneath, so the choice is about the client, not the agent. The OpenClaw API covers the wider gateway API and OpenClaw web fetch what the agent itself does with URLs once a request reaches it.

On Diali

On Diali the gateway sits behind the platform ingress with the runtime configuration generated from the dashboard and replaced at each release, so enabling either HTTP surface is a configuration decision rather than a port to open. Hosted OpenClaw on Diali describes the hosted assistant and Diali pricing the plans it ships in.

• Items in, function calls out, results back as function_call_output.
• Files land in the system prompt as untrusted content.
• Same port, same auth, same owner-level trust as chat completions.