---
read_when:
    - تنفيذ موافقات اقتران Node دون واجهة macOS الرسومية
    - إضافة تدفقات CLI للموافقة على العقد البعيدة
    - توسيع بروتوكول Gateway بإدارة العُقد
summary: اقتران العقد المملوك من Gateway (الخيار ب) لنظام iOS والعقد البعيدة الأخرى
title: الاقتران المملوك لـ Gateway
x-i18n:
    generated_at: "2026-06-27T17:42:37Z"
    model: gpt-5.5
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: aefddafaef419fc59b04ee17dae8ef21685b4f514f4286530bf07362663a8996
    source_path: gateway/pairing.md
    workflow: 16
---

في الإقران المملوك من Gateway، يكون **Gateway** هو مصدر الحقيقة للعُقد
المسموح لها بالانضمام. واجهات المستخدم (تطبيق macOS، والعملاء المستقبليون) ليست إلا واجهات أمامية
توافق على الطلبات المعلّقة أو ترفضها.

**مهم:** تستخدم عُقد WS **إقران الأجهزة** (الدور `node`) أثناء `connect`.
`node.pair.*` هو مخزن إقران منفصل ولا يتحكم في مصافحة WS.
لا يستخدم هذا التدفق إلا العملاء الذين يستدعون `node.pair.*` صراحة.

## المفاهيم

- **طلب معلّق**: طلبت عقدة الانضمام؛ ويتطلب ذلك موافقة.
- **عقدة مقترنة**: عقدة تمت الموافقة عليها مع رمز مصادقة صادر.
- **النقل**: تعيد نقطة نهاية Gateway WS توجيه الطلبات لكنها لا تقرر
  العضوية. (أُزيل دعم جسر TCP القديم.)

## كيفية عمل الإقران

1. تتصل عقدة بـ Gateway WS وتطلب الإقران.
2. يخزن Gateway **طلبًا معلّقًا** ويصدر الحدث `node.pair.requested`.
3. توافق على الطلب أو ترفضه (CLI أو واجهة المستخدم).
4. عند الموافقة، يصدر Gateway **رمزًا جديدًا** (تُدوّر الرموز عند إعادة الإقران).
5. تعيد العقدة الاتصال باستخدام الرمز وتصبح الآن "مقترنة".

تنتهي صلاحية الطلبات المعلّقة تلقائيًا بعد **5 دقائق**.

## سير عمل CLI (مناسب للأنظمة بلا واجهة)

```bash
openclaw nodes pending
openclaw nodes approve <requestId>
openclaw nodes reject <requestId>
openclaw nodes status
openclaw nodes remove --node <id|name|ip>
openclaw nodes rename --node <id|name|ip> --name "Living Room iPad"
```

يعرض `nodes status` العُقد المقترنة/المتصلة وإمكاناتها.

## سطح API (بروتوكول Gateway)

الأحداث:

- `node.pair.requested` - يصدر عند إنشاء طلب معلّق جديد.
- `node.pair.resolved` - يصدر عند الموافقة على طلب أو رفضه أو انتهاء صلاحيته.

الطرق:

- `node.pair.request` - إنشاء طلب معلّق أو إعادة استخدامه.
- `node.pair.list` - سرد العُقد المعلّقة + المقترنة (`operator.pairing`).
- `node.pair.approve` - الموافقة على طلب معلّق (يصدر رمزًا).
- `node.pair.reject` - رفض طلب معلّق.
- `node.pair.remove` - إزالة عقدة مقترنة. بالنسبة إلى الإقرانات المدعومة بأجهزة، يؤدي هذا
  إلى إبطال دور `node` للجهاز: فهو يعدّل `devices/paired.json` ويبطل/يفصل
  جلسات دور العقدة لذلك الجهاز. يحتفظ الجهاز **متعدد الأدوار**
  (مثلًا إذا كان يحمل أيضًا `operator`) بصفه ويفقد دور `node` فقط؛
  أما صف الجهاز ذي العقدة فقط فيُحذف. كما يزيل أي إدخال إقران عقدة قديم مطابق
  مملوك من Gateway. التفويض: يمكن لـ `operator.pairing` إزالة
  صفوف العُقد غير المشغّلة؛ ويحتاج مستدعي رمز الجهاز الذي يبطل دور العقدة **الخاص به** على
  جهاز متعدد الأدوار إلى `operator.admin` أيضًا.
- `node.pair.verify` - التحقق من `{ nodeId, token }`.

ملاحظات:

- `node.pair.request` متطابق النتيجة لكل عقدة: تعيد الاستدعاءات المتكررة الطلب
  المعلّق نفسه.
- تؤدي الطلبات المتكررة للعقدة المعلّقة نفسها أيضًا إلى تحديث بيانات تعريف العقدة المخزنة
  وأحدث لقطة أوامر مصرّح بها ضمن القائمة المسموحة لظهورها للمشغّل.
- تولد الموافقة **دائمًا** رمزًا جديدًا؛ ولا يُعاد أي رمز أبدًا من
  `node.pair.request`.
- تُلخّص مستويات نطاق المشغّل وفحوصات وقت الموافقة في
  [نطاقات المشغّل](/ar/gateway/operator-scopes).
- قد تتضمن الطلبات `silent: true` كتلميح لتدفقات الموافقة التلقائية.
- يستخدم `node.pair.approve` الأوامر المصرّح بها في الطلب المعلّق لفرض
  نطاقات موافقة إضافية:
  - طلب بلا أوامر: `operator.pairing`
  - طلب أمر غير تنفيذي: `operator.pairing` + `operator.write`
  - طلب `system.run` / `system.run.prepare` / `system.which`:
    `operator.pairing` + `operator.admin`

<Warning>
إقران العُقد هو تدفق ثقة وهوية بالإضافة إلى إصدار الرموز. وهو لا يثبّت سطح أوامر العقدة الحية لكل عقدة.

- تأتي أوامر العقدة الحية مما تصرّح به العقدة عند الاتصال بعد تطبيق سياسة أوامر العقد العامة في Gateway (`gateway.nodes.allowCommands` و`denyCommands`).
- تعيش سياسة السماح والسؤال الخاصة بـ `system.run` لكل عقدة على العقدة في `exec.approvals.node.*`، لا في سجل الإقران.

</Warning>

## حجب أوامر العُقد (2026.3.31+)

<Warning>
**تغيير كاسر:** بدءًا من `2026.3.31`، تُعطّل أوامر العُقد حتى تتم الموافقة على إقران العقدة. لم يعد إقران الجهاز وحده كافيًا لكشف أوامر العقدة المصرّح بها.
</Warning>

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

هذا يعني:

- يجب على العُقد التي كانت تعتمد سابقًا على إقران الجهاز وحده لكشف الأوامر إكمال إقران العقدة الآن.
- تُسقط الأوامر الموضوعة في قائمة الانتظار قبل الموافقة على الإقران، ولا تؤجَّل.

## حدود الثقة لأحداث العُقد (2026.3.31+)

<Warning>
**تغيير كاسر:** تبقى عمليات التشغيل الصادرة من العُقد الآن على سطح موثوق مخفّض.
</Warning>

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

تتبع تحديثات حضور العقدة الدائمة حدود الهوية نفسها. لا يُقبل الحدث `node.presence.alive` إلا من جلسات أجهزة عقد مصادق عليها، ولا يحدّث بيانات تعريف الإقران إلا عندما تكون هوية الجهاز/العقدة مقترنة بالفعل. لا تكفي قيم `client.id` المعلنة ذاتيًا لكتابة
حالة آخر ظهور.

## الموافقة التلقائية (تطبيق macOS)

يمكن لتطبيق macOS اختياريًا محاولة **موافقة صامتة** عندما:

- يكون الطلب معلّمًا بـ `silent`، و
- يستطيع التطبيق التحقق من اتصال SSH بمضيف Gateway باستخدام المستخدم نفسه.

إذا فشلت الموافقة الصامتة، يعود إلى مطالبة "موافقة/رفض" العادية.

## الموافقة التلقائية على أجهزة CIDR الموثوقة

يبقى إقران أجهزة WS لـ `role: node` يدويًا افتراضيًا. بالنسبة إلى شبكات
العُقد الخاصة التي يثق فيها Gateway بالفعل بمسار الشبكة، يمكن للمشغّلين
الاشتراك باستخدام CIDR صريحة أو عناوين IP دقيقة:

```json5
{
  gateway: {
    nodes: {
      pairing: {
        autoApproveCidrs: ["192.168.1.0/24"],
      },
    },
  },
}
```

حدود الأمان:

- تكون معطلة عندما لا يكون `gateway.nodes.pairing.autoApproveCidrs` معيّنًا.
- لا يوجد وضع موافقة تلقائية شامل لشبكة LAN أو الشبكات الخاصة.
- لا يكون مؤهلًا إلا إقران جهاز `role: node` جديد بلا نطاقات مطلوبة.
- يظل عملاء المشغّل والمتصفح وControl UI وWebChat يدويين.
- تظل ترقيات الدور والنطاق وبيانات التعريف والمفتاح العام يدوية.
- مسارات ترويسات الوكيل الموثوق عبر loopback على المضيف نفسه غير مؤهلة لأن ذلك
  المسار يمكن انتحاله من مستدعين محليين.

## الموافقة التلقائية على ترقية بيانات التعريف

عندما يعيد جهاز مقترن بالفعل الاتصال مع تغييرات غير حساسة فقط في بيانات التعريف
(على سبيل المثال، اسم العرض أو تلميحات منصة العميل)، يتعامل OpenClaw
مع ذلك كـ `metadata-upgrade`. الموافقة التلقائية الصامتة ضيقة النطاق: فهي تنطبق فقط
على عمليات إعادة الاتصال المحلية الموثوقة غير القادمة من المتصفح التي أثبتت بالفعل حيازة بيانات اعتماد محلية
أو مشتركة، بما في ذلك عمليات إعادة اتصال التطبيق الأصلي على المضيف نفسه بعد تغييرات بيانات تعريف إصدار نظام التشغيل. لا يزال عملاء المتصفح/Control UI والعملاء البعيدون
يستخدمون تدفق إعادة الموافقة الصريح. ترقيات النطاق (من قراءة إلى كتابة/إدارة) وتغييرات
المفتاح العام **ليست** مؤهلة للموافقة التلقائية على ترقية بيانات التعريف -
وتبقى كطلبات إعادة موافقة صريحة.

## مساعدات إقران QR

يعرض `/pair qr` حمولة الإقران كوسائط مهيكلة حتى يتمكن عملاء الأجهزة المحمولة
والمتصفح من مسحها مباشرة.

يؤدي حذف جهاز أيضًا إلى تنظيف أي طلبات إقران معلّقة قديمة لذلك
معرّف الجهاز، بحيث لا يعرض `nodes pending` صفوفًا يتيمة بعد الإبطال.

## المحلية والترويسات المعاد توجيهها

يتعامل إقران Gateway مع الاتصال على أنه loopback فقط عندما يتفق كل من المقبس الخام
وأي دليل وكيل علوي. إذا وصل طلب على loopback لكنه
يحمل أدلة ترويسات `Forwarded` أو أي `X-Forwarded-*` أو `X-Real-IP`، فإن
دليل الترويسة المعاد توجيهها يستبعد ادعاء محلية loopback. عندها يتطلب مسار
الإقران موافقة صريحة بدلًا من التعامل الصامت مع الطلب كاتصال من المضيف نفسه. راجع [مصادقة الوكيل الموثوق](/ar/gateway/trusted-proxy-auth) للاطلاع على
القاعدة المكافئة في مصادقة المشغّل.

## التخزين (محلي، خاص)

تُخزّن حالة الإقران ضمن دليل حالة Gateway (الافتراضي `~/.openclaw`):

- `~/.openclaw/nodes/paired.json`
- `~/.openclaw/nodes/pending.json`

إذا تجاوزت `OPENCLAW_STATE_DIR`، ينتقل مجلد `nodes/` معه.

ملاحظات أمان:

- الرموز أسرار؛ تعامل مع `paired.json` كملف حساس.
- يتطلب تدوير الرمز إعادة موافقة (أو حذف إدخال العقدة).

## سلوك النقل

- النقل **عديم الحالة**؛ فهو لا يخزن العضوية.
- إذا كان Gateway غير متصل أو كان الإقران معطلًا، فلا يمكن للعُقد الاقتران.
- إذا كان Gateway في الوضع البعيد، فسيظل الإقران يحدث مقابل مخزن Gateway البعيد.

## ذو صلة

- [إقران القنوات](/ar/channels/pairing)
- [العُقد](/ar/nodes)
- [CLI الأجهزة](/ar/cli/devices)