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

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 به هیچ درگاه ورودی جدیدی نیاز ندارد.

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

۱) 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"، هم در اعلان‌کنندهٔ LAN و هم در DNS-SD گسترده حذف می‌شود (مقدار پیش‌فرض SSH برابر 22 است).
  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 اعلان‌شده را بازنویسی می‌کند.

۲) Tailnet (میان‌شبکه‌ای)

برای Gatewayهایی که در شبکه‌های فیزیکی متفاوت قرار دارند، Bonjour کمکی نمی‌کند. هدف مستقیم توصیه‌شده، یک نام MagicDNS متعلق به Tailscale (ترجیحی) یا یک نشانی 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:// راه دورِ متن ساده.
• اتصال مستقیم خصوصی LAN با ws:// همچنان پشتیبانی می‌شود.
• برای ساده‌ترین مسیر Tailscale روی Nodeهای موبایل، از Tailscale Serve استفاده کنید تا هم اکتشاف و هم راه‌اندازی به همان نقطهٔ پایانی امن MagicDNS تفکیک شوند.

۳) هدف دستی / SSH

هنگامی که هیچ مسیر مستقیمی وجود ندارد (یا مسیر مستقیم غیرفعال است)، کلاینت‌ها همیشه می‌توانند با هدایت درگاه Gateway در local loopback، از طریق 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