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> का उपयोग करता है; विश्वसनीय प्रॉक्सी पहचान-जागरूक प्रॉक्सी हेडर का उपयोग करता है (समान-होस्ट लूपबैक प्रॉक्सी को 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। इस एंडपॉइंट पर चैट टर्न को स्वामी-प्रेषक टर्न माना जाता है।
• विश्वसनीय पहचान-युक्त HTTP मोड (विश्वसनीय प्रॉक्सी, या gateway.auth.mode="none") मौजूद होने पर x-openclaw-scopes का सम्मान करते हैं, अन्यथा ऑपरेटर के डिफ़ॉल्ट स्कोप सेट का उपयोग करते हैं। स्वामी अर्थ-विज्ञान केवल तभी समाप्त होता है जब कॉलर स्पष्ट रूप से स्कोप सीमित करता है और operator.admin को छोड़ देता है।
• एजेंट चुनने के लिए model: "openclaw", "openclaw/default", "openclaw/<agentId>", या x-openclaw-agent-id हेडर का उपयोग करें।
• चयनित एजेंट के बैकएंड मॉडल को ओवरराइड करने के लिए x-openclaw-model का उपयोग करें (पहचान-युक्त प्रमाणीकरण पथों पर operator.admin आवश्यक है)।
• स्पष्ट सत्र रूटिंग के लिए x-openclaw-session-key का उपयोग करें (यदि यह आरक्षित नेमस्पेस का उपयोग करता है तो 400 invalid_request_error के साथ अस्वीकार किया जाता है: subagent:, cron:, acp:)।
• गैर-डिफ़ॉल्ट कृत्रिम इनग्रेस चैनल संदर्भ के लिए x-openclaw-message-channel का उपयोग करें।

एजेंट-लक्षित मॉडलों, openclaw/default, एम्बेडिंग पास-थ्रू और बैकएंड मॉडल ओवरराइड की प्रामाणिक व्याख्या के लिए OpenAI Chat Completions देखें।

ऑपरेटर स्कोप और सुरक्षा देखें।

सत्र व्यवहार

डिफ़ॉल्ट रूप से एंडपॉइंट प्रति अनुरोध स्टेटलेस होता है (प्रत्येक कॉल पर एक नई सत्र कुंजी बनाई जाती है)।

यदि अनुरोध में OpenResponses user स्ट्रिंग शामिल है, तो Gateway उससे एक स्थिर सत्र कुंजी प्राप्त करता है, ताकि बार-बार किए गए कॉल एक एजेंट सत्र साझा कर सकें।

जब अनुरोध समान एजेंट/उपयोगकर्ता/अनुरोधित-सत्र स्कोप के भीतर रहता है (प्रमाणीकरण विषय, एजेंट आईडी और 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 द्वारा प्रदान की जाती है, जो टेक्स्ट निष्कर्षण और पृष्ठ रेंडरिंग के लिए 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 सेट करें।

फ़ाइल + छवि सीमाएँ

एंडपॉइंट अंतर्निहित 20 MB अनुरोध-बॉडी सीमा का उपयोग करता है। फ़ाइल और छवि स्रोत नीति gateway.http.endpoints.responses के अंतर्गत कॉन्फ़िगर की जा सकती है:

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

छोड़े जाने पर डिफ़ॉल्ट:

HEIC/HEIF input_image स्रोतों को साझा OpenClaw इमेज प्रोसेसर (Rastermill) के माध्यम से प्रदाता तक पहुँचाने से पहले JPEG में सामान्यीकृत किया जाता है, जो बाहरी कोडेक समर्थन की आवश्यकता वाले प्रारूपों के लिए सिस्टम कनवर्टर (sips, ImageMagick, GraphicsMagick, या ffmpeg) का फ़ॉलबैक के रूप में उपयोग करता है।

सुरक्षा नोट: URL अनुमति-सूचियाँ फ़ेच करने से पहले और रीडायरेक्ट के प्रत्येक चरण पर लागू की जाती हैं। किसी होस्टनाम को अनुमति-सूची में शामिल करने से निजी/आंतरिक IP अवरोधन को बायपास नहीं किया जाता। इंटरनेट पर उपलब्ध gateways के लिए, ऐप-स्तरीय सुरक्षा उपायों के अतिरिक्त नेटवर्क एग्रेस नियंत्रण लागू करें। सुरक्षा देखें।

स्ट्रीमिंग (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 सामान्य OpenAI-शैली के उपनामों को सामान्यीकृत करता है, जिनमें input_tokens / output_tokens और prompt_tokens / completion_tokens शामिल हैं।

त्रुटियाँ

त्रुटियाँ इस प्रकार के 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