Gateway

टूल API को इनवोक करते हैं

OpenClaw का Gateway किसी एक टूल को सीधे इनवोक करने के लिए एक HTTP एंडपॉइंट उपलब्ध कराता है। यह हमेशा सक्षम रहता है और Gateway प्रमाणीकरण के साथ टूल नीति का उपयोग करता है। OpenAI-संगत /v1/* सतह की तरह, साझा-सीक्रेट बियरर प्रमाणीकरण को पूरे Gateway के लिए विश्वसनीय ऑपरेटर पहुँच माना जाता है।

POST /tools/invoke
Gateway वाला ही पोर्ट (WS + HTTP मल्टीप्लेक्स): http://<gateway-host>:<port>/tools/invoke
डिफ़ॉल्ट अधिकतम अनुरोध बॉडी आकार: 2 MB

प्रमाणीकरण

Gateway प्रमाणीकरण कॉन्फ़िगरेशन का उपयोग करता है।

सामान्य HTTP प्रमाणीकरण पथ:

साझा-सीक्रेट प्रमाणीकरण (gateway.auth.mode="token" या "password"): Authorization: Bearer <token-or-password>
विश्वसनीय पहचान-युक्त HTTP प्रमाणीकरण (gateway.auth.mode="trusted-proxy"): कॉन्फ़िगर किए गए पहचान-सजग प्रॉक्सी के माध्यम से रूट करें और उसे आवश्यक पहचान हेडर इंजेक्ट करने दें
निजी-इनग्रेस खुला प्रमाणीकरण (gateway.auth.mode="none"): किसी प्रमाणीकरण हेडर की आवश्यकता नहीं

टिप्पणियाँ:

mode="token" gateway.auth.token (या OPENCLAW_GATEWAY_TOKEN) का उपयोग करता है।
mode="password" gateway.auth.password (या OPENCLAW_GATEWAY_PASSWORD) का उपयोग करता है।
mode="trusted-proxy" के लिए HTTP अनुरोध का कॉन्फ़िगर किए गए विश्वसनीय प्रॉक्सी स्रोत से आना आवश्यक है; समान-होस्ट लूपबैक प्रॉक्सी के लिए स्पष्ट gateway.auth.trustedProxy.allowLoopback = true आवश्यक है।
प्रॉक्सी को बायपास करने वाले आंतरिक समान-होस्ट कॉलर स्थानीय प्रत्यक्ष फ़ॉलबैक के रूप में gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD का उपयोग कर सकते हैं। इसके बजाय कोई भी Forwarded, X-Forwarded-*, या X-Real-IP हेडर साक्ष्य अनुरोध को विश्वसनीय-प्रॉक्सी पथ पर बनाए रखता है।
यदि gateway.auth.rateLimit कॉन्फ़िगर है और बहुत अधिक प्रमाणीकरण विफलताएँ होती हैं, तो एंडपॉइंट Retry-After के साथ 429 लौटाता है।

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

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

यहाँ HTTP बियरर प्रमाणीकरण कोई संकीर्ण प्रति-उपयोगकर्ता स्कोप मॉडल नहीं है।
इस एंडपॉइंट के लिए मान्य Gateway टोकन/पासवर्ड को स्वामी/ऑपरेटर क्रेडेंशियल जैसा माना जाना चाहिए।
साझा-सीक्रेट प्रमाणीकरण मोड (token और password) के लिए, एंडपॉइंट सामान्य पूर्ण ऑपरेटर डिफ़ॉल्ट पुनर्स्थापित करता है, भले ही कॉलर अधिक संकीर्ण x-openclaw-scopes हेडर भेजे।
साझा-सीक्रेट प्रमाणीकरण इस एंडपॉइंट पर प्रत्यक्ष टूल इनवोकेशन को स्वामी-प्रेषक टर्न भी मानता है।
विश्वसनीय पहचान-युक्त HTTP मोड (विश्वसनीय प्रॉक्सी प्रमाणीकरण, या निजी इनग्रेस पर gateway.auth.mode="none") मौजूद होने पर x-openclaw-scopes का सम्मान करते हैं और अन्यथा सामान्य ऑपरेटर डिफ़ॉल्ट स्कोप सेट पर फ़ॉलबैक करते हैं।
इस एंडपॉइंट को केवल लूपबैक/टेलनेट/निजी इनग्रेस पर रखें; इसे सीधे सार्वजनिक इंटरनेट पर उजागर न करें।

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

प्रमाणीकरण मोड व्यवहार

token या password + Authorization: Bearer ... साझा Gateway ऑपरेटर सीक्रेट का स्वामित्व प्रमाणित करता है। अधिक संकीर्ण x-openclaw-scopes को अनदेखा करता है। पूर्ण डिफ़ॉल्ट ऑपरेटर स्कोप सेट पुनर्स्थापित करता है: operator.admin, operator.approvals, operator.pairing, operator.read, operator.talk.secrets, operator.write। प्रत्यक्ष टूल इनवोकेशन को स्वामी-प्रेषक टर्न मानता है।

विश्वसनीय पहचान-युक्त HTTP (विश्वसनीय प्रॉक्सी प्रमाणीकरण, या निजी इनग्रेस पर mode="none") किसी बाहरी विश्वसनीय पहचान या डिप्लॉयमेंट सीमा को प्रमाणित करता है। मौजूद होने पर x-openclaw-scopes का सम्मान करता है। हेडर अनुपस्थित होने पर सामान्य ऑपरेटर डिफ़ॉल्ट स्कोप सेट पर फ़ॉलबैक करता है। केवल तभी स्वामी अर्थविज्ञान खोता है, जब कॉलर स्पष्ट रूप से स्कोप संकीर्ण करता है और operator.admin छोड़ देता है।

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

अनुरोध बॉडी

json

{  "tool": "sessions_list",  "action": "json",  "args": {},  "sessionKey": "main",  "dryRun": false}

फ़ील्ड:

tool / name (स्ट्रिंग, आवश्यक): इनवोक किए जाने वाले टूल का नाम। दोनों भेजे जाने पर name को प्राथमिकता मिलती है।
action (स्ट्रिंग, वैकल्पिक): यदि टूल स्कीमा action प्रॉपर्टी का समर्थन करता है और args ने पहले से कोई सेट नहीं की है, तो इसे args.action में मर्ज किया जाता है।
args (ऑब्जेक्ट, वैकल्पिक): टूल-विशिष्ट आर्ग्युमेंट।
sessionKey (स्ट्रिंग, वैकल्पिक): लक्षित सेशन कुंजी। छोड़े जाने या "main" होने पर, Gateway कॉन्फ़िगर की गई मुख्य सेशन कुंजी का उपयोग करता है (session.mainKey और डिफ़ॉल्ट एजेंट, या वैश्विक सेशन स्कोप में global का सम्मान करता है)।
agentId (स्ट्रिंग, वैकल्पिक): उस एजेंट के लिए सेशन कुंजी का समाधान करता है। यदि यह किसी स्पष्ट sessionKey से टकराता है, जो पहले से किसी भिन्न एजेंट पर मैप है, तो 400 के साथ त्रुटि देता है।
idempotencyKey (स्ट्रिंग, वैकल्पिक): इनवोकेशन के लिए स्थिर टूल-कॉल आईडी प्राप्त करने हेतु उपयोग किया जाता है।
dryRun (बूलियन, वैकल्पिक): भविष्य में उपयोग के लिए आरक्षित; वर्तमान में अनदेखा किया जाता है।

नीति + रूटिंग व्यवहार

टूल उपलब्धता को Gateway एजेंटों द्वारा उपयोग की जाने वाली उसी नीति शृंखला के माध्यम से फ़िल्टर किया जाता है:

tools.profile / tools.byProvider.profile
tools.allow / tools.byProvider.allow
agents.<id>.tools.allow / agents.<id>.tools.byProvider.allow
समूह नीतियाँ (यदि सेशन कुंजी किसी समूह या चैनल पर मैप होती है)
उप-एजेंट नीति (उप-एजेंट सेशन कुंजी के साथ इनवोक करते समय)

यदि नीति किसी टूल की अनुमति नहीं देती, तो एंडपॉइंट 404 लौटाता है।

महत्वपूर्ण सीमा संबंधी टिप्पणियाँ:

एक्ज़ेक अनुमोदन ऑपरेटर सुरक्षा-नियंत्रण हैं, इस HTTP एंडपॉइंट के लिए अलग प्राधिकरण सीमा नहीं। यदि कोई टूल यहाँ Gateway प्रमाणीकरण + टूल नीति के माध्यम से पहुँच योग्य है, तो /tools/invoke कोई अतिरिक्त प्रति-कॉल अनुमोदन प्रॉम्प्ट नहीं जोड़ता।
यदि exec यहाँ पहुँच योग्य है, तो इसे परिवर्तनकारी शेल सतह मानें। write, edit, apply_patch, या HTTP फ़ाइल-सिस्टम लेखन टूल को अस्वीकार करने से शेल निष्पादन केवल-पढ़ने योग्य नहीं हो जाता।
अविश्वसनीय कॉलरों के साथ Gateway बियरर क्रेडेंशियल साझा न करें। यदि विश्वास सीमाओं के बीच पृथक्करण आवश्यक है, तो अलग-अलग Gateway चलाएँ (आदर्श रूप से अलग OS उपयोगकर्ताओं/होस्ट पर)।

Gateway HTTP डिफ़ॉल्ट रूप से एक कठोर निषेध सूची भी लागू करता है (भले ही सेशन नीति टूल की अनुमति देती हो):

टूल	कारण
`exec`	प्रत्यक्ष कमांड निष्पादन (RCE सतह)
`spawn`	मनमाना चाइल्ड प्रोसेस निर्माण (RCE सतह)
`shell`	शेल कमांड निष्पादन (RCE सतह)
`fs_write`	होस्ट पर मनमाना फ़ाइल परिवर्तन
`fs_delete`	होस्ट पर मनमाना फ़ाइल विलोपन
`fs_move`	होस्ट पर मनमाना फ़ाइल स्थानांतरण/नाम-परिवर्तन
`apply_patch`	पैच लागू करने से मनमानी फ़ाइलें दोबारा लिखी जा सकती हैं
`sessions_spawn`	सेशन ऑर्केस्ट्रेशन; दूरस्थ रूप से एजेंट स्पॉन करना RCE है
`sessions_send`	क्रॉस-सेशन संदेश इंजेक्शन
`cron`	स्थायी स्वचालन नियंत्रण तल
`gateway`	Gateway नियंत्रण तल; HTTP के माध्यम से पुनः कॉन्फ़िगरेशन रोकता है
`nodes`	Node कमांड रिले युग्मित होस्ट पर `system.run` तक पहुँच सकता है

cron, gateway, और nodes भी केवल-स्वामी हैं: इस डिफ़ॉल्ट निषेध सूची से बाहर भी, गैर-स्वामी कॉलर इस सतह पर उन्हें इनवोक नहीं कर सकते।

सामान्य निषेध सूची को gateway.tools के माध्यम से अनुकूलित करें:

json5

{  gateway: {    tools: {      // HTTP /tools/invoke पर ब्लॉक किए जाने वाले अतिरिक्त टूल      deny: ["browser"],      // स्वामी/एडमिन कॉलरों के लिए डिफ़ॉल्ट निषेध सूची से टूल हटाएँ      allow: ["gateway"],    },  },}

gateway.tools.allow एक एक्सपोज़र ओवरराइड है, स्कोप अपग्रेड नहीं। पहचान-युक्त HTTP मोड में, cron, gateway, और nodes स्वामी/एडमिन पहचान (operator.admin) के बिना कॉलरों के लिए अनुपलब्ध रहते हैं, भले ही वे gateway.tools.allow में सूचीबद्ध हों। साझा-सीक्रेट बियरर प्रमाणीकरण अभी भी ऊपर दिए गए पूर्ण विश्वसनीय-ऑपरेटर नियम का पालन करता है।

समूह नीतियों को संदर्भ निर्धारित करने में सहायता के लिए, वैकल्पिक रूप से ये सेट किए जा सकते हैं:

x-openclaw-message-channel: <channel> (उदाहरण: slack, telegram)
x-openclaw-account-id: <accountId> (जब एकाधिक अकाउंट मौजूद हों)
x-openclaw-message-to: <target> (संदेश-टूल नीति के लिए डिलीवरी लक्ष्य)
x-openclaw-thread-id: <threadId> (संदेश-टूल नीति के लिए थ्रेड संदर्भ)

प्रतिक्रियाएँ

स्थिति	अर्थ
`200`	`{ ok: true, result }`
`400`	`{ ok: false, error: { type, message } }` (अमान्य अनुरोध या टूल इनपुट त्रुटि)
`401`	अनधिकृत
`403`	`{ ok: false, error: { type, message, requiresApproval? } }` (नीति द्वारा टूल कॉल ब्लॉक किया गया)
`404`	टूल उपलब्ध नहीं (नहीं मिला या अनुमति-सूची में नहीं)
`405`	विधि अनुमत नहीं
`408`	अनुरोध बॉडी पढ़ने का समय समाप्त
`413`	अनुरोध बॉडी अधिकतम पेलोड आकार से अधिक हो गई
`429`	प्रमाणीकरण दर-सीमित (`Retry-After` सेट)
`500`	`{ ok: false, error: { type, message } }` (अनपेक्षित टूल निष्पादन त्रुटि; स्वच्छ किया गया संदेश)

उदाहरण

bash

curl -sS http://127.0.0.1:18789/tools/invoke \  -H 'Authorization: Bearer secret' \  -H 'Content-Type: application/json' \  -d '{    "tool": "sessions_list",    "action": "json",    "args": {}  }'