> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

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

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

## المصادقة

تستخدم إعدادات مصادقة 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 من
  مصدر وكيل موثوق مهيأ؛ وتتطلب وكلاء 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 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`

## جسم الطلب

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "tool": "sessions_list",
  "action": "json",
  "args": {},
  "sessionKey": "main",
  "dryRun": false
}
```

الحقول:

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

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

* `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`:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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`. لا تزال مصادقة Bearer بالسر المشترك
تتبع قاعدة المشغّل الموثوق الكاملة أعلاه.

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

* `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 } }` (خطأ غير متوقع في تنفيذ الأداة؛ رسالة منقحة)

## مثال

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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](/ar/gateway/protocol)
* [الأدوات وPlugins](/ar/tools)