---
read_when:
    - تنفيذ موافقات اقتران العقد من دون واجهة macOS
    - إضافة تدفقات CLI للموافقة على العقد البعيدة
    - توسيع بروتوكول البوابة بإدارة العقد
summary: اقتران مملوك للبوابة (الخيار B) لأجهزة iOS والعقد البعيدة الأخرى
title: الاقتران المملوك للبوابة
x-i18n:
    generated_at: "2026-04-05T12:43:48Z"
    model: gpt-5.4
    provider: openai
    source_hash: 8f90818c84daeb190f27df7413e23362372806f2c4250e4954295fbf6df70233
    source_path: gateway/pairing.md
    workflow: 15
---

# الاقتران المملوك للبوابة (الخيار B)

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

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

## المفاهيم

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

## كيف يعمل الاقتران

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

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

## سير عمل CLI (مناسب للبيئات headless)

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

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

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

الأحداث:

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

الأساليب:

- `node.pair.request` — إنشاء طلب معلّق أو إعادة استخدامه.
- `node.pair.list` — سرد العقد المعلقة + المقترنة (`operator.pairing`).
- `node.pair.approve` — الموافقة على طلب معلّق (يصدر رمزًا).
- `node.pair.reject` — رفض طلب معلّق.
- `node.pair.verify` — التحقق من `{ nodeId, token }`.

ملاحظات:

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

مهم:

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

## ضبط أوامر العقدة (2026.3.31+)

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

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

وهذا يعني:

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

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

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

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

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

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

- تكون العلامة `silent` مضبوطة على الطلب، و
- يستطيع التطبيق التحقق من اتصال SSH إلى مضيف البوابة باستخدام المستخدم نفسه.

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

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

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

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

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

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

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

## سلوك النقل

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