OpenResponses API

• POST /v1/responses
• Gateway जैसा ही पोर्ट (WS + HTTP मल्टीप्लेक्स): http://<gateway-host>:<port>/v1/responses

​

प्रमाणीकरण, सुरक्षा, और रूटिंग

• मिलते-जुलते Gateway HTTP प्रमाणीकरण पथ का उपयोग करें:
  • साझा-गुप्त प्रमाणीकरण (gateway.auth.mode="token" या "password"): Authorization: Bearer <token-or-password>
  • विश्वसनीय-प्रॉक्सी प्रमाणीकरण (gateway.auth.mode="trusted-proxy"): कॉन्फ़िगर किए गए विश्वसनीय प्रॉक्सी स्रोत से पहचान-जागरूक प्रॉक्सी हेडर; same-host लूपबैक प्रॉक्सी के लिए स्पष्ट gateway.auth.trustedProxy.allowLoopback = true चाहिए
  • विश्वसनीय-प्रॉक्सी स्थानीय सीधा फ़ॉलबैक: बिना Forwarded, X-Forwarded-*, या X-Real-IP हेडर वाले same-host कॉलर gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD का उपयोग कर सकते हैं
  • निजी-इनग्रेस खुला प्रमाणीकरण (gateway.auth.mode="none"): कोई प्रमाणीकरण हेडर नहीं
• एंडपॉइंट को Gateway इंस्टेंस के लिए पूर्ण ऑपरेटर एक्सेस मानें
• साझा-गुप्त प्रमाणीकरण मोड (token और password) के लिए, संकरे bearer-घोषित x-openclaw-scopes मानों को अनदेखा करें और सामान्य पूर्ण ऑपरेटर डिफ़ॉल्ट वापस लाएं
• विश्वसनीय पहचान-युक्त HTTP मोड के लिए (उदाहरण के लिए विश्वसनीय प्रॉक्सी प्रमाणीकरण या gateway.auth.mode="none"), मौजूद होने पर x-openclaw-scopes का सम्मान करें और अन्यथा सामान्य ऑपरेटर डिफ़ॉल्ट स्कोप सेट पर फ़ॉलबैक करें
• एजेंट चुनें model: "openclaw", model: "openclaw/default", model: "openclaw/<agentId>", या x-openclaw-agent-id से
• जब आप चुने गए एजेंट के बैकएंड मॉडल को ओवरराइड करना चाहते हैं, तो x-openclaw-model का उपयोग करें
• स्पष्ट सत्र रूटिंग के लिए x-openclaw-session-key का उपयोग करें
• जब आप गैर-डिफ़ॉल्ट कृत्रिम इनग्रेस चैनल संदर्भ चाहते हैं, तो x-openclaw-message-channel का उपयोग करें

• gateway.auth.mode="token" या "password" + Authorization: Bearer ...
  • साझा Gateway ऑपरेटर गुप्त के कब्जे को सिद्ध करता है
  • संकरे x-openclaw-scopes को अनदेखा करता है
  • पूर्ण डिफ़ॉल्ट ऑपरेटर स्कोप सेट वापस लाता है: operator.admin, operator.approvals, operator.pairing, operator.read, operator.talk.secrets, operator.write
  • इस एंडपॉइंट पर चैट टर्न को स्वामी-प्रेषक टर्न मानता है
• विश्वसनीय पहचान-युक्त HTTP मोड (उदाहरण के लिए विश्वसनीय प्रॉक्सी प्रमाणीकरण, या निजी इनग्रेस पर gateway.auth.mode="none")
  • हेडर मौजूद होने पर x-openclaw-scopes का सम्मान करते हैं
  • हेडर अनुपस्थित होने पर सामान्य ऑपरेटर डिफ़ॉल्ट स्कोप सेट पर फ़ॉलबैक करते हैं
  • स्वामी semantics केवल तब खोते हैं जब कॉलर स्पष्ट रूप से स्कोप संकरे करता है और operator.admin छोड़ देता है

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

​

सत्र व्यवहार

​

अनुरोध आकार (समर्थित)

• input: स्ट्रिंग या item ऑब्जेक्ट की array.
• instructions: सिस्टम prompt में merge किया जाता है.
• tools: client tool परिभाषाएं (function tools).
• tool_choice: client tools को फ़िल्टर या आवश्यक करने के लिए "auto", "none", "required", या { "type": "function", "name": "..." }.
• stream: SSE streaming सक्षम करता है.
• max_output_tokens: best-effort output सीमा (provider पर निर्भर).
• temperature: provider को forward किया गया best-effort sampling temperature. ChatGPT-आधारित Codex Responses backend द्वारा अनदेखा किया जाता है, जो fixed server-side sampling का उपयोग करता है.
• top_p: provider को forward किया गया best-effort nucleus sampling. temperature जैसी ही Codex Responses सावधानी लागू है.
• user: स्थिर सत्र रूटिंग.

• max_tool_calls
• reasoning
• metadata
• store
• truncation

• previous_response_id: जब अनुरोध उसी एजेंट/user/अनुरोधित-सत्र scope में रहता है, OpenClaw पहले के response सत्र को फिर से उपयोग करता है.

​

Items (इनपुट)

​

message

• system और developer सिस्टम prompt में जोड़े जाते हैं.
• सबसे हाल का user या function_call_output item “वर्तमान संदेश” बनता है.
• पहले के user/assistant संदेश संदर्भ के लिए history के रूप में शामिल किए जाते हैं.

​

function_call_output (turn-आधारित tools)

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

​

reasoning और 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 decode किया जाता है और system prompt में जोड़ा जाता है, user message में नहीं, इसलिए यह ephemeral रहता है (session history में persist नहीं होता).
• Decoded file text को जोड़े जाने से पहले untrusted external content के रूप में wrap किया जाता है, इसलिए file bytes को data माना जाता है, trusted instructions नहीं.
• Injected block स्पष्ट boundary markers जैसे <<<EXTERNAL_UNTRUSTED_CONTENT id="...">>> / <<<END_EXTERNAL_UNTRUSTED_CONTENT id="...">>> का उपयोग करता है और Source: External metadata line शामिल करता है.
• यह file-input path prompt budget बचाने के लिए लंबे SECURITY NOTICE: banner को जानबूझकर छोड़ता है; boundary markers और metadata फिर भी मौजूद रहते हैं.
• PDFs को पहले text के लिए parse किया जाता है. यदि कम text मिलता है, तो पहले pages images में rasterize किए जाते हैं और model को दिए जाते हैं, और injected file block placeholder [PDF content rendered to images] का उपयोग करता है.

• files.allowUrl: true
• images.allowUrl: true
• maxUrlParts: 8 (प्रति अनुरोध कुल URL-based input_file + input_image parts)
• अनुरोध सुरक्षित रखे जाते हैं (DNS resolution, private IP blocking, redirect caps, timeouts).
• Optional hostname allowlists प्रति input type समर्थित हैं (files.urlAllowlist, images.urlAllowlist).
  • Exact host: "cdn.example.com"
  • Wildcard subdomains: "*.assets.example.com" (apex से match नहीं करता)
  • खाली या छोड़ी गई allowlists का अर्थ है कोई hostname allowlist restriction नहीं.
• URL-based fetches को पूरी तरह अक्षम करने के लिए, files.allowUrl: false और/या images.allowUrl: false set करें.

​

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

• maxBodyBytes: 20MB
• maxUrlParts: 8
• files.maxBytes: 5MB
• files.maxChars: 200k
• 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
• HEIC/HEIF input_image sources तब स्वीकार किए जाते हैं जब system converter उपलब्ध हो और provider delivery से पहले JPEG में normalize किए जाते हैं. समर्थित converters macOS sips, ImageMagick, GraphicsMagick, या ffmpeg हैं.

• URL allowlists fetch से पहले और redirect hops पर enforce की जाती हैं.
• किसी hostname को allowlist करना private/internal IP blocking को bypass नहीं करता.
• internet-exposed gateways के लिए, app-level guards के अतिरिक्त network egress controls लागू करें. Security देखें.

​

Streaming (SSE)

• Content-Type: text/event-stream
• प्रत्येक event line event: <type> और data: <json> होती है
• Stream 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 (error पर)

​

उपयोग

​

Errors

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

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

​

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

​

संबंधित

• OpenAI चैट कम्प्लीशन्स
• OpenAI