OpenResponses API

Gateway는 OpenResponses 호환 POST /v1/responses 엔드포인트를 제공할 수 있습니다. 이 엔드포인트는 기본적으로 비활성화되어 있으며, Gateway와 포트를 공유합니다(WS + HTTP 멀티플렉싱): http://<gateway-host>:<port>/v1/responses.

요청은 일반적인 Gateway 에이전트 실행과 동일하게 처리되므로(openclaw agent와 동일한 코드 경로), 라우팅, 권한 및 구성은 Gateway와 일치합니다.

gateway.http.endpoints.responses.enabled로 활성화하거나 비활성화합니다. 활성화하면 동일한 호환성 인터페이스에서 GET /v1/models, GET /v1/models/{id}, POST /v1/embeddings, POST /v1/chat/completions도 제공합니다.

인증, 보안 및 라우팅

작동 방식은 OpenAI Chat Completions와 동일합니다.

• 인증 경로는 gateway.auth.mode와 일치합니다. 공유 비밀(token/password)은 Authorization: Bearer <token-or-password>를 사용하고, 신뢰할 수 있는 프록시는 ID 인식 프록시 헤더를 사용합니다(동일 호스트의 local loopback 프록시는 gateway.auth.trustedProxy.allowLoopback = true가 필요하며, Forwarded/X-Forwarded-*/X-Real-IP 헤더가 없을 때 gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD를 통한 동일 호스트 직접 폴백을 사용함). 비공개 인그레스에서 none을 사용하면 인증 헤더가 필요하지 않습니다. 신뢰할 수 있는 프록시 인증을 참조하세요.
• 이 엔드포인트는 Gateway 인스턴스에 대한 전체 운영자 액세스 권한을 제공하는 것으로 취급하세요.
• 공유 비밀 인증 모드는 베어러가 선언한 더 좁은 범위의 x-openclaw-scopes를 무시하고 전체 기본 운영자 범위 집합인 operator.admin, operator.approvals, operator.pairing, operator.read, operator.talk.secrets, operator.write를 복원합니다. 이 엔드포인트의 채팅 턴은 소유자가 보낸 턴으로 취급됩니다.
• 신뢰할 수 있는 ID가 포함된 HTTP 모드(신뢰할 수 있는 프록시 또는 gateway.auth.mode="none")에서는 x-openclaw-scopes가 있으면 이를 따르고, 그렇지 않으면 기본 운영자 범위 집합을 사용합니다. 호출자가 명시적으로 범위를 좁히면서 operator.admin을 제외한 경우에만 소유자 의미 체계가 사라집니다.
• model: "openclaw", "openclaw/default", "openclaw/<agentId>" 또는 x-openclaw-agent-id 헤더를 사용하여 에이전트를 선택합니다.
• 선택한 에이전트의 백엔드 모델을 재정의하려면 x-openclaw-model을 사용합니다(ID가 포함된 인증 경로에서는 operator.admin 필요).
• 명시적 세션 라우팅에는 x-openclaw-session-key를 사용합니다(예약된 네임스페이스 subagent:, cron:, acp:를 사용하면 400 invalid_request_error로 거부됨).
• 기본값이 아닌 합성 인그레스 채널 컨텍스트에는 x-openclaw-message-channel을 사용합니다.

에이전트 대상 모델, openclaw/default, 임베딩 패스스루 및 백엔드 모델 재정의에 대한 표준 설명은 OpenAI Chat Completions을 참조하세요.

운영자 범위 및 보안을 참조하세요.

세션 동작

기본적으로 이 엔드포인트는 요청별로 상태를 유지하지 않습니다(호출할 때마다 새 세션 키가 생성됨).

요청에 OpenResponses user 문자열이 포함된 경우 Gateway는 이 문자열에서 안정적인 세션 키를 파생하므로 반복 호출에서 에이전트 세션을 공유할 수 있습니다.

요청이 동일한 에이전트/사용자/요청 세션 범위에 머무르면(인증 주체, 에이전트 ID 및 x-openclaw-session-key로 일치 여부 확인) previous_response_id가 이전 응답의 세션을 재사용합니다.

요청 형식

항목(입력)

message

역할: system, developer, user, assistant.

• system과 developer는 시스템 프롬프트에 추가됩니다.
• 가장 최근의 user 또는 function_call_output 항목이 "현재 메시지"가 됩니다.
• 이전 사용자/어시스턴트 메시지는 컨텍스트를 위한 기록으로 포함됩니다.

function_call_output(턴 기반 도구)

도구 결과를 모델에 다시 전송합니다.

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

reasoning 및 item_reference

스키마 호환성을 위해 허용되지만 프롬프트를 구성할 때는 무시됩니다.

도구(클라이언트 측 함수 도구)

tools: [{ type: "function", name, description?, parameters? }] 형식으로 도구를 제공합니다.

에이전트가 도구를 호출하면 응답에서 function_call 출력 항목을 반환합니다. 턴을 계속하려면 function_call_output이 포함된 후속 요청을 보내세요.

tool_choice: "required" 및 함수가 고정된 tool_choice의 경우, 엔드포인트는 노출되는 클라이언트 함수 도구 집합을 좁히고, 응답하기 전에 클라이언트 도구를 호출하도록 런타임에 지시하며, 일치하는 구조화된 클라이언트 도구 호출이 턴에 포함되지 않으면 /v1/chat/completions 계약과 동일하게 해당 턴을 거부합니다. 비스트리밍 요청은 api_error와 함께 502를 반환하고, 스트리밍 요청은 response.failed 이벤트를 내보냅니다.

이미지(input_image)

base64 또는 URL 소스를 지원합니다.

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

허용되는 MIME 유형(기본값): image/jpeg, image/png, image/gif, image/webp, image/heic, image/heif. 최대 크기(기본값): 10MB.

파일(input_file)

base64 또는 URL 소스를 지원합니다.

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

허용되는 MIME 유형(기본값): text/plain, text/markdown, text/html, text/csv, application/json, application/pdf. 최대 크기(기본값): 5MB.

현재 동작:

• 파일 콘텐츠는 디코딩되어 사용자 메시지가 아닌 시스템 프롬프트에 추가되므로 일시적으로만 유지됩니다(세션 기록에는 저장되지 않음).
• 디코딩된 파일 텍스트는 추가되기 전에 신뢰할 수 없는 외부 콘텐츠로 감싸지므로 파일 바이트는 신뢰할 수 있는 지침이 아닌 데이터로 취급됩니다. 삽입된 블록은 명시적인 경계 마커(<<&lt;EXTERNAL_UNTRUSTED_CONTENT id=&quot;...&quot;&gt;>> / <<&lt;END_EXTERNAL_UNTRUSTED_CONTENT id=&quot;...&quot;&gt;>>)와 Source: External 메타데이터 줄을 사용합니다. 프롬프트 예산을 보존하기 위해 긴 SECURITY NOTICE: 배너는 의도적으로 생략하지만 경계 마커와 메타데이터는 그대로 적용됩니다.
• PDF는 먼저 텍스트를 추출합니다. 텍스트가 거의 없으면 첫 페이지들을 이미지로 래스터화하여 모델에 전달하며, 삽입된 파일 블록에서는 자리표시자 [PDF content rendered to images]를 사용합니다.

PDF 구문 분석은 번들 document-extract Plugin에서 제공하며, 이 Plugin은 텍스트 추출과 페이지 렌더링을 위해 clawpdf 및 패키지에 포함된 PDFium WebAssembly 런타임을 사용합니다.

URL 가져오기 기본값:

• files.allowUrl: true
• images.allowUrl: true
• maxUrlParts: 8(요청당 URL 기반 input_file + input_image 부분의 총합)
• 요청에는 보호 조치가 적용됩니다(DNS 확인, 비공개 IP 차단, 리디렉션 횟수 제한, 시간 제한).
• 입력 유형별로 선택적 호스트 이름 허용 목록(files.urlAllowlist, images.urlAllowlist)을 지원합니다. 정확한 호스트("cdn.example.com") 또는 와일드카드 하위 도메인("*.assets.example.com", 최상위 도메인 자체와는 일치하지 않음)을 사용할 수 있습니다. 허용 목록이 비어 있거나 생략되면 호스트 이름 허용 목록 제한이 없습니다.
• URL 기반 가져오기를 완전히 비활성화하려면 files.allowUrl: false 및/또는 images.allowUrl: false를 설정합니다.

파일 + 이미지 제한(구성)

기본값은 gateway.http.endpoints.responses에서 조정할 수 있습니다.

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

생략 시 기본값:

HEIC/HEIF input_image 소스는 공유 OpenClaw 이미지 프로세서(Rastermill)를 통해 제공자에게 전달되기 전에 JPEG로 정규화됩니다. 외부 코덱 지원이 필요한 형식의 경우 시스템 변환기(sips, ImageMagick, GraphicsMagick 또는 ffmpeg)로 폴백합니다.

보안 참고: URL 허용 목록은 가져오기 전과 리디렉션 단계마다 적용됩니다. 호스트 이름을 허용 목록에 추가해도 비공개/내부 IP 차단을 우회하지 않습니다. 인터넷에 노출된 Gateway의 경우 애플리케이션 수준 보호 조치와 함께 네트워크 이그레스 제어를 적용하세요. 보안을 참조하세요.

스트리밍(SSE)

Server-Sent Events를 수신하려면 stream: true로 설정합니다.

• Content-Type: text/event-stream
• 각 이벤트 줄은 event: <type> 및 data: <json> 형식입니다
• 스트림은 data: [DONE]으로 종료됩니다

현재 생성되는 이벤트 유형: 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(오류 발생 시).

사용량

기본 제공자가 토큰 수를 보고하면 usage가 채워집니다. OpenClaw는 이러한 카운터가 하위 상태/세션 표면에 전달되기 전에 input_tokens / output_tokens 및 prompt_tokens / completion_tokens를 비롯한 일반적인 OpenAI 스타일 별칭을 정규화합니다.

오류

오류는 다음과 같은 JSON 객체를 사용합니다.

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

일반적인 경우: 400 잘못된 요청 본문, 401 인증 누락/잘못된 인증, 403 운영자 범위 누락, 405 잘못된 메서드, 429 인증 실패 횟수 초과(Retry-After 포함).

예시

비스트리밍:

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 채팅 완성
• 운영자 범위
• OpenAI