الانتقال إلى المحتوى الرئيسي

​
الاقتران المملوك للبوابة (الخيار 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)

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+)

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

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

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

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

يمكن لتطبيق macOS اختياريًا محاولة موافقة صامتة عندما:
  • تكون العلامة silent مضبوطة على الطلب، و
  • يستطيع التطبيق التحقق من اتصال SSH إلى مضيف البوابة باستخدام المستخدم نفسه.
إذا فشلت الموافقة الصامتة، فإنه يعود إلى مطالبة “موافقة/رفض” العادية.

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

تُخزَّن حالة الاقتران ضمن دليل حالة البوابة (الافتراضي ~/.openclaw):
  • ~/.openclaw/nodes/paired.json
  • ~/.openclaw/nodes/pending.json
إذا قمت بتجاوز OPENCLAW_STATE_DIR، ينتقل مجلد nodes/ معه. ملاحظات أمنية:
  • الرموز أسرار؛ تعامل مع paired.json على أنه حساس.
  • يتطلب تدوير الرمز إعادة الموافقة (أو حذف إدخال العقدة).

​
سلوك النقل

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