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

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

• 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"): لا تلزم ترويسة مصادقة

ملاحظات:

• يستخدم 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.

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

تعامل مع نقطة النهاية هذه بوصفها واجهة وصول كامل للمشغّل إلى مثيل Gateway.

• مصادقة حامل 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 (قيمة منطقية، اختياري): محجوز للاستخدام المستقبلي؛ ويُتجاهل حاليًا.

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

تُرشَّح إتاحة الأدوات عبر سلسلة السياسات نفسها التي تستخدمها وكلاء 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 مع مستدعين غير موثوقين. إذا احتجت إلى الفصل بين حدود الثقة، فشغّل بوابات Gateway منفصلة (ويُفضّل تشغيلها تحت مستخدمي نظام تشغيل أو مضيفين منفصلين).

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

كما أن cron وgateway وnodes مقتصرة على المالك: حتى خارج قائمة الرفض الافتراضية هذه، لا يمكن للمستدعين من غير المالك استدعاؤها عبر هذه الواجهة.

خصّص قائمة الرفض العامة عبر gateway.tools:

{  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"],    },  },}

يمثل gateway.tools.allow تجاوزًا للإتاحة، وليس ترقية للنطاق. في أوضاع HTTP الحاملة للهوية، تظل cron وgateway وnodes غير متاحة للمستدعين الذين لا يملكون هوية المالك/المسؤول (operator.admin)، حتى عند إدراجها في gateway.tools.allow. وتظل مصادقة حامل السر المشترك تتبع قاعدة المشغّل الموثوق بالكامل المذكورة أعلاه.

للمساعدة في تمكين سياسات المجموعة من تحديد السياق، يمكنك اختياريًا تعيين:

• 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
• الأدوات والإضافات