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

يكشف Gateway الخاص بـ OpenClaw عن نقطة نهاية HTTP بسيطة لاستدعاء أداة واحدة مباشرة. تكون مفعّلة دائمًا وتستخدم مصادقة Gateway بالإضافة إلى سياسة الأدوات. مثل سطح /v1/* المتوافق مع OpenAI، تُعامل مصادقة الحامل ذات السر المشترك كوصول مشغّل موثوق به للبوابة بالكامل.

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

الحد الأقصى الافتراضي لحجم الحمولة هو 2 ميغابايت.

​

المصادقة

تستخدم تهيئة مصادقة Gateway.

مسارات مصادقة HTTP الشائعة:

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

​

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

تعامل مع نقطة النهاية هذه كسطح وصول كامل للمشغّل لمثيل البوابة.

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

مصفوفة المصادقة:

• gateway.auth.mode="token" أو "password" + Authorization: Bearer ...
  • يثبت امتلاك سر مشغّل البوابة المشترك
  • يتجاهل 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 (سلسلة نصية، اختياري): يُعيّن ضمن الوسائط إذا كان مخطط الأداة يدعم action وكانت حمولة الوسائط قد حذفته.
• args (كائن، اختياري): وسيطات خاصة بالأداة.
• sessionKey (سلسلة نصية، اختياري): مفتاح الجلسة الهدف. إذا حُذف أو كان "main"، يستخدم Gateway مفتاح الجلسة الرئيسي المهيأ (يحترم session.mainKey والوكيل الافتراضي، أو global في النطاق العام).
• dryRun (قيمة منطقية، اختياري): محجوز للاستخدام المستقبلي؛ يتم تجاهله حاليًا.

​

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

تُرشّح إتاحة الأدوات عبر سلسلة السياسات نفسها المستخدمة بواسطة وكلاء Gateway:

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

إذا لم تكن الأداة مسموحة بالسياسة، فستعيد نقطة النهاية 404.

ملاحظات حدود مهمة:

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

يطبق HTTP الخاص بـ Gateway أيضًا قائمة رفض صارمة افتراضيًا (حتى إذا سمحت سياسة الجلسة بالأداة):

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

يمكنك تخصيص قائمة الرفض هذه عبر gateway.tools:

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

​

الاستجابات

• 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