الإقران المملوك لـ Gateway

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

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

# المفاهيم

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

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

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

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

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

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.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

# تقييد أوامر Node (2026.3.31+)

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

يعني هذا:

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

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

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

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

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

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

• يكون الطلب موسومًا بـ silent، و
• يستطيع التطبيق التحقق من اتصال SSH إلى مضيف gateway باستخدام المستخدم نفسه.

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

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

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

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

حدود الأمان:

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

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

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

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

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

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

# المحلية والترويسات المُمرَّرة

يعامل اقتران Gateway الاتصال كاسترجاع فقط عندما يتفق كل من المقبس الخام وأي دليل وكيل علوي. إذا وصل طلب على الاسترجاع لكنه يحمل ترويسات X-Forwarded-For / X-Forwarded-Host / X-Forwarded-Proto تشير إلى أصل غير محلي، فإن دليل الترويسة المُمرَّرة هذا يستبعد ادعاء محلية الاسترجاع. يتطلب مسار الاقتران عندها موافقة صريحة بدلًا من معاملة الطلب بصمت كاتصال من المضيف نفسه. راجع مصادقة الوكيل الموثوق للقاعدة المكافئة في مصادقة المشغل.

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

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

• ~/.openclaw/nodes/paired.json
• ~/.openclaw/nodes/pending.json

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

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

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

# سلوك النقل

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

# ذو صلة

• اقتران القناة
• العُقد
• CLI للأجهزة