الشبكات والاكتشاف

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

لدى OpenClaw مشكلتان متميزتان تبدوان متشابهتين على السطح:

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

الهدف التصميمي هو الاحتفاظ بجميع عمليات اكتشاف/الإعلان عن الشبكة في بوابة العقدة (openclaw gateway) وجعل العملاء (تطبيق mac، iOS) مستهلكين فقط.

المصطلحات

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

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

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

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

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

1) Bonjour / mDNS (شبكة LAN فقط)

Bonjour هو أفضل جهد ولا يعبر الشبكات. يُستخدم فقط لتسهيل "نفس شبكة LAN". الاتجاه المستهدف:

  • تقوم البوابة بالإعلان عن نقطة نهاية WS الخاصة بها عبر Bonjour.
  • يتصفح العملاء ويعرضون قائمة "اختر بوابة"، ثم يخزنون نقطة النهاية المختارة.

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

تفاصيل منارة الخدمة

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

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

  • سجلات 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 يتحكم في وضع ربط البوابة.
  • OPENCLAW_SSH_PORT يتجاوز منفذ SSH المُعلن عنه في TXT (الافتراضي 22).
  • OPENCLAW_TAILNET_DNS ينشر تلميح tailnetDns (MagicDNS).
  • OPENCLAW_CLI_PATH يتجاوز مسار CLI المُعلن عنه.

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

لإعدادات نمط London/Vienna، لن يساعد Bonjour. الهدف "المباشر" الموصى به هو:

  • اسم Tailscale MagicDNS (مفضل) أو عنوان IP ثابت في شبكة tailnet.

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

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

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

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

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

  1. إذا تم تكوين نقطة نهاية مباشرة مقترنة وكانت قابلة للوصول، فاستخدمها.
  2. وإلا، إذا وجد Bonjour بوابة على شبكة LAN، فاعرض خيار "استخدم هذه البوابة" بنقرة واحدة واحفظها كنقطة النهاية المباشرة.
  3. وإلا، إذا تم تكوين DNS/IP لشبكة tailnet، فجرّب المباشر.
  4. وإلا، ارجع إلى SSH.

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

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

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

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

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

الإقران المملوك للبوابةاكتشاف Bonjour