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

• POST /tools/invoke
• المنفذ نفسه مثل Gateway (تعدد إرسال WS + HTTP): http://<gateway-host>:<port>/tools/invoke

​

المصادقة

• مصادقة السر المشترك (gateway.auth.mode="token" أو "password"): Authorization: Bearer <token-or-password>
• مصادقة HTTP موثوقة تحمل هوية (gateway.auth.mode="trusted-proxy"): وجّه الطلب عبر الوكيل المهيأ والواعي بالهوية ودعه يحقن ترويسات الهوية المطلوبة
• مصادقة مفتوحة عبر مدخل خاص (gateway.auth.mode="none"): لا يلزم ترويسة مصادقة

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

• gateway.auth.mode="token" أو "password" + Authorization: Bearer ...
  • يثبت امتلاك سر مشغّل Gateway المشترك
  • يتجاهل x-openclaw-scopes الأضيق
  • يستعيد مجموعة نطاقات المشغّل الافتراضية الكاملة: operator.admin, operator.approvals, operator.pairing, operator.read, operator.talk.secrets, operator.write
  • يتعامل مع استدعاءات الأدوات المباشرة على نقطة النهاية هذه كدورات مرسِل مالك
• أوضاع HTTP التي تحمل هوية موثوقة (مثل مصادقة الوكيل الموثوق، أو gateway.auth.mode="none" على مدخل خاص)
  • تصادق هوية خارجية موثوقة أو حد نشر موثوق
  • تحترم x-openclaw-scopes عندما تكون الترويسة موجودة
  • ترجع إلى مجموعة نطاقات المشغّل الافتراضية المعتادة عندما تكون الترويسة غائبة
  • تفقد دلالات المالك فقط عندما يضيّق المتصل النطاقات صراحة ويحذف operator.admin

​

جسم الطلب

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

• tool (سلسلة نصية، مطلوب): اسم الأداة المطلوب استدعاؤها.
• action (سلسلة نصية، اختياري): يُعيَّن ضمن args إذا كان مخطط الأداة يدعم action وكانت حمولة args قد حذفته.
• args (كائن، اختياري): وسائط خاصة بالأداة.
• sessionKey (سلسلة نصية، اختياري): مفتاح الجلسة الهدف. إذا حُذف أو كان "main"، تستخدم Gateway مفتاح الجلسة الرئيسي المهيأ (مع احترام session.mainKey والوكيل الافتراضي، أو global في النطاق العام).
• 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 Bearer مع متصلين غير موثوقين. إذا كنت تحتاج إلى فصل عبر حدود الثقة، فشغّل Gateways منفصلة (ويُفضّل أيضًا مستخدمين/مضيفين منفصلين على نظام التشغيل).

• exec - تنفيذ أوامر مباشر (سطح RCE)
• spawn - إنشاء عمليات فرعية عشوائية (سطح RCE)
• shell - تنفيذ أوامر الصدفة (سطح RCE)
• fs_write - تعديل عشوائي للملفات على المضيف
• fs_delete - حذف عشوائي للملفات على المضيف
• fs_move - نقل/إعادة تسمية عشوائية للملفات على المضيف
• apply_patch - يمكن لتطبيق الرقع إعادة كتابة ملفات عشوائية
• sessions_spawn - تنسيق الجلسات؛ إنشاء وكلاء عن بُعد هو RCE
• sessions_send - حقن رسائل عبر الجلسات
• cron - مستوى تحكم للأتمتة المستمرة
• gateway - مستوى تحكم Gateway؛ يمنع إعادة التهيئة عبر HTTP
• nodes - يمكن لترحيل أوامر العقد الوصول إلى system.run على المضيفين المقترنين
• whatsapp_login - إعداد تفاعلي يتطلب مسح QR من الطرفية؛ يتوقف على HTTP

{
  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> (عند وجود حسابات متعددة)

​

الاستجابات

• 200 → { ok: true, result }
• 400 → { ok: false, error: { type, message } } (طلب غير صالح أو خطأ في إدخال الأداة)
• 401 → غير مخوّل
• 429 → محدد المعدل بسبب المصادقة (Retry-After مضبوط)
• 404 → الأداة غير متاحة (غير موجودة أو غير مدرجة في قائمة السماح)
• 405 → الطريقة غير مسموح بها
• 500 → { ok: false, error: { type, 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
• الأدوات وPlugins