تستدعي الأدوات واجهة API

• POST /tools/invoke
• المنفذ نفسه الذي تستخدمه Gateway (تعدد إرسال WS وHTTP): http://<gateway-host>:<port>/tools/invoke
• الحد الأقصى الافتراضي لحجم نص الطلب: 2 ميغابايت

​

المصادقة

• مصادقة السر المشترك (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 من مصدر وكيل موثوق مهيأ؛ وتتطلب وكلاء local loopback على المضيف نفسه تعيين gateway.auth.trustedProxy.allowLoopback = true صراحةً.
• يمكن للجهات الداخلية المستدعية على المضيف نفسه التي تتجاوز الوكيل استخدام gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD كخيار احتياطي محلي مباشر. ويؤدي وجود أي دليل في ترويسات Forwarded أو X-Forwarded-* أو X-Real-IP إلى إبقاء الطلب على مسار الوكيل الموثوق بدلًا من ذلك.
• إذا كان gateway.auth.rateLimit مهيأً وحدثت إخفاقات مصادقة كثيرة جدًا، فتعيد نقطة النهاية 429 مع Retry-After.

​

الحد الأمني (مهم)

• مصادقة حامل HTTP هنا ليست نموذج نطاق ضيقًا لكل مستخدم.
• يجب التعامل مع رمز Gateway المميز/كلمة المرور الصالحة لنقطة النهاية هذه باعتبارها بيانات اعتماد للمالك/المشغّل.
• في أوضاع مصادقة السر المشترك (token وpassword)، تستعيد نقطة النهاية الإعدادات الافتراضية المعتادة للوصول الكامل للمشغّل، حتى إذا أرسل المستدعي ترويسة x-openclaw-scopes أضيق نطاقًا.
• تعامل مصادقة السر المشترك أيضًا الاستدعاءات المباشرة للأدوات على نقطة النهاية هذه على أنها أدوار واردة من المالك.
• تحترم أوضاع HTTP الموثوقة الحاملة للهوية (مصادقة الوكيل الموثوق، أو gateway.auth.mode="none" عند إدخال خاص) الترويسة x-openclaw-scopes عند وجودها، وإلا تعود إلى مجموعة النطاقات الافتراضية المعتادة للمشغّل.
• أبقِ نقطة النهاية هذه مقتصرة على local loopback أو شبكة Tailscale أو الإدخال الخاص؛ ولا تكشفها مباشرةً للإنترنت العام.

​

نص الطلب

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

• tool / name (سلسلة نصية، مطلوب): اسم الأداة المراد استدعاؤها. تكون الأولوية لـname إذا أُرسل كلاهما.
• action (سلسلة نصية، اختياري): يُدمج في args.action إذا كان مخطط الأداة يدعم الخاصية action ولم تكن args قد عيّنتها بالفعل.
• args (كائن، اختياري): وسائط خاصة بالأداة.
• sessionKey (سلسلة نصية، اختياري): مفتاح الجلسة المستهدفة. إذا حُذف أو كان "main"، تستخدم Gateway مفتاح الجلسة الرئيسية المهيأ (مع مراعاة session.mainKey والوكيل الافتراضي، أو global في نطاق الجلسة العام).
• agentId (سلسلة نصية، اختياري): يحل مفتاح الجلسة لذلك الوكيل. يعيد خطأ 400 إذا تعارض مع sessionKey صريح مرتبط مسبقًا بوكيل مختلف.
• idempotencyKey (سلسلة نصية، اختياري): يُستخدم لاشتقاق معرّف ثابت لاستدعاء الأداة.
• dryRun (قيمة منطقية، اختياري): محجوز للاستخدام المستقبلي؛ ويُتجاهل حاليًا.

​

سلوك السياسة والتوجيه

• tools.profile / tools.byProvider.profile
• tools.allow / tools.byProvider.allow
• agents.<id>.tools.allow / agents.<id>.tools.byProvider.allow
• سياسات المجموعة (إذا كان مفتاح الجلسة مرتبطًا بمجموعة أو قناة)
• سياسة الوكيل الفرعي (عند الاستدعاء باستخدام مفتاح جلسة وكيل فرعي)

• موافقات exec هي ضوابط حماية للمشغّل، وليست حد تفويض منفصلًا لنقطة نهاية HTTP هذه. إذا أمكن الوصول إلى أداة هنا عبر مصادقة Gateway وسياسة الأدوات، فلن يضيف /tools/invoke مطالبة موافقة إضافية لكل استدعاء.
• إذا أمكن الوصول إلى exec هنا، فتعامل معه بوصفه واجهة صدفة قادرة على إجراء تغييرات. إن رفض write أو edit أو apply_patch أو أدوات HTTP التي تكتب إلى نظام الملفات لا يجعل تنفيذ أوامر الصدفة للقراءة فقط.
• لا تشارك بيانات اعتماد حامل Gateway مع مستدعين غير موثوقين. إذا احتجت إلى الفصل بين حدود الثقة، فشغّل بوابات Gateway منفصلة (ويُفضّل تشغيلها تحت مستخدمي نظام تشغيل أو مضيفين منفصلين).

{
  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> (عند وجود حسابات متعددة)
• 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
• الأدوات والإضافات