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

# واجهة برمجة تطبيقات استدعاء الأدوات

# استدعاء الأدوات (HTTP)

تُوفّر Gateway في OpenClaw نقطة نهاية HTTP بسيطة لاستدعاء أداة واحدة مباشرة. تكون مُمكّنة دائمًا، لكنها مقيّدة بمصادقة Gateway وسياسة الأدوات.

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

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

## المصادقة

تستخدم تهيئة مصادقة Gateway. أرسل رمز Bearer:

* `Authorization: Bearer <token>`

ملاحظات:

* عند `gateway.auth.mode="token"`، استخدم `gateway.auth.token` (أو `OPENCLAW_GATEWAY_TOKEN`).
* عند `gateway.auth.mode="password"`، استخدم `gateway.auth.password` (أو `OPENCLAW_GATEWAY_PASSWORD`).
* إذا تم تكوين `gateway.auth.rateLimit` وحدث عدد كبير جدًا من إخفاقات المصادقة، فستُرجع نقطة النهاية `429` مع `Retry-After`.

## طلب الجسم

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

الحقول:

* `tool` (string، مطلوب): اسم الأداة المراد استدعاؤها.
* `action` (string، اختياري): يُدرج في args إذا كان مخطط الأداة يدعم `action` ولم تتضمن حمولة args هذا الحقل.
* `args` (object، اختياري): وسائط خاصة بالأداة.
* `sessionKey` (string، اختياري): مفتاح الجلسة الهدف. إذا تم إهماله أو كان `"main"`، تستخدم Gateway مفتاح الجلسة الرئيسي المُهيّأ (مع احترام `session.mainKey` والوكيل الافتراضي، أو `global` في النطاق العام).
* `dryRun` (boolean، اختياري): محجوز للاستخدام المستقبلي؛ يتم تجاهله حاليًا.

## السلوك الخاص بالسياسات والتوجيه

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

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

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

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

* `sessions_spawn`
* `sessions_send`
* `gateway`
* `whatsapp_login`

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

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  gateway: {
    tools: {
      // أدوات إضافية لحظرها عبر HTTP /tools/invoke
      deny: ["browser"],
      // إزالة أدوات من قائمة الحظر الافتراضية
      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 } }` (خطأ غير متوقع أثناء تنفيذ الأداة؛ رسالة منقّحة)

## مثال

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -sS http://127.0.0.1:18789/tools/invoke \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "tool": "sessions_list",
    "action": "json",
    "args": {}
  }'
```