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

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

​

प्रमाणीकरण

• साझा-सीक्रेट प्रमाणीकरण (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 लौटाता है।

​

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

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

​

अनुरोध बॉडी

{
  "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 (बूलियन, वैकल्पिक): भविष्य में उपयोग के लिए आरक्षित; वर्तमान में अनदेखा किया जाता है।

​

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

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

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

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

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

​

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

​

उदाहरण

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

​

संबंधित

• Gateway प्रोटोकॉल
• टूल और plugins