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

لدى OpenClaw مشكلتان مترابطتان لكنهما متمايزتان في الاكتشاف:

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

توجد جميع وظائف اكتشاف الشبكة والإعلان ضمن Node Gateway (openclaw gateway)؛ أما العملاء (تطبيق Mac وiOS) فهم مستهلكون فقط.

المصطلحات

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

تفاصيل البروتوكول: بروتوكول Gateway، بروتوكول الجسر (قديم).

سبب وجود النقل المباشر وSSH معًا

• WS المباشر يوفر أفضل تجربة مستخدم على الشبكة نفسها وضمن شبكة Tailscale: اكتشاف تلقائي عبر Bonjour على الشبكة المحلية، ورموز إقران وقوائم تحكم بالوصول تملكها Gateway، ومن دون الحاجة إلى وصول عبر الصدفة.
• SSH هو الخيار الاحتياطي العام: يعمل في أي مكان يتوفر فيه وصول SSH، حتى عبر شبكات غير مترابطة، ويتجاوز مشكلات البث المتعدد/mDNS، ولا يحتاج إلى أي منفذ وارد جديد بخلاف SSH.

مدخلات الاكتشاف

1) Bonjour / DNS-SD

يعمل Bonjour متعدد البث بأفضل جهد ولا يعبر بين الشبكات. يدعم OpenClaw أيضًا استعراض إشارة Gateway نفسها عبر نطاق DNS-SD واسع النطاق مُهيأ، بحيث يشمل الاكتشاف كلًا من local. على الشبكة المحلية نفسها ونطاق DNS-SD أحادي البث مُهيأ للاكتشاف عبر الشبكات.

تعلن Gateway عن نقطة نهاية WS الخاصة بها عبر Bonjour عند تمكين Plugin المضمّن bonjour؛ ويستعرض العملاء قائمة «اختر Gateway» ويعرضونها، ثم يخزّنون نقطة النهاية المختارة.

استكشاف الأخطاء وإصلاحها وتفاصيل الإشارة: Bonjour.

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

• نوع الخدمة: _openclaw-gw._tcp (إشارة نقل Gateway).

• مفاتيح TXT (غير سرية):

  المفتاح	الملاحظات
  role=gateway	موجود دائمًا.
  transport=gateway	موجود دائمًا.
  displayName=<name>	اسم العرض الذي يهيئه المشغّل.
  lanHost=<hostname>.local	لمُعلن mDNS على الشبكة المحلية فقط؛ لا يكتبه DNS-SD واسع النطاق.
  gatewayPort=18789	منفذ Gateway WS وHTTP.
  gatewayTls=1	فقط عند تمكين TLS.
  gatewayTlsSha256=<sha256>	فقط عند تمكين TLS وتوفر بصمة.
  tailnetDns=<magicdns>	تلميح اختياري؛ يُكتشف تلقائيًا عند توفر Tailscale.
  sshPort=<port>	لا يظهر إلا عندما تكون discovery.mdns.mode="full"؛ ويُحذف (القيمة الافتراضية لـSSH هي 22) في الوضع الافتراضي "minimal"، سواء في مُعلن الشبكة المحلية أو DNS-SD واسع النطاق.
  cliPath=<path>	يخضع لشرط discovery.mdns.mode="full" نفسه مثل sshPort؛ وهو تلميح للتثبيت البعيد لمسار CLI.

  يُعرَّف مفتاح TXT باسم canvasPort في عقد اكتشاف Plugin لمنفذ مضيف لوحة مستقبلي، لكن لا يعيّن أي مسار برمجي حالي قيمة له، ولذلك لا يُرسل حاليًا مطلقًا.

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

• سجلات TXT في Bonjour/mDNS غير موثّقة. يجب على العملاء التعامل مع قيم TXT على أنها تلميحات لتجربة المستخدم فقط.
• يجب أن يفضّل التوجيه (المضيف/المنفذ) نقطة نهاية الخدمة المحلولة (SRV وA/AAAA) على lanHost أو tailnetDns أو gatewayPort الواردة عبر TXT.
• يجب ألا يسمح تثبيت TLS أبدًا لبصمة gatewayTlsSha256 مُعلَن عنها بتجاوز بصمة مخزنة مسبقًا.
• يجب أن تتطلب عُقد iOS/Android تأكيدًا صريحًا لـ«الوثوق بهذه البصمة» قبل تخزين بصمة للمرة الأولى (تحقق خارج النطاق) كلما كان المسار المختار آمنًا/قائمًا على TLS.

التمكين والتعطيل والتجاوز:

• يمكّن openclaw plugins enable bonjour الإعلان متعدد البث على الشبكة المحلية.
• يتحكم discovery.mdns.mode في openclaw.json في بث mDNS: "minimal" (افتراضي)، أو "full" (يضيف cliPath/sshPort إلى كل من إشارة الشبكة المحلية وأي نطاق DNS-SD واسع النطاق)، أو "off" (يعطّل mDNS).
• يفرض OPENCLAW_DISABLE_BONJOUR=1 تعطيل الإعلان؛ كما تعطّله discovery.mdns.mode="off" بصورة مستقلة. تمثل OPENCLAW_DISABLE_BONJOUR=0 اشتراكًا صريحًا يتجاوز التعطيل التلقائي للـPlugin داخل حاوية مكتشفة (Docker أو containerd أو Kubernetes أو LXC)؛ ولا يتجاوز discovery.mdns.mode="off". يبدأ Plugin المضمّن bonjour تلقائيًا على مضيفي macOS (enabledByDefaultOnPlatforms: ["darwin"]) ويُعطّل تلقائيًا داخل الحاويات المكتشفة؛ أما عمليات النشر على Linux وWindows وغيرها من البيئات المحوّاة فتحتاج إلى تنفيذ plugins enable bonjour صراحةً.
• يتحكم gateway.bind في ~/.openclaw/openclaw.json في وضع ربط Gateway.
• يتجاوز OPENCLAW_SSH_PORT منفذ SSH المُعلَن عنه (ولا يسري إلا عندما تكون discovery.mdns.mode="full").
• ينشر OPENCLAW_TAILNET_DNS تلميح tailnetDns ‏(MagicDNS).
• يتجاوز OPENCLAW_CLI_PATH مسار CLI المُعلَن عنه.

2) شبكة Tailscale (عبر الشبكات)

لن يفيد Bonjour مع بوابات موجودة على شبكات مادية مختلفة. الهدف المباشر الموصى به هو اسم Tailscale MagicDNS (المفضّل) أو عنوان IP ثابت ضمن شبكة Tailscale.

إذا اكتشفت Gateway أنها تعمل ضمن Tailscale، فإنها تنشر tailnetDns كتلميح اختياري للعملاء (بما في ذلك الإشارات واسعة النطاق). يفضّل تطبيق macOS أسماء MagicDNS على عناوين IP الخام لـTailscale عند اكتشاف Gateway، ويظل ذلك موثوقًا عند تغير عناوين IP لشبكة Tailscale (إعادة تشغيل العُقد أو إعادة تعيين CGNAT)، لأن MagicDNS يحلّ الاسم تلقائيًا إلى عنوان IP الحالي.

بالنسبة إلى إقران عُقد الأجهزة المحمولة، لا تخفف تلميحات الاكتشاف أمان النقل أبدًا على مسارات شبكة Tailscale/المسارات العامة:

• لا تزال iOS/Android تتطلب مسار اتصال أولي آمنًا عبر شبكة Tailscale/المسار العام (wss:// أو Tailscale Serve/Funnel).
• عنوان IP خام مكتشف ضمن شبكة Tailscale هو تلميح توجيه، وليس إذنًا باستخدام ws:// بعيد بنص صريح.
• يظل الاتصال المباشر عبر ws:// على الشبكة المحلية الخاصة مدعومًا.
• لأبسط مسار Tailscale على عُقد الأجهزة المحمولة، استخدم Tailscale Serve كي يُحل كل من الاكتشاف والإعداد إلى نقطة نهاية MagicDNS الآمنة نفسها.

3) هدف يدوي / SSH

عندما لا يتوفر مسار مباشر (أو يكون المباشر معطّلًا)، يمكن للعملاء دائمًا الاتصال عبر SSH من خلال إعادة توجيه منفذ Gateway على local loopback. راجع الوصول عن بُعد.

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

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

الإقران والمصادقة (النقل المباشر)

Gateway هي مصدر الحقيقة لقبول العُقد/العملاء:

• تُنشأ طلبات الإقران وتُعتمد أو تُرفض في Gateway (راجع إقران Gateway).
• تفرض Gateway المصادقة (الرمز/زوج المفاتيح)، والنطاقات/قوائم التحكم بالوصول (فهي ليست وكيلًا خامًا لكل طريقة)، وحدود المعدّل.

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

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

ذو صلة

• الوصول عن بُعد
• Tailscale
• اكتشاف Bonjour