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

لدى OpenClaw مشكلتان متميزتان تبدوان متشابهتين ظاهريًا:

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

هدف التصميم هو إبقاء كل اكتشاف/إعلان الشبكة في Node Gateway (openclaw gateway) وإبقاء العملاء (تطبيق Mac وiOS) كمستهلكين.

# المصطلحات

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

تفاصيل البروتوكول:

• بروتوكول Gateway
• بروتوكول الجسر (قديم)

# لماذا نحتفظ بكل من الاتصال المباشر وSSH

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

# مدخلات الاكتشاف (كيف يعرف العملاء مكان Gateway)

# 1) اكتشاف Bonjour / DNS-SD

Bonjour متعدد البث يعمل بأفضل جهد ولا يعبر الشبكات. يمكن لـ OpenClaw أيضًا تصفح إشارة Gateway نفسها عبر نطاق DNS-SD واسع النطاق مُكوَّن، لذلك يمكن أن يغطي الاكتشاف:

• local. على الشبكة المحلية نفسها
• نطاق DNS-SD أحادي البث مُكوَّن للاكتشاف عبر الشبكات

الاتجاه المستهدف:

• يعلن Gateway عن نقطة نهاية WS الخاصة به عبر Bonjour عند تمكين Plugin bonjour المضمّن. يبدأ Plugin تلقائيًا على مضيفي macOS ويكون اختياريًا في غير ذلك.
• يتصفح العملاء ويعرضون قائمة "اختر Gateway"، ثم يخزنون نقطة النهاية المختارة.

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

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

• أنواع الخدمة:
  • _openclaw-gw._tcp (إشارة نقل Gateway)
• مفاتيح TXT (غير سرية):
  • role=gateway
  • transport=gateway
  • displayName=<friendly name> (اسم عرض مُكوَّن من المشغّل)
  • lanHost=<hostname>.local
  • gatewayPort=18789 (Gateway WS + HTTP)
  • gatewayTls=1 (فقط عند تمكين TLS)
  • gatewayTlsSha256=<sha256> (فقط عند تمكين TLS وتوفر البصمة)
  • canvasPort=<port> (منفذ مضيف اللوحة؛ حاليًا هو نفسه gatewayPort عند تمكين مضيف اللوحة)
  • tailnetDns=<magicdns> (تلميح اختياري؛ يُكتشف تلقائيًا عند توفر Tailscale)
  • sshPort=<port> (وضع mDNS الكامل فقط؛ قد يحذفه DNS-SD واسع النطاق، وفي هذه الحالة تبقى افتراضيات SSH على 22)
  • cliPath=<path> (وضع mDNS الكامل فقط؛ لا يزال DNS-SD واسع النطاق يكتبه كتلميح تثبيت بعيد)

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

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

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

• openclaw plugins enable bonjour يمكّن إعلان multicast على الشبكة المحلية.
• OPENCLAW_DISABLE_BONJOUR=1 يعطّل الإعلان.
• عند تمكين Plugin الخاص بـ Bonjour وعدم تعيين OPENCLAW_DISABLE_BONJOUR، يعلن Bonjour على المضيفين العاديين ويتعطل تلقائيًا داخل الحاويات المكتشفة. يؤدي بدء تشغيل Gateway على macOS بإعدادات فارغة إلى تمكين Plugin تلقائيًا؛ أما Linux، وWindows، والنشر ضمن الحاويات فتحتاج إلى تمكين صريح. استخدم 0 فقط على مضيف أو macvlan أو شبكة أخرى قادرة على mDNS؛ واستخدم 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.

إذا كان Gateway يستطيع اكتشاف أنه يعمل تحت Tailscale، فإنه ينشر tailnetDns كتلميح اختياري للعملاء (بما في ذلك الإشارات واسعة النطاق).

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

بالنسبة إلى إقران Node على الهاتف المحمول، لا تخفف تلميحات الاكتشاف أمان النقل على مسارات tailnet/العامة:

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

# 3) هدف يدوي / SSH

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

انظر الوصول البعيد.

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

سلوك العميل الموصى به:

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

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

Gateway هو مصدر الحقيقة لقبول Node/العميل.

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

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

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

# ذات صلة

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