إقران Node

يتكون إقران Node من طبقتين، وكلتاهما مخزنتان في سجل الجهاز المقترن ضمن قاعدة بيانات حالة SQLite الخاصة بـ Gateway:

• إقران الجهاز (الدور node) يتحكم في مصافحة connect. راجع الموافقة التلقائية على الجهاز عبر CIDR الموثوق أدناه وإقران القناة.
• الموافقة على إمكانات Node (node.pair.*) تتحكم في الإمكانات/الأوامر المعلنة التي يجوز لـ Node متصل إتاحتها. Gateway هو مصدر الحقيقة؛ أما واجهات المستخدم (تطبيق macOS وواجهة Control UI) فهي واجهات أمامية توافق على الطلبات المعلقة أو ترفضها.

لم يعد مخزن إقران Node المستقل السابق (nodes/paired.json مع رمز مميز لكل Node، وقد أُخرج من مسار الاتصال في يناير 2026) موجودًا: تدمج مثيلات Gateway أي صفوف متبقية في سجلات الأجهزة مرة واحدة عند بدء التشغيل، وتؤرشف الملفات القديمة بلاحقة .migrated. وقد أزيل دعم جسر TCP القديم.

كيفية عمل الموافقة على الإمكانات

1. يتصل Node بـ Gateway WS (ويتحكم إقران الجهاز في هذه الخطوة).
2. يقارن Gateway سطح الإمكانات/الأوامر المعلن بالسطح الموافق عليه؛ وتؤدي الأسطح الجديدة أو الموسعة إلى تخزين طلب معلق في سجل الجهاز وإصدار node.pair.requested.
3. توافق على الطلب أو ترفضه (عبر CLI أو واجهة المستخدم).
4. حتى تتم الموافقة، تظل أوامر Node مصفاة؛ وتتيح الموافقة السطح المعلن وفقًا لسياسة الأوامر المعتادة.

تنتهي صلاحية الطلبات المعلقة تلقائيًا بعد 5 دقائق من آخر إعادة محاولة أجراها Node — يحافظ Node الذي يعيد الاتصال بنشاط على طلبه المعلق الوحيد بدلًا من إنشاء طلب جديد (ومطالبة موافقة) لكل محاولة.

سير عمل 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 مثيلات Node المقترنة/المتصلة وإمكاناتها.

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

الأحداث:

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

الأساليب:

• node.pair.list - يسرد مثيلات Node المعلقة والمقترنة (operator.pairing).
• node.pair.approve - يوافق على طلب معلق.
• node.pair.reject - يرفض طلبًا معلقًا.
• node.pair.remove - يزيل Node مقترنًا. يؤدي ذلك إلى إبطال دور node الخاص بالجهاز في مخزن الأجهزة المقترنة، وإزالة سطح Node الموافق عليه معه، وإبطال/فصل جلسات دور Node لذلك الجهاز. يحتفظ الجهاز متعدد الأدوار (مثل جهاز يحمل أيضًا operator) بصفه ولا يفقد سوى دور node؛ بينما يُحذف صف الجهاز المخصص لـ Node فقط. التفويض: يجوز لـ operator.pairing إزالة صفوف Node لغير المشغلين؛ أما المستدعي الذي يستخدم رمز الجهاز لإبطال دور Node الخاص به على جهاز متعدد الأدوار فيحتاج أيضًا إلى operator.admin.
• node.rename - يعيد تسمية اسم العرض الموجه للمشغل الخاص بـ Node مقترن.

أُزيل في 2026.7: node.pair.request وnode.pair.verify. ينشئ Gateway الطلبات المعلقة بنفسه أثناء اتصالات Node، ولم يعد الرمز المميز المستقل لكل Node الذي كانت تخدمه هذه الأساليب موجودًا؛ ومصادقة Node هي رمز إقران الجهاز.

ملاحظات:

• تعيد الاتصالات ذات السطح غير المتغير استخدام الطلب المعلق؛ وتحدّث الطلبات المتكررة بيانات Node الوصفية المخزنة وأحدث لقطة للأوامر المعلنة المدرجة في قائمة السماح ليراها المشغل.
• تُلخص مستويات نطاق المشغل وفحوصات وقت الموافقة في نطاقات المشغل.
• يستخدم node.pair.approve الأوامر المعلنة في الطلب المعلق لفرض نطاقات موافقة إضافية:
  • طلب بلا أوامر: operator.pairing
  • طلب أوامر عادي: operator.pairing + operator.write
  • طلب حساس إداريًا يحتوي على system.run أو system.run.prepare أو system.which أو browser.proxy أو fs.listDir أو system.execApprovals.get/set: operator.pairing + operator.admin

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

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

يعني ذلك:

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

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

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

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

الموافقة التلقائية على الجهاز المتحقق منها عبر SSH (افتراضيًا)

تتم الموافقة تلقائيًا على إقران جهاز role: node لأول مرة من عنوان خاص/CGNAT عندما يستطيع Gateway إثبات ملكية الجهاز عبر SSH: إذ يعيد الاتصال بمضيف الإقران (BatchMode، StrictHostKeyChecking=yes)، ويشغل openclaw node identity --json هناك، ولا يوافق إلا عندما يتطابق معرّف الجهاز البعيد ومفتاحه العام تمامًا مع الطلب المعلق. تطابق المفتاح هو ما يجعل ذلك آمنًا: فإمكانية الوصول وحدها لا تؤدي إلى الموافقة أبدًا، ولذلك يعود المشاركون في عنوان NAT والمستخدمون الآخرون على مضيف مشترك وانتحال LAN جميعًا إلى المطالبة المعتادة.

مفعّلة افتراضيًا. متطلبات تشغيلها:

• يمكن لمستخدم عملية Gateway (أو sshVerify.user) الاتصال عبر SSH بمضيف Node دون تفاعل (باستخدام المفاتيح/الوكيل؛ ويعمل Tailscale SSH أيضًا)، ويكون مفتاح المضيف موثوقًا بالفعل.
• يُحل openclaw على PATH البعيد لأجل sh -lc غير التفاعلي.
• يكون عنوان IP المتصل عنوانًا مباشرًا (غير وكيل وغير استرجاعي) خاصًا أو ULA أو محليًا للرابط أو CGNAT، أو يطابق sshVerify.cidrs عند تعيينه.
• تنطبق أهلية الحد الأدنى نفسها للموافقة عبر CIDR الموثوق: إقران Node جديد بلا نطاقات فقط؛ أما الترقيات والمتصفحات وControl UI وWebChat فتطلب الموافقة دائمًا.

أثناء تشغيل الفحص، يُطلب من عميل Node مواصلة إعادة المحاولة (wait_then_retry) بدلًا من التوقف انتظارًا للموافقة اليدوية؛ وإذا فشل الفحص، تعود المحاولة التالية إلى تدفق المطالبة المعتاد. وتحصل الأهداف التي فشلت على فترة تهدئة قصيرة (5 دقائق بعد عدم تطابق المفتاح).

تسجل الأجهزة الموافق عليها approvedVia: "ssh-verified"، ويُعتمد أول سطح إمكانات معلن لها في الخطوة نفسها — فتطابق المفتاح يثبت بالفعل أن Node يعمل ضمن حساب المشغل على جهاز يملكه، وهو الادعاء نفسه الذي تؤكده الموافقة اليدوية على الإمكانات. وتظل ترقيات السطح اللاحقة تتطلب الموافقة.

للتشديد أو التعطيل:

{  gateway: {    nodes: {      pairing: {        // التعطيل بالكامل:        sshVerify: false,        // ...أو تحديد نطاق الفحص/ضبطه:        // sshVerify: { user: "me", identity: "~/.ssh/probe", timeoutMs: 7000, cidrs: ["10.0.0.0/8"] },      },    },  },}

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

يمكن لتطبيق macOS محاولة إجراء موافقة صامتة على طلبات إمكانات Node عندما:

• يكون الطلب موسومًا بـ silent (يضع Gateway وسم الصمت على أول سطح إمكانات عندما تتم الموافقة على إقران الجهاز دون تفاعل)، و
• يستطيع التطبيق التحقق من اتصال SSH بمضيف Gateway باستخدام المستخدم نفسه.

إذا فشلت الموافقة الصامتة، فإنها تعود إلى مطالبة Approve/Reject المعتادة.

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

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

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

حدود الأمان:

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

تنظيف الاستبدال الناتج عن الإقران الصامت

تسجل الموافقات غير التفاعلية مصدرها في صف الجهاز المقترن: موافقات السياسة المحلية على المضيف نفسه كـ silent، وموافقات Node عبر CIDR الموثوق كـ trusted-cidr، وموافقات Node المتحقق منها عبر SSH كـ ssh-verified. ينشئ العملاء الذين يكون دليل حالتهم مؤقتًا (مجلدات رئيسية مؤقتة، وحاويات، وبيئات معزولة لكل تشغيل) زوج مفاتيح جهاز جديدًا في كل تشغيل، ويعيد كل تشغيل الإقران بصمت كجهاز جديد تمامًا — ومن دون التنظيف تنمو قائمة الأجهزة المقترنة بصف قديم واحد لكل تشغيل.

عندما يوافق Gateway بصمت على إقران جهاز محلي، فإنه يُخرج من الخدمة السجلات القديمة الموافق عليها عبر silent التي تنتمي إلى مجموعة العميل نفسها (بمطابقة clientId وclientMode واسم العرض) وغير المتصلة حاليًا. يعمل العملاء المحليون على مضيف Gateway نفسه، ولذلك لا يمكن لمفتاح المجموعة أن يطابق جهازًا مختلفًا. تفقد الصفوف المُخرجة من الخدمة رموزها فورًا؛ ويُمسح أي إدخال إقران Node قديم مطابق، ويُبث حدث إزالة node.pair.resolved.

الحدود:

• لا تكون مؤهلة، سواء كمُشغِّل أو كهدف، إلا السجلات التي كانت أحدث موافقة عليها محلية على المضيف نفسه (silent). تمتد عمليات الاقتران الموثَّقة عبر نطاق CIDR وعمليات الاقتران المتحقَّق منها عبر SSH بين المضيفين، حيث لا تمثّل بيانات العرض الوصفية هوية الجهاز، ولذلك لا تُزال تلقائيًا أبدًا — استخدم التنظيف في واجهة التحكم أو openclaw nodes remove لهذه الحالات.
• لا تُزال تلقائيًا أبدًا عمليات الاقتران التي وافق عليها المالك وعمليات الاقتران عبر رمز QR/رمز الإعداد (التمهيد). وتظل السجلات التي تمت الموافقة عليها قبل توفر معلومات المصدر محمية، حتى بعد إعادة موافقة صامتة لاحقة على معرّف الجهاز نفسه.
• يتم تخطي الأجهزة المتصلة حاليًا، بحيث تحتفظ الجلسات المحلية المتزامنة ذات أدلة الحالة المنفصلة برموزها المميزة ما دامت نشطة. كما يتم تخطي السجلات التي تمت الموافقة عليها خلال الدقيقة الأخيرة، بحيث لا تتمكن مصافحات الاقتران المتزامنة من إنهاء بعضها بعضًا قبل تسجيل اتصالاتها.
• العملاء المتأثرون محليون بحكم التصميم، ولذلك يعيدون الاقتران بصمت عند اتصالهم التالي.

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

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

أدوات مساعدة للاقتران عبر QR

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

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

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

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

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

توجد حالة الاقتران ضمن سجلات الأجهزة المقترنة في قاعدة بيانات حالة SQLite المشتركة داخل دليل حالة Gateway (الافتراضي ~/.openclaw):

• ~/.openclaw/state/openclaw.sqlite (الأجهزة المقترنة مع مصادقة الجهاز، وأسطح Node الموافق عليها، وطلبات الأسطح المعلّقة، وطلبات اقتران الأجهزة المعلّقة، ورموز التمهيد المميزة)

إذا تجاوزت OPENCLAW_STATE_DIR، فستنتقل قاعدة البيانات معه. تستورد بوابات Gateway التي تمت ترقيتها من إصدارات تستخدم مخازن JSON تلك المخازن عند بدء التشغيل وتترك أرشيفَي devices/*.json.migrated وnodes/*.json.migrated.

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

• رموز الأجهزة المميزة أسرار؛ تعامل مع قاعدة بيانات الحالة على أنها حساسة.
• يستخدم تدوير الرمز المميز لجهاز openclaw devices rotate / device.token.rotate.

سلوك النقل

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

ذو صلة

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