---
read_when:
    - استدعاء الأدوات دون تشغيل دورة وكيل كاملة
    - بناء عمليات أتمتة تحتاج إلى إنفاذ سياسات الأدوات
summary: استدعِ أداة واحدة مباشرةً عبر نقطة نهاية HTTP الخاصة بـ Gateway
title: واجهة API لاستدعاء الأدوات
x-i18n:
    generated_at: "2026-05-10T19:42:44Z"
    model: gpt-5.5
    provider: openai
    source_hash: 531e77673fb9c06d0cc8f8145d874e22f7e590dc3e4c5dee1574874af5666886
    source_path: gateway/tools-invoke-http-api.md
    workflow: 16
---

يكشف 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`

## جسم الطلب

```json
{
  "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`:

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

## مثال

```bash
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)