---
read_when:
    - أنت تنشئ تطبيقًا خارجيًا أو برنامجًا نصيًا أو لوحة معلومات أو مهمة CI أو إضافة IDE تتواصل مع OpenClaw
    - أنت تختار بين استدعاء الإجراءات البعيدة لـ Gateway وحزمة تطوير البرمجيات الخاصة بـ Plugin
    - أنت تتكامل مع عمليات الوكيل أو الجلسات أو الأحداث أو الموافقات أو النماذج أو الأدوات في Gateway
    - أنت تقرن وحدة تحكم في الاستضافة بجدولة تنبيه خارجية
sidebarTitle: External apps
summary: مسار التكامل الحالي للتطبيقات الخارجية والبرامج النصية ولوحات المعلومات ومهام CI وملحقات بيئات التطوير المتكاملة
title: تكاملات Gateway للتطبيقات الخارجية
x-i18n:
    generated_at: "2026-07-12T05:55:16Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 0034db64dea64f8c5c400cf2adc69c6e046d0cd574914fe7497099018cb28745
    source_path: gateway/external-apps.md
    workflow: 16
---

تتواصل التطبيقات الخارجية مع OpenClaw عبر بروتوكول Gateway: نقل ويب سوكيت
بالإضافة إلى أساليب RPC. استخدمه عندما يريد برنامج نصي أو لوحة معلومات أو مهمة CI أو امتداد IDE
أو عملية أخرى بدء عمليات تشغيل الوكيل، أو بث الأحداث، أو انتظار
النتائج، أو إلغاء العمل، أو فحص موارد Gateway.

<Warning>
  لا توجد حزمة عميل عامة على npm حتى الآن. لا تُضف أسماء حزم عميل OpenClaw
  إلى تبعيات التطبيق إلى أن تعلن ملاحظات الإصدار عن حزمة منشورة
  وتتضمن هذه الصفحة تعليمات التثبيت.
</Warning>

<Note>
  هذه الصفحة مخصصة للتعليمات البرمجية الموجودة خارج عملية OpenClaw. أما تعليمات Plugin البرمجية التي تعمل
  داخل OpenClaw فينبغي أن تستخدم المسارات الفرعية الموثقة `openclaw/plugin-sdk/*` بدلًا من ذلك.
</Note>

## ما المتاح حاليًا

| الواجهة                                 | الحالة | الاستخدام                                                                                     |
| --------------------------------------- | ------ | --------------------------------------------------------------------------------------------- |
| [بروتوكول Gateway](/ar/gateway/protocol)   | جاهز   | نقل ويب سوكيت، ومصافحة الاتصال، ونطاقات المصادقة، وإصدارات البروتوكول، والأحداث.              |
| [مرجع Gateway RPC](/ar/reference/rpc)      | جاهز   | أساليب Gateway الحالية للوكلاء والجلسات والمهام والنماذج والأدوات والعناصر والاعتمادات.       |
| [`openclaw agent`](/ar/cli/agent)          | جاهز   | تكامل البرامج النصية أحادية التشغيل عندما يكفي استدعاء CLI عبر الصدفة.                       |
| [`openclaw message`](/ar/cli/message)      | جاهز   | إرسال الرسائل أو إجراءات القنوات من البرامج النصية.                                          |

يجري العمل داخليًا على حزمة مكتبة عميل مستقبلية، لكنها ليست
واجهة تثبيت عامة حتى الآن. تعامل معها كتفصيل تنفيذي تجريبي إلى أن
يُعلن إصدار عن حزمة منشورة وذات إصدار محدد.

## المسار الموصى به

1. شغّل Gateway أو اكتشفه.
2. اتصل عبر [بروتوكول Gateway](/ar/gateway/protocol).
3. استدعِ أساليب RPC الموثقة في [مرجع Gateway RPC](/ar/reference/rpc).
4. ثبّت إصدار OpenClaw الذي تختبر عليه.
5. أعد مراجعة مرجع RPC عند ترقية OpenClaw.

بالنسبة إلى عمليات تشغيل الوكيل، ابدأ بأسلوب RPC‏ `agent` واقرنه بـ `agent.wait` للحصول على
نتيجة نهائية. ولحالة المحادثة الدائمة، استخدم أساليب `sessions.*`.
أما تكاملات واجهة المستخدم، فاشترك في أحداث Gateway واعرض فقط
فئات الأحداث التي يفهمها تطبيقك.

## التعليق التعاوني للمضيف

يمكن لوحدات تحكم الاستضافة التي تجمّد عملية قيد التشغيل أو تأخذ لقطة منها استخدام
مصافحة التعليق المحايدة تجاه المضيف:

1. أوقف قبول حركة الدخول الخارجية التي يتحكم فيها المضيف.
2. استدعِ `gateway.suspend.prepare` باستخدام `requestId` ثابت وفريد.
3. إذا كانت الاستجابة `busy`، فأبقِ العملية قيد التشغيل وأعد المحاولة لاحقًا.
4. إذا كانت `ready`، فاحفظ `suspensionId` المُعاد، ثم جمّد العملية أو التقط
   لقطة لها قبل `expiresAtMs`.
5. بعد استئناف العملية من التجميد، أو إذا أُلغي التعليق، استدعِ `gateway.suspend.resume`
   باستخدام `suspensionId` نفسه عبر اتصال ويب سوكيت الحالي أو مسار تحكم
   Admin HTTP.

يرفض Gateway المُعَدّ مسبقًا مصافحات ويب سوكيت الجديدة. يجب على وحدة تحكم ويب سوكيت
إبقاء اتصالها الموثّق مفتوحًا طوال عملية المضيف. إذا تعذّر
ضمان ذلك، ففعّل واستخدم
[Plugin ‏Admin HTTP RPC](/ar/plugins/admin-http-rpc) قبل الإعداد. إذا فُقد
مسار التحكم، فانتظر انتهاء مدة الإيجار البالغة دقيقتين قبل
إعادة الاتصال؛ إذ يعيد انتهاء الصلاحية فتح القبول تلقائيًا.

عقد RPC هو:

- `gateway.suspend.prepare` — `operator.admin`؛ المعاملات
  `{ "requestId": "stable-host-operation-id" }`
- `gateway.suspend.status` — `operator.read`؛ المعاملات
  `{ "suspensionId": "id-from-prepare" }`
- `gateway.suspend.resume` — `operator.admin`؛ المعاملات
  `{ "suspensionId": "id-from-prepare" }`

تُزال المسافات المحيطة بالمُعرّفات، ويجب أن تحتوي على محرف واحد على الأقل غير فارغ، كما يقتصر طولها على
128 محرفًا. تتضمن نتيجة الإعداد المشغول `status: "busy"` و`reason`
و`retryAfterMs` و`activeCount` و`blockers`. وتكون نتيجة الجاهزية بهذا الشكل:

```json
{
  "status": "ready",
  "suspensionId": "2c3f...",
  "expiresAtMs": 1770000000000,
  "activeCount": 0,
  "blockers": []
}
```

تعيد الحالة `{"status":"running"}` أو نتيجة جاهزية تتضمن `expiresAtMs`.
ويعيد الاستئناف `{"ok":true,"status":"running","resumed":true}`؛ أما تكراره
بعد استئناف ناجح فيعيد `resumed: false`.

يؤدي استخدام مُعرّف طلب متعارض أو حدوث فشل عابر في استئناف المُجدول إلى إعادة
`UNAVAILABLE` قابل لإعادة المحاولة مع `retryAfterMs`. أثناء استعادة المُجدول، تعيد عمليات الإعداد والحالة
والاستئناف جميعها هذا الخطأ، ويبقى Gateway غير جاهز
ومغلقًا عند الفشل، ويجب ألا يجمّده المضيف أو يأخذ لقطة منه. يعيد OpenClaw محاولة
تشغيل المُجدول تلقائيًا، ولا يعيد فتح القبول إلا بعد نجاح الاستعادة. ويعيد
مُعرّف استئناف غير مطابق `INVALID_REQUEST`. يشترك الإعداد في
ميزانية الكتابة لمستوى تحكم Gateway، والبالغة ثلاث محاولات في الدقيقة؛ التزم بمدة
تأخير إعادة المحاولة المُعادة. تُقسّم عملاء ويب سوكيت إلى مجموعات حسب الجهاز وعنوان IP. أما وحدات تحكم
Admin HTTP فتُقسّم حسب عنوان IP المحسوم للعميل، ولذلك قد تتشارك وحدات التحكم الموجودة خلف وكيل واحد
الميزانية نفسها.

الإعداد قائم على الرفض فقط: يغلق OpenClaw قبول الجذر والجلسات والأوامر الجديدة،
ويوقف مؤقتًا نبضات Cron التلقائية، ويفحص العمل بصورة متزامنة. إذا كان أي شيء
نشطًا، فإنه يستأنف المُجدول ويعيد فتح القبول قبل إعادة
`busy`؛ ولا يقاطع ذلك العمل أو يفرّغه. يستمر إيجار الجاهزية
دقيقتين. يؤدي تكرار `prepare` باستخدام `requestId` نفسه إلى تجديده؛ ويستأنف انتهاء الصلاحية
المُجدول قبل إعادة فتح القبول.
أما إرسال إعادة التشغيل الذي يحين موعده خلال إيجار الجاهزية، فينتظر حتى استئناف الإيجار؛ وتجعل
إعادة التشغيل الجارية الإعداد يعيد `busy`.

أثناء الجاهزية، يظل `/healthz` نشطًا ويعيد `/readyz` الرمز `503`. تتضمن استجابات
الجاهزية المحلية أو الموثّقة `gateway-draining`؛ بينما لا تتلقى
اختبارات الفحص البعيدة غير الموثّقة سوى `{ "ready": false }`. يظل اختبار سلامة HTTP،
وأساليب التعليق على اتصالات ويب سوكيت القائمة، ومسار
Admin HTTP RPC المفعّل مسبقًا متاحًا. أما استدعاءات RPC الأخرى فتعيد
`UNAVAILABLE` قابلًا لإعادة المحاولة. وتعيد مسارات HTTP المضمّنة لأعمال المستخدم ومسارات HTTP العادية الخاصة بالـ Plugins،
بما فيها واجهات API المتوافقة مع OpenAI، وعمليات الأدوات والجلسات، ومراقبات Node،
والخطافات المُعدّة، الرمز `503` مع `error.code: "gateway_unavailable"`. كما تعيد
ترقيات ويب سوكيت الجديدة المملوكة للـ Plugins الرمز `503`؛ ويغطي ذلك
ملكية الترقية، لا العمل المنفّذ لاحقًا عبر مقبس Plugin قائم.

لا تحفظ هذه المصافحة الرسائل الواردة، ولا توقف وسائل نقل القنوات التابعة لجهات خارجية،
ولا تتحكم في منصة الاستضافة. يجب على المضيف عزل حركة الدخول الخاصة به
قبل الإعداد، ويظل مسؤولًا عن الإيقاظ واللقطة أو التجميد
والإيقاف. يمثّل `activeCount` العدد الإجمالي للأعمال المتتبعة، بينما يحتوي `blockers`
على أعداد الفئات غير الصفرية وتفاصيل محدودة للمهام. وهذا ليس
حاجزًا عامًا لسكون العملية. الحاجب `background-exec` إجمالي
فقط: لا تعبر البروتوكول مطلقًا نصوص الأوامر أو مُعرّفات العمليات أو المخرجات أو مُعرّفات الجلسات أو النطاقات.
وقد تظل سلامة القناة والصيانة وتحديث ذاكرة التخزين المؤقت وجلسات
ويب سوكيت القائمة الخاصة بالـ Plugins والأعمال الخلفية غير المسجلة والمملوكة للـ Plugins
نشطة.
يجب على منصة الاستضافة تجميد شجرة العمليات الكاملة ونظام ملفاتها أو أخذ لقطة منهما
بشكل متسق؛ ولا يمكن لهذا العقد الأول إثبات خمول العمل غير المسجل.

<Tip>
  لجدولة إيقاظ المضيف، احتفظ بالجزء المواجه لـ OpenClaw داخل
  Plugin يعمل ضمن العملية، وأسقط لقطات كاملة قابلة للتكرار بأمان على محوّل المضيف الخارجي.
  ينبغي ألا تستورد وحدة تحكم الاستضافة حزمة Plugin SDK أو تعيد بناء حالة Cron
  من فروق الأحداث. راجع [الإسقاط الآمن لـ Cron الخارجي
  ](/ar/plugins/hooks#safe-external-cron-projection).
</Tip>

## تعليمات التطبيق البرمجية مقارنة بتعليمات Plugin البرمجية

استخدم Gateway RPC عندما تكون التعليمات البرمجية خارج OpenClaw:

- برامج Node النصية التي تبدأ عمليات تشغيل الوكيل أو تراقبها
- مهام CI التي تستدعي Gateway
- لوحات المعلومات ولوحات الإدارة
- امتدادات IDE
- الجسور الخارجية التي لا تحتاج إلى أن تصبح Plugins للقنوات
- اختبارات التكامل باستخدام وسائل نقل Gateway وهمية أو حقيقية

استخدم Plugin SDK عندما تعمل التعليمات البرمجية داخل OpenClaw:

- Plugins لمزوّدي الخدمة
- Plugins للقنوات
- خطافات الأدوات أو دورة الحياة
- Plugins لأُطر تشغيل الوكلاء
- مساعدات وقت تشغيل موثوقة

ينبغي ألا تستورد التطبيقات الخارجية `openclaw/plugin-sdk/*`؛ فهذه المسارات الفرعية مخصصة
للـ Plugins التي يحمّلها OpenClaw.

## ذو صلة

- [بروتوكول Gateway](/ar/gateway/protocol)
- [مرجع Gateway RPC](/ar/reference/rpc)
- [أمر الوكيل في CLI](/ar/cli/agent)
- [أمر الرسائل في CLI](/ar/cli/message)
- [حلقة الوكيل](/ar/concepts/agent-loop)
- [بيئات تشغيل الوكيل](/ar/concepts/agent-runtimes)
- [الجلسات](/ar/concepts/session)
- [المهام الخلفية](/ar/automation/tasks)
- [وكلاء ACP](/ar/tools/acp-agents)
- [نظرة عامة على Plugin SDK](/ar/plugins/sdk-overview)