إقران Node

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

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

أُزيل مخزن اقتران 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: operator.pairing + operator.admin

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

عندما يتصل Node للمرة الأولى، يُطلب الاقتران تلقائيًا. وحتى تتم الموافقة على ذلك الطلب، تُرشَّح جميع أوامر 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) الاتصال بمضيف Node عبر SSH دون تفاعل (بالمفاتيح/الوكيل؛ ويعمل Tailscale SSH أيضًا)، ويكون مفتاح المضيف موثوقًا بالفعل.
• يمكن العثور على openclaw ضمن PATH البعيد عند تشغيل sh -lc دون تفاعل.
• يكون عنوان IP المتصل عنوانًا مباشرًا (غير مار عبر وكيل، وليس عنوان loopback) خاصًا أو ULA أو link-local أو CGNAT، أو يطابق sshVerify.cidrs عند تعيينه.
• ينطبق حد الأهلية الأدنى نفسه للموافقة عبر CIDR موثوق: اقتران Node جديد بلا نطاقات فقط؛ أما الترقيات والمتصفحات وواجهة التحكم وWebChat فتطلب الموافقة دائمًا.

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

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

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

{  gateway: {    nodes: {      pairing: {        // Disable entirely:        sshVerify: false,        // ...or scope/tune the probe:        // 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 من دون نطاقات مطلوبة.
• يظل عملاء المشغل والمتصفح وواجهة التحكم وWebChat خاضعين للموافقة اليدوية.
• تظل ترقيات الدور والنطاق والبيانات الوصفية والمفتاح العام خاضعة للموافقة اليدوية.
• لا تكون مسارات ترويسات الوكيل الموثوق عبر local loopback على المضيف نفسه مؤهلة، لأن المستدعين المحليين يستطيعون انتحال هذا المسار.

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

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

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

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

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

النطاق المحلي والرؤوس المُمرَّرة

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

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

توجد حالة الاقتران في سجلات الأجهزة المقترنة ضمن قاعدة بيانات حالة 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 للأجهزة