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

في الإقران المملوك من 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 (مناسب للأنظمة بلا واجهة)

openclaw nodes pendingopenclaw nodes approve <requestId>openclaw nodes reject <requestId>openclaw nodes statusopenclaw 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.
• تُلخّص مستويات نطاق المشغّل وفحوصات وقت الموافقة في نطاقات المشغّل.
• قد تتضمن الطلبات silent: true كتلميح لتدفقات الموافقة التلقائية.
• يستخدم node.pair.approve الأوامر المصرّح بها في الطلب المعلّق لفرض نطاقات موافقة إضافية:
  • طلب بلا أوامر: operator.pairing
  • طلب أمر غير تنفيذي: operator.pairing + operator.write
  • طلب system.run / system.run.prepare / system.which: operator.pairing + operator.admin

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

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

هذا يعني:

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

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

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

تتبع تحديثات حضور العقدة الدائمة حدود الهوية نفسها. لا يُقبل الحدث node.presence.alive إلا من جلسات أجهزة عقد مصادق عليها، ولا يحدّث بيانات تعريف الإقران إلا عندما تكون هوية الجهاز/العقدة مقترنة بالفعل. لا تكفي قيم 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 يدويين.
• تظل ترقيات الدور والنطاق وبيانات التعريف والمفتاح العام يدوية.
• مسارات ترويسات الوكيل الموثوق عبر loopback على المضيف نفسه غير مؤهلة لأن ذلك المسار يمكن انتحاله من مستدعين محليين.

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

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

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

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

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

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

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

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

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

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

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

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

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

سلوك النقل

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

ذو صلة

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