OpenResponses API

기준일: 2026-07-26
공식 기준: OpenResponses API

OpenResponses API 문서는 OpenClaw 공식 문서(gateway/openresponses-http-api)를 한국어로 정리한 가이드입니다. Expose an OpenResponses-compatible /v1/responses HTTP endpoint from the Gateway 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Expose an OpenResponses-compatible /v1/responses HTTP endpoint from the Gateway

한국어 가이드 범위: gateway/openresponses-http-api 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

• Authentication, security, and routing
• Session behavior
• Request shape
• Items (input)
• message
• function_call_output (turn-based tools)
• reasoning and item_reference
• Tools (client-side function tools)
• Images (input_image)
• Files (input_file)
• File + image limits
• Streaming (SSE)
• 사용법
• Errors
• 예제
• 관련 문서

상세 내용

본문

The Gateway can serve an OpenResponses-compatible POST /v1/responses endpoint. It is disabled by default and shares its port with the Gateway (WS + HTTP multiplex): http://:/v1/responses.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Authentication, security, and routing

Operational behavior matches OpenAI Chat Completions:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• 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

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

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Request shape

Field	Support
input	String or array of item objects.
instructions	Merged into the system prompt.
tools	Client tool definitions (function tools).
tool_choice	"auto", "none", "required", or { "type": "function", "name": "..." } to filter or require client tools.
stream	Enables SSE streaming.
max_output_tokens	Best-effort output limit (provider dependent).
temperature	Best-effort sampling temperature. Ignored by the ChatGPT-based Codex Responses backend, which uses fixed server-side sampling.
top_p	Best-effort nucleus sampling. Same Codex Responses caveat as temperature.
user	Stable session routing.
previous_response_id	Session continuity (see above).
max_tool_calls, reasoning, metadata, store, truncation	Accepted but currently ignored.

Items (input)

이 섹션의 세부 항목은 공식 문서 Items (input)를 참고하세요.

message

Roles: system, developer, user, assistant.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• 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

Accepted for schema compatibility but ignored when building the prompt.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Tools (client-side function tools)

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

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Images (input_image)

Allowed MIME types (default): image/jpeg, image/png, image/gif, image/webp, image/heic, image/heif. Max size (default): 10MB.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

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

Files (input_file)

Allowed MIME types (default): text/plain, text/markdown, text/html, text/csv, application/json, application/pdf. Max size (default): 5MB.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

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

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

File + image limits

The endpoint uses a built-in 20 MB request-body limit. File and image source policy remains configurable under gateway.http.endpoints.responses:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Key	Default
maxUrlParts	8
files.maxBytes	5MB
files.maxChars	60k
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

{
  gateway: {
    http: {
      endpoints: {
        responses: {
          enabled: true,
          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)

Set stream: true to receive Server-Sent Events:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

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

사용법

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 input_tokens / output_tokens and prompt_tokens / completion_tokens.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Errors

Common cases: 400 invalid request body, 401 missing/invalid auth, 403 missing operator scope, 405 wrong method, 429 too many failed auth attempts (with Retry-After).

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

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

예제

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

관련 문서

주요 항목:

• OpenAI chat completions
• Operator scopes
• OpenAI

실습 체크리스트

1. 공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/gateway/openresponses-http-api
2. 관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
3. 설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
4. Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

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

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

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

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

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

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

관련 링크

• 공식 원문: gateway/openresponses-http-api
• OpenClaw 문서 홈

이 가이드는 공식 문서를 한국어 학습용으로 재구성한 것입니다. 옵션 기본값·플래그 이름은 설치 버전에 따라 달라질 수 있습니다.