---
read_when:
    - पूर्ण एजेंट टर्न चलाए बिना टूल कॉल करना
    - ऐसे ऑटोमेशन बनाना जिनमें टूल नीति लागू करना आवश्यक हो
summary: Gateway HTTP एंडपॉइंट के माध्यम से सीधे किसी एक टूल को इनवोक करें
title: टूल API को इनवोक करते हैं
x-i18n:
    generated_at: "2026-07-27T21:02:30Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: 6d07f765d63255e718d5e558b662589e77b2992538f43288cd83e6e3f2a06dda
    source_path: gateway/tools-invoke-http-api.md
    workflow: 16
---

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` छोड़ देता है।                               |

## अनुरोध बॉडी

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

## संबंधित

- [Gateway प्रोटोकॉल](/hi/gateway/protocol)
- [टूल और plugins](/hi/tools)