उपकरण API को कॉल करते हैं

• POST /tools/invoke
• Gateway जैसा ही port (WS + HTTP multiplex): http://<gateway-host>:<port>/tools/invoke

​

प्रमाणीकरण

• shared-secret auth (gateway.auth.mode="token" या "password"): Authorization: Bearer <token-or-password>
• trusted identity-bearing HTTP auth (gateway.auth.mode="trusted-proxy"): configured identity-aware proxy के माध्यम से route करें और उसे आवश्यक identity headers inject करने दें
• private-ingress open auth (gateway.auth.mode="none"): कोई auth header आवश्यक नहीं

• जब gateway.auth.mode="token" हो, तो gateway.auth.token (या OPENCLAW_GATEWAY_TOKEN) का उपयोग करें।
• जब gateway.auth.mode="password" हो, तो gateway.auth.password (या OPENCLAW_GATEWAY_PASSWORD) का उपयोग करें।
• जब gateway.auth.mode="trusted-proxy" हो, तो HTTP request को configured trusted proxy source से आना चाहिए; same-host loopback proxies के लिए explicit gateway.auth.trustedProxy.allowLoopback = true आवश्यक है।
• Internal same-host callers जो proxy को bypass करते हैं, वे local direct fallback के रूप में gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD का उपयोग कर सकते हैं। कोई भी Forwarded, X-Forwarded-*, या X-Real-IP header evidence request को इसके बजाय trusted-proxy path पर रखता है।
• यदि gateway.auth.rateLimit configured है और बहुत अधिक auth failures होते हैं, तो endpoint Retry-After के साथ 429 लौटाता है।

​

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

• यहां HTTP bearer auth कोई संकीर्ण per-user scope model नहीं है।
• इस endpoint के लिए valid Gateway token/password को owner/operator credential जैसा माना जाना चाहिए।
• shared-secret auth modes (token और password) के लिए, endpoint normal full operator defaults restore करता है, भले ही caller एक संकरा x-openclaw-scopes header भेजे।
• Shared-secret auth इस endpoint पर direct tool invokes को owner-sender turns भी मानता है।
• Trusted identity-bearing HTTP modes (उदाहरण के लिए trusted proxy auth या private ingress पर gateway.auth.mode="none") मौजूद होने पर x-openclaw-scopes का सम्मान करते हैं और अन्यथा normal operator default scope set पर fall back करते हैं।
• इस endpoint को केवल loopback/tailnet/private ingress पर रखें; इसे सीधे public internet पर expose न करें।

• gateway.auth.mode="token" या "password" + Authorization: Bearer ...
  • shared gateway operator secret के possession को prove करता है
  • संकरे x-openclaw-scopes को ignore करता है
  • full default operator scope set restore करता है: operator.admin, operator.approvals, operator.pairing, operator.read, operator.talk.secrets, operator.write
  • इस endpoint पर direct tool invokes को owner-sender turns मानता है
• trusted identity-bearing HTTP modes (उदाहरण के लिए trusted proxy auth, या private ingress पर gateway.auth.mode="none")
  • किसी outer trusted identity या deployment boundary को authenticate करते हैं
  • header मौजूद होने पर x-openclaw-scopes का सम्मान करते हैं
  • header अनुपस्थित होने पर normal operator default scope set पर fall back करते हैं
  • owner semantics केवल तब खोते हैं जब caller स्पष्ट रूप से scopes को narrow करता है और operator.admin को omit करता है

​

Request body

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

• tool (string, आवश्यक): invoke करने के लिए टूल नाम।
• action (string, वैकल्पिक): यदि tool schema action को support करता है और args payload ने इसे omit किया है, तो args में mapped किया जाता है।
• args (object, वैकल्पिक): tool-specific arguments।
• sessionKey (string, वैकल्पिक): target session key। यदि omit किया गया है या "main" है, तो Gateway configured main session key का उपयोग करता है (session.mainKey और default agent का सम्मान करता है, या global scope में global)।
• dryRun (boolean, वैकल्पिक): future use के लिए reserved; अभी ignored है।

​

Policy + routing behavior

• tools.profile / tools.byProvider.profile
• tools.allow / tools.byProvider.allow
• agents.<id>.tools.allow / agents.<id>.tools.byProvider.allow
• group policies (यदि session key किसी group या channel पर map होती है)
• subagent policy (subagent session key के साथ invoke करते समय)

• Exec approvals operator guardrails हैं, इस HTTP endpoint के लिए कोई separate authorization boundary नहीं। यदि कोई टूल यहां Gateway auth + tool policy के माध्यम से reachable है, तो /tools/invoke कोई extra per-call approval prompt नहीं जोड़ता।
• यदि exec यहां reachable है, तो इसे mutating shell surface मानें। write, edit, apply_patch, या HTTP filesystem-write tools को deny करना shell execution को read-only नहीं बनाता।
• Gateway bearer credentials को untrusted callers के साथ share न करें। यदि आपको trust boundaries के बीच separation चाहिए, तो separate gateways चलाएं (और ideally separate OS users/hosts)।

• exec - direct command execution (RCE surface)
• spawn - arbitrary child process creation (RCE surface)
• shell - shell command execution (RCE surface)
• fs_write - host पर arbitrary file mutation
• fs_delete - host पर arbitrary file deletion
• fs_move - host पर arbitrary file move/rename
• apply_patch - patch application arbitrary files rewrite कर सकता है
• sessions_spawn - session orchestration; agents को remotely spawn करना RCE है
• sessions_send - cross-session message injection
• cron - persistent automation control plane
• gateway - gateway control plane; HTTP के माध्यम से reconfiguration रोकता है
• nodes - node command relay paired hosts पर system.run तक पहुंच सकता है
• whatsapp_login - terminal QR scan की आवश्यकता वाला interactive setup; HTTP पर hangs

{
  gateway: {
    tools: {
      // Additional tools to block over HTTP /tools/invoke
      deny: ["browser"],
      // Remove tools from the default deny list for owner/admin callers
      allow: ["gateway"],
    },
  },
}

• x-openclaw-message-channel: <channel> (उदाहरण: slack, telegram)
• x-openclaw-account-id: <accountId> (जब multiple accounts मौजूद हों)

​

Responses

• 200 → { ok: true, result }
• 400 → { ok: false, error: { type, message } } (invalid request या tool input error)
• 401 → unauthorized
• 429 → auth rate-limited (Retry-After set)
• 404 → tool available नहीं है (not found या allowlisted नहीं)
• 405 → method allowed नहीं है
• 500 → { ok: false, error: { type, message } } (unexpected tool execution error; sanitized message)

​

उदाहरण

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 protocol
• Tools and plugins