OpenAI चैट पूर्णताएँ

Gateway एक छोटी OpenAI-संगत Chat Completions सतह उपलब्ध करा सकता है। यह डिफ़ॉल्ट रूप से अक्षम है।

सक्षम होने के बाद, यह इन सभी को Gateway वाले पोर्ट पर ही उपलब्ध कराता है (WS + HTTP मल्टीप्लेक्स):

अनुरोध सामान्य Gateway एजेंट रन के रूप में चलते हैं (openclaw agent के समान कोडपथ), इसलिए रूटिंग, अनुमतियाँ और कॉन्फ़िगरेशन आपके Gateway के अनुरूप होते हैं।

एंडपॉइंट सक्षम करना

{  gateway: {    http: {      endpoints: {        chatCompletions: { enabled: true },      },    },  },}

अक्षम करने के लिए enabled: false सेट करें (या इसे छोड़ दें)।

सुरक्षा सीमा (महत्वपूर्ण)

इस एंडपॉइंट को Gateway इंस्टेंस तक पूर्ण ऑपरेटर पहुँच मानें:

• इस एंडपॉइंट के लिए मान्य Gateway टोकन/पासवर्ड किसी स्वामी/ऑपरेटर क्रेडेंशियल के बराबर है, न कि संकीर्ण प्रति-उपयोगकर्ता दायरे के।
• अनुरोध विश्वसनीय ऑपरेटर कार्रवाइयों वाले उसी नियंत्रण-प्लेन एजेंट पथ से चलते हैं, इसलिए यदि लक्षित एजेंट की नीति संवेदनशील टूल की अनुमति देती है, तो यह एंडपॉइंट उनका उपयोग कर सकता है।
• इसे केवल लूपबैक/टेलनेट/निजी इनग्रेस पर रखें। इसे सार्वजनिक इंटरनेट पर उजागर न करें।

प्रमाणीकरण मैट्रिक्स:

ऑपरेटर दायरे, सुरक्षा, और दूरस्थ पहुँच देखें।

प्रमाणीकरण

Gateway प्रमाणीकरण कॉन्फ़िगरेशन का उपयोग करता है (उस मोड के विवरण के लिए विश्वसनीय प्रॉक्सी प्रमाणीकरण देखें):

टिप्पणियाँ:

• trusted-proxy Gateway पर प्रॉक्सी को बायपास करने वाले समान-होस्ट कॉलर सीधे gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD का उपयोग कर सकते हैं। किसी भी Forwarded, X-Forwarded-*, या X-Real-IP हेडर का प्रमाण अनुरोध को इसके बजाय विश्वसनीय-प्रॉक्सी पथ पर बनाए रखता है।
• यदि gateway.auth.rateLimit कॉन्फ़िगर है और बहुत अधिक प्रमाणीकरण प्रयास विफल होते हैं, तो एंडपॉइंट Retry-After हेडर के साथ 429 लौटाता है।

इस एंडपॉइंट का उपयोग कब करें

• जब आपका एकीकरण उसी Gateway के लिए केवल एक अन्य ऑपरेटर/क्लाइंट सतह हो, तो नया बिल्ट-इन चैनल जोड़ने के बजाय इसे प्राथमिकता दें।
• दूरस्थ Gateway से सीधे कनेक्ट होने वाले नेटिव मोबाइल क्लाइंट के लिए, युग्मित-डिवाइस बूटस्ट्रैप/डिवाइस-टोकन प्रवाह के साथ WebChat या Gateway प्रोटोकॉल को प्राथमिकता दें, ताकि डिवाइस को साझा HTTP टोकन/पासवर्ड की आवश्यकता न हो।
• अपने उपयोगकर्ताओं, रूम, Webhook डिलीवरी या आउटबाउंड ट्रांसपोर्ट वाले बाहरी मैसेजिंग नेटवर्क को एकीकृत करते समय इसके बजाय चैनल Plugin बनाएँ। Plugin बनाना देखें।

एजेंट-प्रथम मॉडल अनुबंध

OpenClaw, OpenAI के model फ़ील्ड को अपरिष्कृत प्रदाता मॉडल आईडी नहीं, बल्कि एजेंट लक्ष्य मानता है।

वैकल्पिक अनुरोध हेडर:

/v1/models शीर्ष-स्तरीय एजेंट लक्ष्य (openclaw, openclaw/default, openclaw/<agentId>) सूचीबद्ध करता है, बैकएंड प्रदाता मॉडल या उप-एजेंट नहीं; उप-एजेंट आंतरिक निष्पादन टोपोलॉजी बने रहते हैं। यदि आप x-openclaw-model को छोड़ देते हैं, तो चयनित एजेंट अपने सामान्य कॉन्फ़िगर किए गए मॉडल के साथ चलता है।

/v1/embeddings समान एजेंट-लक्ष्य model आईडी का उपयोग करता है। विशिष्ट एम्बेडिंग मॉडल चुनने के लिए x-openclaw-model भेजें (साझा-सीक्रेट कॉलर से, या operator.admin वाले पहचान-युक्त कॉलर से); अन्यथा अनुरोध चयनित एजेंट के सामान्य एम्बेडिंग सेटअप का उपयोग करता है।

सत्र व्यवहार

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

यदि अनुरोध में OpenAI की user स्ट्रिंग शामिल है, तो Gateway उससे एक स्थिर सत्र कुंजी प्राप्त करता है, ताकि बार-बार किए गए कॉल एक एजेंट सत्र साझा कर सकें। कस्टम ऐप्स के लिए, प्रत्येक वार्तालाप थ्रेड में समान user मान का पुनः उपयोग करें; खाता-स्तरीय पहचानकर्ताओं से बचें, जब तक कि आप कई वार्तालापों/डिवाइसों को एक OpenClaw सत्र साझा नहीं करवाना चाहते। कई क्लाइंट/थ्रेड के बीच स्पष्ट रूटिंग नियंत्रण की आवश्यकता होने पर ही x-openclaw-session-key का उपयोग करें, और ऐप्लिकेशन-स्वामित्व वाली ऐसी कुंजियाँ रखें जो ऊपर दिए गए आरक्षित नेमस्पेस से बचें।

अनुरोध सीमाएँ (कॉन्फ़िगरेशन)

डिफ़ॉल्ट मानों को gateway.http.endpoints.chatCompletions के अंतर्गत समायोजित किया जा सकता है:

{  gateway: {    http: {      endpoints: {        chatCompletions: {          enabled: true,          maxBodyBytes: 20000000,          maxImageParts: 8,          maxTotalImageBytes: 20000000,          images: {            allowUrl: false,            urlAllowlist: ["cdn.example.com", "*.assets.example.com"],            allowedMimes: [              "image/jpeg",              "image/png",              "image/gif",              "image/webp",              "image/heic",              "image/heif",            ],            maxBytes: 10485760,            maxRedirects: 3,            timeoutMs: 10000,          },        },      },    },  },}

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

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

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

चैट टूल अनुबंध

/v1/chat/completions सामान्य OpenAI Chat क्लाइंट के साथ संगत फ़ंक्शन-टूल उपसमुच्चय का समर्थन करता है।

समर्थित अनुरोध फ़ील्ड

सभी सैंपलिंग और टोकन-सीमा फ़ील्ड समान एजेंट स्ट्रीम-पैरामीटर चैनल से भेजे जाते हैं और सर्वोत्तम प्रयास के आधार पर अग्रेषित किए जाते हैं:

• टोकन सीमा: वायर फ़ील्ड का नाम प्रदाता ट्रांसपोर्ट चुनता है: OpenAI-परिवार के एंडपॉइंट के लिए max_completion_tokens, और केवल पुराना नाम स्वीकार करने वाले प्रदाताओं (Mistral, Chutes) के लिए max_tokens।
• stop ट्रांसपोर्ट के स्टॉप फ़ील्ड से मैप होता है: Chat Completions बैकएंड के लिए stop, Anthropic के लिए stop_sequences। OpenAI Responses API में स्टॉप पैरामीटर नहीं है, इसलिए Responses-समर्थित मॉडल पर stop लागू नहीं होता।
• ChatGPT-आधारित Codex Responses बैकएंड निश्चित सर्वर-साइड सैंपलिंग का उपयोग करता है और अनुरोध के उस बैकएंड तक पहुँचने से पहले temperature/top_p को (max_output_tokens, metadata, prompt_cache_retention, service_tier के साथ) हटा देता है।

असमर्थित प्रकार

इनके लिए 400 invalid_request_error लौटाता है:

• गैर-सरणी tools, गैर-फ़ंक्शन टूल प्रविष्टियाँ, या अनुपस्थित tool.function.name
• tool_choice के प्रकार, जैसे allowed_tools और custom
• tool_choice.function.name मान, जो दिए गए किसी टूल से मेल नहीं खाते

tool_choice: "required" और फ़ंक्शन-पिन किए गए tool_choice के लिए, एंडपॉइंट उपलब्ध क्लाइंट फ़ंक्शन-टूल सेट को सीमित करता है, रनटाइम को उत्तर देने से पहले क्लाइंट टूल कॉल करने का निर्देश देता है, और एजेंट प्रतिक्रिया में मेल खाने वाला संरचित क्लाइंट-टूल कॉल न होने पर त्रुटि देता है। यह कॉलर द्वारा दी गई HTTP tools सूची पर लागू होता है, प्रत्येक आंतरिक OpenClaw एजेंट टूल पर नहीं।

गैर-स्ट्रीमिंग टूल प्रतिक्रिया का स्वरूप

जब एजेंट टूल कॉल करता है, तो प्रतिक्रिया में इसका उपयोग होता है:

• choices[0].finish_reason = "tool_calls"
• choices[0].message.tool_calls[] प्रविष्टियाँ, जिनमें id, type: "function", function.name, function.arguments (JSON स्ट्रिंग) होते हैं
• टूल कॉल से पहले सहायक की टिप्पणी, choices[0].message.content में (संभवतः रिक्त)

स्ट्रीमिंग टूल प्रतिक्रिया का स्वरूप

जब stream: true, टूल कॉल क्रमिक SSE खंडों के रूप में आते हैं: एक आरंभिक सहायक भूमिका डेल्टा, वैकल्पिक सहायक टिप्पणी डेल्टा, टूल की पहचान और आर्ग्युमेंट के अंश ले जाने वाले एक या अधिक delta.tool_calls खंड, और फिर finish_reason: "tool_calls" तथा data: [DONE] वाला अंतिम खंड।

यदि stream_options.include_usage=true, तो [DONE] से पहले उपयोग का अंतिम खंड उत्सर्जित किया जाता है।

टूल अनुवर्ती लूप

tool_calls प्राप्त करने के बाद, अनुरोधित फ़ंक्शन निष्पादित करें और ऐसा अनुवर्ती अनुरोध भेजें जिसमें पिछला सहायक टूल-कॉल संदेश तथा मेल खाने वाले tool_call_id वाले एक या अधिक role: "tool" संदेश शामिल हों। अंतिम उत्तर तैयार करने के लिए यही एजेंट रीज़निंग लूप जारी रहता है।

स्ट्रीमिंग (SSE)

Server-Sent Events प्राप्त करने के लिए stream: true सेट करें:

• Content-Type: text/event-stream
• प्रत्येक इवेंट पंक्ति data: <json> होती है
• स्ट्रीम data: [DONE] के साथ समाप्त होती है

Open WebUI का त्वरित सेटअप

• Base URL: http://127.0.0.1:18789/v1
• Docker on macOS base URL: http://host.docker.internal:18789/v1
• API key: आपका Gateway बेयरर टोकन
• Model: openclaw/default

अपेक्षित व्यवहार: GET /v1/models में openclaw/default सूचीबद्ध होता है, और Open WebUI इसे चैट मॉडल आईडी के रूप में उपयोग करता है। किसी विशिष्ट बैकएंड प्रदाता/मॉडल के लिए, एजेंट का सामान्य डिफ़ॉल्ट मॉडल सेट करें, या x-openclaw-model भेजें (साझा-सीक्रेट कॉलर, या operator.admin वाला पहचान-युक्त कॉलर)।

त्वरित स्मोक परीक्षण:

curl -sS http://127.0.0.1:18789/v1/models \  -H 'Authorization: Bearer YOUR_TOKEN'

यदि यह openclaw/default लौटाता है, तो अधिकांश Open WebUI सेटअप समान Base URL और टोकन से कनेक्ट हो सकते हैं।

उदाहरण

किसी एक ऐप वार्तालाप के लिए स्थिर सत्र:

curl -sS http://127.0.0.1:18789/v1/chat/completions \  -H 'Authorization: Bearer YOUR_TOKEN' \  -H 'Content-Type: application/json' \  -d '{    "model": "openclaw/default",    "user": "conv:YOUR_CONVERSATION_ID",    "messages": [{"role":"user","content":"आज के लिए मेरे कार्यों का सारांश दें"}]  }'

उसी एजेंट सत्र को जारी रखने के लिए उस वार्तालाप की बाद की कॉल में समान user मान का पुनः उपयोग करें।

गैर-स्ट्रीमिंग:

curl -sS http://127.0.0.1:18789/v1/chat/completions \  -H 'Authorization: Bearer YOUR_TOKEN' \  -H 'Content-Type: application/json' \  -d '{    "model": "openclaw/default",    "messages": [{"role":"user","content":"नमस्ते"}]  }'

स्ट्रीमिंग:

curl -N http://127.0.0.1:18789/v1/chat/completions \  -H 'Authorization: Bearer YOUR_TOKEN' \  -H 'Content-Type: application/json' \  -H 'x-openclaw-model: openai/gpt-5.4' \  -d '{    "model": "openclaw/research",    "stream": true,    "messages": [{"role":"user","content":"नमस्ते"}]  }'

मॉडल सूचीबद्ध करें:

curl -sS http://127.0.0.1:18789/v1/models \  -H 'Authorization: Bearer YOUR_TOKEN'

एक मॉडल प्राप्त करें:

curl -sS http://127.0.0.1:18789/v1/models/openclaw%2Fdefault \  -H 'Authorization: Bearer YOUR_TOKEN'

एम्बेडिंग बनाएँ:

curl -sS http://127.0.0.1:18789/v1/embeddings \  -H 'Authorization: Bearer YOUR_TOKEN' \  -H 'Content-Type: application/json' \  -H 'x-openclaw-model: openai/text-embedding-3-small' \  -d '{    "model": "openclaw/default",    "input": ["alpha", "beta"]  }'

/v1/embeddings, input को स्ट्रिंग या स्ट्रिंग की सरणी के रूप में समर्थन करता है।

संबंधित

• कॉन्फ़िगरेशन संदर्भ
• ऑपरेटर स्कोप
• OpenAI