---
read_when:
    - استدعاء الأدوات دون تشغيل دورة وكيل كاملة
    - إنشاء عمليات أتمتة تحتاج إلى إنفاذ سياسة الأدوات
summary: استدعاء أداة واحدة مباشرةً عبر نقطة نهاية HTTP في Gateway
title: واجهة برمجة تطبيقات استدعاء الأدوات
x-i18n:
    generated_at: "2026-04-30T08:03:03Z"
    model: gpt-5.5
    provider: openai
    source_hash: 7ba20b7471de76e7f6bccc4d7a3d72c00d9d7b9843ad4e74825685c992a33f1a
    source_path: gateway/tools-invoke-http-api.md
    workflow: 16
---

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

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

ملاحظات:

- عند `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.rateLimit` مكوّنًا وحدث عدد كبير جدًا من إخفاقات المصادقة، فستعيد نقطة النهاية `429` مع `Retry-After`.

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

تعامل مع نقطة النهاية هذه كسطح **وصول كامل للمشغّل** إلى مثيل Gateway.

- مصادقة حامل HTTP هنا ليست نموذج نطاق ضيق لكل مستخدم.
- يجب التعامل مع رمز/كلمة مرور 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
{
  "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**.

ملاحظات حدود مهمة:

- موافقات التنفيذ هي حواجز حماية للمشغّل، وليست حد تفويض منفصلًا لنقطة نهاية HTTP هذه. إذا كانت الأداة قابلة للوصول هنا عبر مصادقة Gateway + سياسة الأدوات، فلن يضيف `/tools/invoke` مطالبة موافقة إضافية لكل استدعاء.
- لا تشارك اعتمادات حامل Gateway مع مستدعين غير موثوقين. إذا كنت تحتاج إلى فصل عبر حدود الثقة، فشغّل Gateways منفصلة (ومن الأفضل مستخدمي/مضيفي نظام تشغيل منفصلين).

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

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