> ## Documentation Index
> Fetch the complete documentation index at: https://openclaw.veiseule.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools Invoke API

# Tools Invoke (HTTP)

OpenClaw’s Gateway exposes a simple HTTP endpoint for invoking a single tool directly. It is always enabled, but gated by Gateway auth and tool policy.

* `POST /tools/invoke`
* Gateway के समान पोर्ट (WS + HTTP मल्टीप्लेक्स): `http://<gateway-host>:<port>/tools/invoke`

डिफ़ॉल्ट अधिकतम पेलोड आकार 2 MB है।

## प्रमाणीकरण

Uses the Gateway auth configuration. Send a bearer token:

* `Authorization: Bearer <token>`

टिप्पणियाँ:

* जब `gateway.auth.mode="token"`, तब `gateway.auth.token` (या `OPENCLAW_GATEWAY_TOKEN`) का उपयोग करें।
* जब `gateway.auth.mode="password"`, तब `gateway.auth.password` (या `OPENCLAW_GATEWAY_PASSWORD`) का उपयोग करें।
* यदि `gateway.auth.rateLimit` कॉन्फ़िगर है और बहुत अधिक auth विफलताएँ होती हैं, तो endpoint `Retry-After` के साथ `429` लौटाता है।

## Request body

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "tool": "sessions_list",
  "action": "json",
  "args": {},
  "sessionKey": "main",
  "dryRun": false
}
```

फ़ील्ड्स:

* `tool` (string, आवश्यक): इनवोक किए जाने वाले टूल का नाम।
* `action` (string, वैकल्पिक): यदि टूल स्कीमा `action` का समर्थन करता है और args पेलोड में इसे छोड़ा गया है, तो इसे args में मैप किया जाता है।
* `args` (object, वैकल्पिक): टूल-विशिष्ट आर्ग्युमेंट्स।
* `sessionKey` (string, optional): target session key. If omitted or `"main"`, the Gateway uses the configured main session key (honors `session.mainKey` and default agent, or `global` in global scope).
* `dryRun` (boolean, वैकल्पिक): भविष्य के उपयोग के लिए आरक्षित; वर्तमान में अनदेखा किया जाता है।

## Policy + routing behavior

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

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

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

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

* `x-openclaw-message-channel: <channel>` (उदाहरण: `slack`, `telegram`)
* `x-openclaw-account-id: <accountId>` (जब कई खाते मौजूद हों)
* `gateway`
* `whatsapp_login`

आप इस deny list को `gateway.tools` के माध्यम से अनुकूलित कर सकते हैं:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  gateway: {
    tools: {
      // Additional tools to block over HTTP /tools/invoke
      deny: ["browser"],
      // Remove tools from the default deny list
      allow: ["gateway"],
    },
  },
}
```

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

* `x-openclaw-message-channel: <channel>` (उदाहरण: `slack`, `telegram`)
* `x-openclaw-account-id: <accountId>` (जब कई खाते मौजूद हों)

## Responses

* `200` → `{ ok: true, result }`
* `400` → `{ ok: false, error: { type, message } }` (अमान्य अनुरोध या टूल इनपुट त्रुटि)
* `401` → अनधिकृत
* `429` → auth rate-limited (`Retry-After` सेट)
* `404` → टूल उपलब्ध नहीं (नहीं मिला या allowlist में नहीं)
* `405` → विधि अनुमत नहीं
* `500` → `{ ok: false, error: { type, message } }` (अनपेक्षित टूल निष्पादन त्रुटि; सुरक्षित किया गया संदेश)

## Example

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -sS http://127.0.0.1:18789/tools/invoke \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "tool": "sessions_list",
    "action": "json",
    "args": {}
  }'
```