---
read_when:
    - استدعاء الأدوات دون تشغيل دورة وكيل كاملة
    - إنشاء عمليات أتمتة تتطلب فرض سياسات الأدوات
summary: استدعِ أداة واحدة مباشرةً عبر نقطة نهاية HTTP الخاصة بـ Gateway
title: تستدعي الأدوات واجهة API
x-i18n:
    generated_at: "2026-07-12T05:56:50Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 6d07f765d63255e718d5e558b662589e77b2992538f43288cd83e6e3f2a06dda
    source_path: gateway/tools-invoke-http-api.md
    workflow: 16
---

تكشف 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 أو الإدخال الخاص؛ ولا تكشفها مباشرةً للإنترنت العام.

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

| وضع المصادقة                                                                          | السلوك                                                                                                                                                                                                                                                                                                                                 |
| -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `token` أو `password` مع `Authorization: Bearer ...`                                   | يثبت امتلاك سر مشغّل Gateway المشترك. يتجاهل `x-openclaw-scopes` الأضيق نطاقًا. يستعيد مجموعة نطاقات المشغّل الافتراضية الكاملة: `operator.admin` و`operator.approvals` و`operator.pairing` و`operator.read` و`operator.talk.secrets` و`operator.write`. يعامل الاستدعاءات المباشرة للأدوات على أنها أدوار واردة من المالك. |
| HTTP موثوق حامل للهوية (مصادقة وكيل موثوق، أو `mode="none"` عند إدخال خاص)            | يصادق هوية خارجية موثوقة أو حد النشر. يحترم `x-openclaw-scopes` عند وجودها. يعود إلى مجموعة نطاقات المشغّل الافتراضية المعتادة عند غياب الترويسة. لا يفقد دلالات المالك إلا عندما يضيّق المستدعي النطاقات صراحةً ويحذف `operator.admin`.                                                                                              |

## نص الطلب

```json
{
  "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 أيضًا قائمة رفض صارمة افتراضيًا (حتى إذا سمحت سياسة الجلسة بالأداة):

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

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

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

```json5
{
  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>` (سياق سلسلة المحادثة لسياسة أداة الرسائل)

## الاستجابات

| الحالة | المعنى                                                                                                   |
| ------ | -------------------------------------------------------------------------------------------------------- |
| `200`  | `{ ok: true, result }`                                                                                   |
| `400`  | `{ ok: false, error: { type, message } }` (طلب غير صالح أو خطأ في مدخلات الأداة)                        |
| `401`  | غير مصرح                                                                                                 |
| `403`  | `{ ok: false, error: { type, message, requiresApproval? } }` (حظرت السياسة استدعاء الأداة)              |
| `404`  | الأداة غير متاحة (غير موجودة أو غير مدرجة في قائمة السماح)                                             |
| `405`  | الطريقة غير مسموح بها                                                                                    |
| `408`  | انتهت مهلة قراءة نص الطلب                                                                                |
| `413`  | تجاوز نص الطلب الحد الأقصى لحجم الحمولة                                                                  |
| `429`  | فُرض حد للمعدل على المصادقة (تم تعيين `Retry-After`)                                                    |
| `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)
- [الأدوات والإضافات](/ar/tools)