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

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

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

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

المصطلحات¶

• Gateway: عملية Gateway واحدة طويلة التشغيل تمتلك الحالة (الجلسات، الإقران، سجل العُقد) وتُشغّل القنوات. تستخدم معظم الإعدادات واحدة لكل مضيف؛ كما يمكن إعداد عدة Gateways معزولة.
• 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 قديم (مهجور/مزال): نقل عُقد أقدم (انظر بروتوكول الجسر)؛ لم يعد مُعلنًا للاكتشاف.

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

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

لماذا نحتفظ بكلٍّ من «المباشر» وSSH¶

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

مُدخلات الاكتشاف (كيف يتعرّف العملاء على مكان Gateway)¶

1. Bonjour / mDNS (LAN فقط)¶

يعمل Bonjour على أساس أفضل جهد ولا يعبر الشبكات. يُستخدم فقط لتسهيل «الشبكة المحلية نفسها».

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

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

تفاصيل الاستكشاف والمنارات: Bonjour.

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

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

التعطيل/التجاوز:

• OPENCLAW_DISABLE_BONJOUR=1 يعطّل الإعلان.
• gateway.bind ضمن ~/.openclaw/openclaw.json يتحكّم في وضع ربط Gateway.
• OPENCLAW_SSH_PORT يتجاوز منفذ SSH المُعلن في TXT (الافتراضي 22).
• OPENCLAW_TAILNET_DNS ينشر تلميح tailnetDns (MagicDNS).
• OPENCLAW_CLI_PATH يتجاوز مسار CLI المُعلن.

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

في إعدادات على نمط لندن/فيينا، لن يفيد Bonjour. الهدف «المباشر» الموصى به هو:

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

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

3. هدف يدوي / SSH¶

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

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

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

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

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

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

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

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

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

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