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

​
الاكتشاف ووسائط النقل

لدى OpenClaw مشكلتان متميزتان تبدوان متشابهتين ظاهريًا:
  1. التحكم البعيد للمشغّل: تطبيق شريط القوائم على macOS الذي يتحكم في بوابة تعمل في مكان آخر.
  2. اقتران العقدة: عثور iOS/Android (والعقد المستقبلية) على بوابة والاقتران بها بأمان.
الهدف من التصميم هو إبقاء كل اكتشاف/إعلان الشبكة داخل Node Gateway (openclaw gateway) والإبقاء على العملاء (تطبيق Mac وiOS) كمستهلكين.

​
المصطلحات

  • Gateway: عملية بوابة واحدة طويلة التشغيل تملك الحالة (الجلسات، والاقتران، وسجل العقد) وتشغّل القنوات. تستخدم معظم الإعدادات واحدة لكل مضيف؛ كما أن إعدادات متعددة البوابات المعزولة ممكنة.
  • Gateway WS (طبقة التحكم): نقطة نهاية WebSocket على 127.0.0.1:18789 افتراضيًا؛ ويمكن ربطها بـ LAN/tailnet عبر gateway.bind.
  • نقل WS مباشر: نقطة نهاية Gateway WS مواجهة لـ LAN/tailnet (من دون SSH).
  • نقل SSH (احتياطي): تحكم عن بُعد عبر تمرير 127.0.0.1:18789 عبر SSH.
  • جسر TCP القديم (تمت إزالته): نقل عقدة أقدم (راجع Bridge protocol)؛ لم يعد يُعلن عنه من أجل الاكتشاف ولم يعد جزءًا من الإصدارات الحالية.
تفاصيل البروتوكول:

​
لماذا نحتفظ بكل من “المباشر” وSSH

  • WS المباشر هو أفضل تجربة استخدام على الشبكة نفسها وداخل tailnet:
    • اكتشاف تلقائي على LAN عبر Bonjour
    • تمتلك البوابة رموز الاقتران + ACLs
    • لا حاجة إلى وصول shell؛ ويمكن أن يبقى سطح البروتوكول ضيقًا وقابلًا للتدقيق
  • يظل SSH الاحتياطي العالمي:
    • يعمل في أي مكان لديك فيه وصول SSH (حتى عبر شبكات غير مترابطة)
    • يصمد أمام مشكلات multicast/mDNS
    • لا يتطلب أي منافذ واردة جديدة بخلاف SSH

​
مدخلات الاكتشاف (كيف يعرف العملاء مكان البوابة)

​
1) الاكتشاف عبر Bonjour / DNS-SD

يكون Multicast Bonjour مجهودًا بأفضل ما يمكن ولا يعبر الشبكات. ويمكن لـ OpenClaw أيضًا تصفح إشارة البوابة نفسها عبر نطاق DNS-SD واسع النطاق مهيأ، بحيث يمكن أن يغطي الاكتشاف:
  • local. على LAN نفسها
  • نطاق DNS-SD أحادي الإرسال مهيأ للاكتشاف عبر الشبكات
اتجاه الهدف:
  • تقوم البوابة بالإعلان عن نقطة نهاية WS الخاصة بها عبر Bonjour.
  • يتصفح العملاء ويعرضون قائمة “اختر بوابة”، ثم يخزنون نقطة النهاية المختارة.
استكشاف الأخطاء وتفاصيل الإشارة: Bonjour.

​
تفاصيل إشارة الخدمة

  • أنواع الخدمة:
    • _openclaw-gw._tcp (إشارة نقل البوابة)
  • مفاتيح TXT (غير سرية):
    • role=gateway
    • transport=gateway
    • displayName=<friendly name> (اسم عرض سهل التعرّف يُعده المشغّل)
    • lanHost=<hostname>.local
    • gatewayPort=18789 (‏Gateway WS + HTTP)
    • gatewayTls=1 (فقط عند تمكين TLS)
    • gatewayTlsSha256=<sha256> (فقط عند تمكين TLS وتوفر البصمة)
    • canvasPort=<port> (منفذ مضيف canvas؛ وهو حاليًا نفس gatewayPort عند تمكين مضيف canvas)
    • tailnetDns=<magicdns> (تلميح اختياري؛ يُكتشف تلقائيًا عند توفر Tailscale)
    • sshPort=<port> (في وضع mDNS الكامل فقط؛ قد يحذفه DNS-SD واسع النطاق، وفي هذه الحالة تبقى إعدادات SSH الافتراضية عند 22)
    • cliPath=<path> (في وضع mDNS الكامل فقط؛ ولا يزال DNS-SD واسع النطاق يكتبه كتلميح للتثبيت عن بُعد)
ملاحظات الأمان:
  • سجلات Bonjour/mDNS TXT غير موثقة. ويجب على العملاء التعامل مع قيم TXT كتلميحات لتجربة الاستخدام فقط.
  • يجب أن يفضّل التوجيه (المضيف/المنفذ) نقطة نهاية الخدمة المحلولة (‏SRV + A/AAAA) على lanHost أو tailnetDns أو gatewayPort المقدمة عبر TXT.
  • يجب ألا يسمح ربط TLS أبدًا لـ gatewayTlsSha256 المعلن عنه بأن يتجاوز ربطًا مخزنًا سابقًا.
  • يجب على عقد iOS/Android أن تتطلب تأكيدًا صريحًا من نوع “الثقة بهذه البصمة” قبل تخزين ربط لأول مرة (تحقق خارج النطاق) كلما كان المسار المختار آمنًا/قائمًا على TLS.
التعطيل/التجاوز:
  • يؤدي OPENCLAW_DISABLE_BONJOUR=1 إلى تعطيل الإعلان.
  • يتحكم gateway.bind في ~/.openclaw/openclaw.json في وضع ربط Gateway.
  • يتجاوز OPENCLAW_SSH_PORT منفذ SSH المُعلن عنه عند إصدار sshPort.
  • ينشر OPENCLAW_TAILNET_DNS تلميح tailnetDns (‏MagicDNS).
  • يتجاوز OPENCLAW_CLI_PATH مسار CLI المُعلن عنه.

​
2) Tailnet (عبر الشبكات)

بالنسبة إلى إعدادات على نمط London/Vienna، لن يفيد Bonjour. الهدف “المباشر” الموصى به هو:
  • اسم Tailscale MagicDNS (مفضل) أو عنوان IP ثابت من tailnet.
إذا استطاعت البوابة اكتشاف أنها تعمل تحت Tailscale، فإنها تنشر tailnetDns كتلميح اختياري للعملاء (بما في ذلك الإشارات واسعة النطاق). يفضّل تطبيق macOS الآن أسماء MagicDNS على عناوين Tailscale IP الخام لاكتشاف البوابة. ويحسن ذلك الاعتمادية عندما تتغير عناوين tailnet IP (على سبيل المثال بعد إعادة تشغيل العقد أو إعادة تعيين CGNAT)، لأن أسماء MagicDNS تُحل إلى عنوان IP الحالي تلقائيًا. بالنسبة إلى اقتران العقد المحمولة، لا تُخفف تلميحات الاكتشاف أمان النقل على مسارات tailnet/المسارات العامة:
  • لا تزال iOS/Android تتطلب مسار اتصال أولي آمن عبر tailnet/المسار العام (wss:// أو Tailscale Serve/Funnel).
  • يمثل عنوان IP خام من tailnet تم اكتشافه تلميح توجيه، وليس إذنًا باستخدام ws:// بعيد بنص واضح.
  • لا يزال الاتصال المباشر الخاص عبر LAN باستخدام ws:// مدعومًا.
  • إذا كنت تريد أبسط مسار Tailscale للعقد المحمولة، فاستخدم Tailscale Serve بحيث يحل كل من الاكتشاف وشيفرة الإعداد إلى نقطة نهاية MagicDNS الآمنة نفسها.

​
3) الهدف اليدوي / SSH

عندما لا يوجد مسار مباشر (أو عندما يكون المباشر معطلًا)، يمكن للعملاء دائمًا الاتصال عبر SSH بتمرير منفذ البوابة local loopback. راجع Remote access.

​
اختيار النقل (سياسة العميل)

سلوك العميل الموصى به:
  1. إذا كانت نقطة نهاية مباشرة مقترنة مهيأة ويمكن الوصول إليها، فاستخدمها.
  2. وإلا، إذا عثر الاكتشاف على بوابة على local. أو على النطاق واسع النطاق المهيأ، فاعرض خيارًا بضغطة واحدة “استخدم هذه البوابة” واحفظه كنقطة النهاية المباشرة.
  3. وإلا، إذا كان DNS/IP خاص بـ tailnet مهيأً، فجرّب الاتصال المباشر. وبالنسبة إلى العقد المحمولة على مسارات tailnet/المسارات العامة، فإن الاتصال المباشر يعني نقطة نهاية آمنة، وليس ws:// بعيدًا بنص واضح.
  4. وإلا، فارجع إلى SSH.

​
الاقتران + المصادقة (النقل المباشر)

البوابة هي مصدر الحقيقة لقبول العقدة/العميل.
  • يتم إنشاء طلبات الاقتران/الموافقة عليها/رفضها في البوابة (راجع Gateway pairing).
  • تفرض البوابة:
    • المصادقة (token / keypair)
    • النطاقات/ACLs (البوابة ليست وكيلًا خامًا لكل طريقة)
    • حدود المعدل

​
المسؤوليات بحسب المكوّن

  • Gateway: تعلن إشارات الاكتشاف، وتملك قرارات الاقتران، وتستضيف نقطة نهاية WS.
  • تطبيق macOS: يساعدك في اختيار بوابة، ويعرض مطالبات الاقتران، ويستخدم SSH فقط كخيار احتياطي.
  • عقد iOS/Android: تتصفح Bonjour كوسيلة مريحة وتتصل بـ Gateway WS المقترنة.