OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Gateway

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

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

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

विधि पथ
POST /v1/chat/completions
GET /v1/models
GET /v1/models/{id}
POST /v1/embeddings
POST /v1/responses

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

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

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

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

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

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

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

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

प्रमाणीकरण पथ व्यवहार
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 का पालन करता है; अनुपस्थित होने पर डिफ़ॉल्ट ऑपरेटर दायरा सेट का उपयोग करता है। स्वामी संबंधी अर्थ केवल तभी खोता है, जब कॉलर स्पष्ट रूप से दायरों को सीमित करता है और operator.admin को छोड़ देता है। x-openclaw-model जैसे स्वामी-स्तरीय नियंत्रणों के लिए operator.admin आवश्यक है।

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

प्रमाणीकरण

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

मोड प्रमाणीकरण करने का तरीका
gateway.auth.mode="token" Authorization: Bearer <token>। gateway.auth.token या OPENCLAW_GATEWAY_TOKEN के माध्यम से सेट करें।
gateway.auth.mode="password" Authorization: Bearer <password>। gateway.auth.password या OPENCLAW_GATEWAY_PASSWORD के माध्यम से सेट करें।
gateway.auth.mode="trusted-proxy" कॉन्फ़िगर किए गए पहचान-जागरूक प्रॉक्सी से रूट करें; यह आवश्यक पहचान हेडर इंजेक्ट करता है। समान-होस्ट लूपबैक प्रॉक्सी को स्पष्ट gateway.auth.trustedProxy.allowLoopback = true की आवश्यकता होती है।
gateway.auth.mode="none" किसी प्रमाणीकरण हेडर की आवश्यकता नहीं है (केवल निजी इनग्रेस)।

टिप्पणियाँ:

  • 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 टोकन/पासवर्ड की आवश्यकता न हो।
  • इसके बजाय चैनल Plugin तब बनाएँ, जब किसी ऐसे बाहरी मैसेजिंग नेटवर्क को इंटीग्रेट कर रहे हों जिसके अपने उपयोगकर्ता, रूम, Webhook डिलीवरी या आउटबाउंड ट्रांसपोर्ट हों। Plugin बनाना देखें।

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

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

model मान यहाँ रूट करता है
openclaw कॉन्फ़िगर किया गया डिफ़ॉल्ट एजेंट
openclaw/default कॉन्फ़िगर किया गया डिफ़ॉल्ट एजेंट (स्थिर उपनाम; अलग-अलग परिवेशों में वास्तविक डिफ़ॉल्ट एजेंट आईडी बदलने पर भी इसे हार्डकोड करना सुरक्षित है)
openclaw/<agentId> या openclaw:<agentId> विशिष्ट एजेंट
agent:<agentId> विशिष्ट एजेंट (संगतता उपनाम)

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

हेडर प्रभाव
x-openclaw-model: <provider/model-or-bare-id> चयनित एजेंट के लिए बैकएंड मॉडल को ओवरराइड करता है। साझा-सीक्रेट बियरर कॉलर इसका सीधे उपयोग कर सकते हैं; पहचान-सहित कॉलर (विश्वसनीय-प्रॉक्सी, या x-openclaw-scopes वाला निजी बिना-प्रमाणीकरण इनग्रेस) को operator.admin की आवश्यकता होती है, अन्यथा 403 missing scope: operator.admin।
x-openclaw-agent-id: <agentId> एजेंट चयन के लिए संगतता ओवरराइड।
x-openclaw-session-key: <sessionKey> स्पष्ट सत्र रूटिंग। यदि यह आरक्षित आंतरिक नेमस्पेस (subagent:, cron:, acp:) का उपयोग करता है, तो 400 invalid_request_error के साथ अस्वीकार किया जाता है।
x-openclaw-message-channel: <channel> चैनल-जागरूक प्रॉम्प्ट/नीतियों के लिए सिंथेटिक इनग्रेस चैनल संदर्भ सेट करता है।

/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 का उपयोग केवल तभी करें, जब आपको कई क्लाइंट/थ्रेड में स्पष्ट रूटिंग नियंत्रण की आवश्यकता हो; इसके लिए ऐप्लिकेशन-स्वामित्व वाली ऐसी कुंजियाँ उपयोग करें जो ऊपर दिए गए आरक्षित नेमस्पेस से बचें।

अनुरोध सीमाएँ

एंडपॉइंट प्रति अनुरोध बॉडी के लिए 20 MB, नवीनतम उपयोगकर्ता संदेश से 8 image_url भाग और संचयी डीकोड किए गए चित्र डेटा के लिए 20 MB की अंतर्निहित सीमाओं का उपयोग करता है। चित्र स्रोत नीति gateway.http.endpoints.chatCompletions.images के अंतर्गत कॉन्फ़िगर करने योग्य रहती है:

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

चित्र सेटिंग के डिफ़ॉल्ट मान:

कुंजी डिफ़ॉल्ट
images.allowUrl false (URL-स्रोत वाले image_url भाग सक्षम किए जाने तक अस्वीकार किए जाते हैं)
images.maxBytes प्रति चित्र 10MB
images.maxRedirects 3
images.timeoutMs 10s

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

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

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

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

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

फ़ील्ड टिप्पणियाँ
tools { "type": "function", "function": { ... } } की सरणी
tool_choice "auto", "none", "required", या { "type": "function", "function": { "name": "..." } }
messages[*].role: "tool" अनुवर्ती टर्न
messages[*].tool_call_id किसी टूल परिणाम को पिछले टूल कॉल से संबद्ध करता है
max_completion_tokens संख्या; प्रत्येक कॉल में कुल कंप्लीशन टोकनों की सीमा (रीज़निंग टोकन सहित)। वर्तमान फ़ील्ड नाम; इसे और max_tokens दोनों को भेजे जाने पर इसका उपयोग होता है।
max_tokens संख्या; लीगेसी उपनाम, max_completion_tokens भी मौजूद होने पर अनदेखा किया जाता है।
temperature संख्या 0-2; सर्वोत्तम प्रयास के आधार पर अपस्ट्रीम प्रदाता को अग्रेषित की जाती है। सीमा से बाहर होने पर 400 invalid_request_error।
top_p संख्या 0-1; सर्वोत्तम प्रयास। सीमा से बाहर होने पर 400 invalid_request_error।
frequency_penalty संख्या -2.0 से 2.0; सर्वोत्तम प्रयास। सीमा से बाहर होने पर 400 invalid_request_error।
presence_penalty संख्या -2.0 से 2.0; सर्वोत्तम प्रयास। सीमा से बाहर होने पर 400 invalid_request_error।
seed पूर्णांक; सर्वोत्तम प्रयास। गैर-पूर्णांक मानों के लिए 400 invalid_request_error।
stop स्ट्रिंग या अधिकतम 4 स्ट्रिंग की सरणी; सर्वोत्तम प्रयास। 4 से अधिक अनुक्रमों या गैर-स्ट्रिंग/खाली प्रविष्टियों के लिए 400 invalid_request_error।

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

  • टोकन सीमा: वायर फ़ील्ड का नाम प्रदाता ट्रांसपोर्ट द्वारा चुना जाता है: 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 का त्वरित सेटअप

  • बेस URL: http://127.0.0.1:18789/v1
  • macOS पर Docker का बेस URL: http://host.docker.internal:18789/v1
  • API कुंजी: आपका Gateway बेयरर टोकन
  • मॉडल: openclaw/default

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

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

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

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

उदाहरण

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

bash
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 मान दोबारा उपयोग करें।

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

bash
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":"नमस्ते"}]  }'

स्ट्रीमिंग:

bash
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":"नमस्ते"}]  }'

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

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

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

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

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

bash
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 को स्ट्रिंग या स्ट्रिंग की सरणी के रूप में समर्थित करता है।

संबंधित

Was this useful?
On this page

On this page