کشف و روش‌های انتقال

OpenClaw دو مسئلهٔ کشف مرتبط اما متمایز دارد:

1. کنترل از راه دور اپراتور: برنامهٔ نوار منوی macOS که Gateway در حال اجرا در جایی دیگر را کنترل می‌کند.
2. جفت‌سازی Node: یافتن یک Gateway و جفت‌سازی امن با آن توسط iOS/Android (و Nodeهای آینده).

تمام کشف/اعلان شبکه در Node Gateway انجام می‌شود (openclaw gateway)؛ کلاینت‌ها (برنامهٔ Mac،‏ iOS) فقط مصرف‌کننده‌اند.

اصطلاحات

• Gateway: یک فرایند واحد و طولانی‌مدت که مالک وضعیت (نشست‌ها، جفت‌سازی، رجیستری Node) است و کانال‌ها را اجرا می‌کند. بیشتر راه‌اندازی‌ها از یک مورد در هر میزبان استفاده می‌کنند؛ راه‌اندازی‌های چندGateway مجزا نیز ممکن‌اند.
• Gateway WS (صفحهٔ کنترل): نقطهٔ پایانی WebSocket که به‌طور پیش‌فرض روی 127.0.0.1:18789 است؛ آن را از طریق gateway.bind به LAN/tailnet متصل کنید.
• انتقال مستقیم WS: یک نقطهٔ پایانی Gateway WS روبه‌LAN/tailnet (بدون SSH).
• انتقال SSH (مسیر جایگزین): کنترل از راه دور با فورواردکردن 127.0.0.1:18789 از طریق SSH.
• پل TCP قدیمی (حذف‌شده): انتقال قدیمی‌تر Node (نگاه کنید به پروتکل پل)؛ دیگر برای کشف اعلان نمی‌شود و بخشی از ساخت‌های فعلی نیست.

جزئیات پروتکل: پروتکل Gateway، پروتکل پل (قدیمی).

چرا هم اتصال مستقیم و هم SSH وجود دارند

• WS مستقیم بهترین تجربهٔ کاربری را در یک شبکه و درون یک tailnet ارائه می‌دهد: کشف خودکار LAN از طریق Bonjour، توکن‌های جفت‌سازی و ACLهای تحت مالکیت Gateway، و بدون نیاز به دسترسی پوسته.
• SSH مسیر جایگزین عمومی است: هر جا دسترسی SSH داشته باشید کار می‌کند، حتی در شبکه‌های نامرتبط، در برابر مشکلات multicast/mDNS مقاوم است و جز SSH به هیچ درگاه ورودی جدیدی نیاز ندارد.

ورودی‌های کشف

1) Bonjour / DNS-SD

Bonjour چندپخشی به‌صورت بهترین‌تلاش عمل می‌کند و از شبکه‌ها عبور نمی‌کند. OpenClaw همچنین از مرور همان نشانگر Gateway از طریق یک دامنهٔ DNS-SD گستردهٔ پیکربندی‌شده پشتیبانی می‌کند؛ بنابراین کشف می‌تواند هم local. در همان LAN و هم یک دامنهٔ DNS-SD تک‌پخشی پیکربندی‌شده را برای کشف میان‌شبکه‌ای پوشش دهد.

هنگامی که Plugin همراه bonjour فعال باشد، Gateway نقطهٔ پایانی WS خود را از طریق Bonjour اعلان می‌کند؛ کلاینت‌ها آن را مرور می‌کنند و فهرست «انتخاب یک Gateway» را نمایش می‌دهند، سپس نقطهٔ پایانی انتخاب‌شده را ذخیره می‌کنند.

جزئیات عیب‌یابی و نشانگر: Bonjour.

جزئیات نشانگر سرویس

• نوع سرویس: _openclaw-gw._tcp (نشانگر انتقال Gateway).

• کلیدهای TXT (غیرمحرمانه):

  کلید	نکات
  role=gateway	همیشه موجود است.
  transport=gateway	همیشه موجود است.
  displayName=<name>	نام نمایشی پیکربندی‌شده توسط اپراتور.
  lanHost=<hostname>.local	فقط اعلان‌کنندهٔ mDNS در LAN؛ توسط DNS-SD گسترده نوشته نمی‌شود.
  gatewayPort=18789	درگاه Gateway WS + HTTP.
  gatewayTls=1	فقط هنگامی که TLS فعال است.
  gatewayTlsSha256=<sha256>	فقط هنگامی که TLS فعال است و اثر انگشت در دسترس باشد.
  tailnetDns=<magicdns>	راهنمای اختیاری؛ هنگامی که Tailscale در دسترس باشد به‌طور خودکار شناسایی می‌شود.
  sshPort=<port>	فقط هنگامی موجود است که discovery.mdns.mode="full"؛ در حالت پیش‌فرض "minimal" حذف می‌شود (SSH به‌طور پیش‌فرض از 22 استفاده می‌کند)، هم در اعلان‌کنندهٔ LAN و هم در DNS-SD گسترده.
  cliPath=<path>	همان محدودیت discovery.mdns.mode="full" مانند sshPort؛ راهنمای نصب از راه دور برای مسیر CLI.

  یک کلید TXT به نام canvasPort در قرارداد کشف Plugin برای یک درگاه میزبان canvas در آینده تعریف شده است، اما هیچ مسیر کد فعلی مقداری تنظیم نمی‌کند؛ بنابراین امروزه هرگز منتشر نمی‌شود.

نکات امنیتی:

• رکوردهای TXT در Bonjour/mDNS احراز اصالت نشده‌اند. کلاینت‌ها باید مقادیر TXT را فقط به‌عنوان راهنمای تجربهٔ کاربری در نظر بگیرند.
• مسیریابی (میزبان/درگاه) باید نقطهٔ پایانی سرویس تفکیک‌شده (SRV + A/AAAA) را بر lanHost،‏ tailnetDns یا gatewayPort ارائه‌شده از طریق TXT ترجیح دهد.
• سنجاق‌کردن TLS هرگز نباید اجازه دهد gatewayTlsSha256 اعلان‌شده جایگزین یک سنجاق ذخیره‌شدهٔ قبلی شود.
• Nodeهای iOS/Android باید پیش از ذخیرهٔ سنجاق برای اولین بار، تأیید صریح «اعتماد به این اثر انگشت» (راستی‌آزمایی خارج از باند) را الزامی کنند، هرگاه مسیر انتخاب‌شده امن/مبتنی بر TLS باشد.

فعال‌سازی، غیرفعال‌سازی و بازنویسی:

• openclaw plugins enable bonjour اعلان چندپخشی LAN را فعال می‌کند.
• discovery.mdns.mode در openclaw.json پخش mDNS را کنترل می‌کند: "minimal" (پیش‌فرض)، "full" (‏cliPath/sshPort را هم به نشانگر LAN و هم به هر ناحیهٔ 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) Tailnet (میان‌شبکه‌ای)

برای Gatewayهای روی شبکه‌های فیزیکی متفاوت، Bonjour کمکی نخواهد کرد. هدف مستقیم توصیه‌شده یک نام Tailscale MagicDNS (ترجیحی) یا یک IP پایدار tailnet است.

اگر Gateway تشخیص دهد که زیر Tailscale اجرا می‌شود، tailnetDns را به‌عنوان راهنمای اختیاری برای کلاینت‌ها منتشر می‌کند (از جمله در نشانگرهای گسترده). برنامهٔ macOS برای کشف Gateway، نام‌های MagicDNS را بر IPهای خام Tailscale ترجیح می‌دهد؛ زیرا وقتی IPهای tailnet تغییر می‌کنند (راه‌اندازی مجدد Node، تخصیص مجدد CGNAT)، همچنان قابل‌اعتماد می‌ماند و MagicDNS به‌طور خودکار به IP فعلی تفکیک می‌شود.

برای جفت‌سازی Node موبایل، راهنماهای کشف هرگز امنیت انتقال را در مسیرهای tailnet/عمومی کاهش نمی‌دهند:

• ‏iOS/Android همچنان به یک مسیر اتصال امن برای نخستین بار از طریق tailnet/عمومی (wss:// یا Tailscale Serve/Funnel) نیاز دارند.
• یک IP خام tailnet کشف‌شده راهنمای مسیریابی است، نه مجوزی برای استفاده از ws:// راه دورِ متن ساده.
• اتصال مستقیم ws:// در LAN خصوصی همچنان پشتیبانی می‌شود.
• برای ساده‌ترین مسیر Tailscale روی Nodeهای موبایل، از Tailscale Serve استفاده کنید تا هم کشف و هم راه‌اندازی به همان نقطهٔ پایانی امن MagicDNS تفکیک شوند.

3) هدف دستی / SSH

هنگامی که مسیر مستقیمی وجود ندارد (یا اتصال مستقیم غیرفعال است)، کلاینت‌ها همیشه می‌توانند با فورواردکردن درگاه loopback‏ Gateway از طریق SSH متصل شوند. نگاه کنید به دسترسی از راه دور.

انتخاب انتقال (سیاست کلاینت)

1. اگر یک نقطهٔ پایانی مستقیم جفت‌شده پیکربندی شده و در دسترس است، از آن استفاده کنید.
2. در غیر این صورت، اگر کشف یک Gateway را در local. یا دامنهٔ گستردهٔ پیکربندی‌شده پیدا کرد، گزینهٔ تک‌ضربه‌ای «استفاده از این Gateway» را ارائه دهید و آن را به‌عنوان نقطهٔ پایانی مستقیم ذخیره کنید.
3. در غیر این صورت، اگر DNS/IP یک tailnet پیکربندی شده است، اتصال مستقیم را امتحان کنید. برای Nodeهای موبایل در مسیرهای tailnet/عمومی، اتصال مستقیم به‌معنای یک نقطهٔ پایانی امن است، نه ws:// راه دورِ متن ساده.
4. در غیر این صورت، از SSH به‌عنوان مسیر جایگزین استفاده کنید.

جفت‌سازی و احراز هویت (انتقال مستقیم)

Gateway منبع حقیقت برای پذیرش Node/کلاینت است:

• درخواست‌های جفت‌سازی در Gateway ایجاد/تأیید/رد می‌شوند (نگاه کنید به جفت‌سازی Gateway).
• Gateway احراز هویت (توکن/جفت‌کلید)، دامنه‌ها/ACLها (یک پروکسی خام برای همهٔ متدها نیست) و محدودیت نرخ را اعمال می‌کند.

مسئولیت‌ها بر اساس مؤلفه

• Gateway: نشانگرهای کشف را اعلان می‌کند، مالک تصمیم‌های جفت‌سازی است و نقطهٔ پایانی WS را میزبانی می‌کند.
• برنامهٔ macOS: به انتخاب Gateway کمک می‌کند، اعلان‌های جفت‌سازی را نمایش می‌دهد و فقط به‌عنوان مسیر جایگزین از SSH استفاده می‌کند.
• Nodeهای iOS/Android: برای سهولت Bonjour را مرور می‌کنند و به Gateway WS جفت‌شده متصل می‌شوند.

مرتبط

• دسترسی از راه دور
• Tailscale
• کشف Bonjour