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

OpenClaw دو مشکل مجزا دارد که در ظاهر شبیه به هم به نظر می‌رسند:

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

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

# اصطلاحات

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

جزئیات پروتکل:

• پروتکل Gateway
• پروتکل پل (قدیمی)

# چرا هر دو روش مستقیم و SSH را نگه می‌داریم

• WS مستقیم بهترین تجربه کاربری را روی همان شبکه و داخل یک tailnet فراهم می‌کند:
  • کشف خودکار روی LAN از طریق Bonjour
  • توکن‌های جفت‌سازی + ACLها که در مالکیت gateway هستند
  • نیازی به دسترسی shell نیست؛ سطح پروتکل می‌تواند محدود و قابل ممیزی بماند
• SSH همچنان بازگشت پشتیبان عمومی است:
  • هر جایی که دسترسی SSH داشته باشید کار می‌کند (حتی در شبکه‌های نامرتبط)
  • از مشکلات multicast/mDNS جان سالم به در می‌برد
  • به پورت ورودی جدیدی به‌جز SSH نیاز ندارد

# ورودی‌های کشف (کلاینت‌ها چگونه می‌فهمند gateway کجاست)

# 1) کشف Bonjour / DNS-SD

Bonjour چندپخشی best-effort است و از شبکه‌ها عبور نمی‌کند. OpenClaw همچنین می‌تواند همان beacon مربوط به gateway را از طریق یک دامنه DNS-SD گسترده پیکربندی‌شده مرور کند، بنابراین کشف می‌تواند این موارد را پوشش دهد:

• local. روی همان LAN
• یک دامنه unicast DNS-SD پیکربندی‌شده برای کشف بین‌شبکه‌ای

جهت هدف:

• gateway وقتی Plugin داخلی bonjour فعال باشد endpoint WS خود را از طریق Bonjour اعلان می‌کند. Plugin روی میزبان‌های macOS به‌صورت خودکار شروع می‌شود و در جاهای دیگر opt-in است.
• کلاینت‌ها مرور می‌کنند و فهرست «انتخاب یک gateway» را نشان می‌دهند، سپس endpoint انتخاب‌شده را ذخیره می‌کنند.

جزئیات عیب‌یابی و beacon: Bonjour.

# جزئیات beacon سرویس

• انواع سرویس:
  • _openclaw-gw._tcp (beacon انتقال 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> (پورت میزبان canvas؛ در حال حاضر وقتی میزبان canvas فعال باشد همان gatewayPort است)
  • tailnetDns=<magicdns> (راهنمای اختیاری؛ وقتی Tailscale در دسترس باشد به‌صورت خودکار تشخیص داده می‌شود)
  • sshPort=<port> (فقط حالت کامل mDNS؛ DNS-SD گسترده ممکن است آن را حذف کند، که در این صورت پیش‌فرض‌های SSH روی 22 می‌مانند)
  • cliPath=<path> (فقط حالت کامل mDNS؛ DNS-SD گسترده همچنان آن را به‌عنوان راهنمای نصب از راه دور می‌نویسد)

نکات امنیتی:

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

فعال‌سازی/غیرفعال‌سازی/override:

• openclaw plugins enable bonjour اعلان چندپخشی LAN را فعال می‌کند.
• OPENCLAW_DISABLE_BONJOUR=1 اعلان را غیرفعال می‌کند.
• وقتی Plugin Bonjour فعال باشد و OPENCLAW_DISABLE_BONJOUR تنظیم نشده باشد، Bonjour روی میزبان‌های عادی اعلان می‌کند و داخل کانتینرهای تشخیص‌داده‌شده به‌صورت خودکار غیرفعال می‌شود. شروع Gateway با پیکربندی خالی در macOS، Plugin را به‌صورت خودکار فعال می‌کند؛ استقرارهای Linux، Windows، و کانتینری به فعال‌سازی صریح نیاز دارند. از 0 فقط روی میزبان، macvlan، یا شبکه دیگری که قابلیت mDNS دارد استفاده کنید؛ از 1 برای غیرفعال‌سازی اجباری استفاده کنید.
• gateway.bind در ~/.openclaw/openclaw.json حالت bind مربوط به Gateway را کنترل می‌کند.
• OPENCLAW_SSH_PORT پورت SSH اعلان‌شده را وقتی sshPort منتشر می‌شود override می‌کند.
• OPENCLAW_TAILNET_DNS یک راهنمای tailnetDns (MagicDNS) منتشر می‌کند.
• OPENCLAW_CLI_PATH مسیر CLI اعلان‌شده را override می‌کند.

# 2) Tailnet (بین‌شبکه‌ای)

برای راه‌اندازی‌هایی به سبک لندن/وین، Bonjour کمکی نمی‌کند. هدف «مستقیم» پیشنهادی این است:

• نام Tailscale MagicDNS (ترجیحی) یا یک IP پایدار tailnet.

اگر gateway بتواند تشخیص دهد که تحت Tailscale اجرا می‌شود، tailnetDns را به‌عنوان یک راهنمای اختیاری برای کلاینت‌ها منتشر می‌کند (از جمله beaconهای گسترده).

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

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

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

# 3) هدف دستی / SSH

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

ببینید دسترسی از راه دور.

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

رفتار پیشنهادی کلاینت:

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

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

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

• درخواست‌های جفت‌سازی در gateway ایجاد/تأیید/رد می‌شوند (ببینید جفت‌سازی Gateway).
• gateway این موارد را اعمال می‌کند:
  • احراز هویت (توکن / keypair)
  • scopes/ACLها (gateway یک proxy خام برای هر متد نیست)
  • محدودیت‌های نرخ

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

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

# مرتبط

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