OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Gateway

کشف Bonjour

OpenClaw می‌تواند از Bonjour ‏(mDNS/DNS-SD) برای کشف یک Gateway فعال (نقطه پایانی WebSocket) استفاده کند. مرور چندپخشی local. یک قابلیت رفاهی صرفاً مخصوص LAN است: Plugin همراه bonjour مالک تبلیغ در LAN است و در میزبان‌های macOS به‌طور خودکار شروع می‌شود، اما در Linux، Windows و استقرارهای کانتینری Gateway نیازمند فعال‌سازی است. همین بیکن می‌تواند برای کشف بین‌شبکه‌ای، از طریق یک دامنه DNS-SD گسترده پیکربندی‌شده نیز منتشر شود. کشف بر مبنای بیشترین تلاش انجام می‌شود و جایگزین اتصال مبتنی بر SSH یا Tailnet نیست.

Bonjour گسترده (DNS-SD تک‌پخشی) روی Tailscale

اگر Node و Gateway در شبکه‌های متفاوتی باشند، mDNS چندپخشی نمی‌تواند از مرز شبکه عبور کند. با تغییر به DNS-SD تک‌پخشی («Bonjour گسترده») روی Tailscale، همان تجربه کاربری کشف را حفظ کنید:

  1. یک سرور DNS روی میزبان Gateway اجرا کنید که از طریق Tailnet قابل دسترسی باشد.
  2. رکوردهای DNS-SD را برای _openclaw-gw._tcp زیر یک ناحیه اختصاصی منتشر کنید (مثال: openclaw.internal.).
  3. ‏split DNS در Tailscale را طوری پیکربندی کنید که دامنه انتخابی شما برای کلاینت‌ها، از جمله iOS، از طریق آن سرور DNS تفکیک شود.

openclaw.internal. در بالا فقط یک مثال است — OpenClaw از هر دامنه کشفی پشتیبانی می‌کند. Nodeهای iOS/Android هم local. و هم دامنه گسترده پیکربندی‌شده شما را مرور می‌کنند.

پیکربندی Gateway

json5
{  gateway: { bind: "tailnet" }, // فقط tailnet (توصیه‌شده)  discovery: { wideArea: { enabled: true, domain: "openclaw.internal" } },}

discovery.wideArea.domain در صورت تنظیم‌نبودن، متغیر محیطی OPENCLAW_WIDE_AREA_DOMAIN را نیز به‌عنوان مسیر جایگزین می‌پذیرد.

راه‌اندازی یک‌باره سرور DNS (میزبان Gateway، فقط macOS)

bash
openclaw dns setup --apply

این فرمان فقط مخصوص macOS است و به Homebrew و یک اتصال فعال Tailscale نیاز دارد. این فرمان CoreDNS ‏(brew install coredns) را نصب و طوری پیکربندی می‌کند که:

  • فقط روی رابط‌های Tailscale متعلق به Gateway، به درگاه 53 گوش دهد
  • دامنه انتخابی شما (مثال: openclaw.internal.) را از ~/.openclaw/dns/<domain>.db ارائه کند

ابتدا بدون --apply اجرا کنید تا بدون نصب چیزی، طرح را پیش‌نمایش کنید (دامنه، مسیر فایل ناحیه، IP شناسایی‌شده Tailnet و پیکربندی توصیه‌شده).

از یک دستگاه متصل به Tailnet اعتبارسنجی کنید:

bash
dns-sd -B _openclaw-gw._tcp openclaw.internal.dig @&lt;TAILNET_IPV4&gt; -p 53 _openclaw-gw._tcp.openclaw.internal PTR +short

تنظیمات DNS در Tailscale

در کنسول مدیریت Tailscale:

  • یک nameserver اضافه کنید که به IP ‏Tailnet متعلق به Gateway اشاره کند (UDP/TCP 53).
  • ‏split DNS را اضافه کنید تا دامنه کشف شما از آن nameserver استفاده کند.

پس از پذیرش DNS ‏Tailnet توسط کلاینت‌ها، Nodeهای iOS و کشف CLI می‌توانند بدون چندپخشی، _openclaw-gw._tcp را در دامنه کشف شما مرور کنند.

امنیت شنونده Gateway

درگاه WS متعلق به Gateway (پیش‌فرض 18789) به‌طور پیش‌فرض به loopback متصل می‌شود. برای دسترسی از LAN/Tailnet، اتصال را صریحاً تنظیم کنید و احراز هویت را فعال نگه دارید. برای راه‌اندازی‌های صرفاً Tailnet، مقدار gateway.bind: "tailnet" را در ~/.openclaw/openclaw.json تنظیم و Gateway (یا برنامه نوار منوی macOS) را راه‌اندازی مجدد کنید.

چه چیزی تبلیغ می‌کند

فقط Gateway، ‏_openclaw-gw._tcp را تبلیغ می‌کند. تبلیغ چندپخشی LAN، در صورت فعال‌بودن، از Plugin همراه bonjour انجام می‌شود؛ انتشار DNS-SD گسترده همچنان در مالکیت Gateway باقی می‌ماند.

انواع سرویس

  • _openclaw-gw._tcp - بیکن انتقال Gateway که Nodeهای macOS/iOS/Android از آن استفاده می‌کنند.

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

کلید هنگام وجود
role=gateway همیشه.
displayName=<friendly name> همیشه.
lanHost=<hostname>.local همیشه.
gatewayPort=<port> همیشه (WS و HTTP متعلق به Gateway).
transport=gateway همیشه.
gatewayTls=1 فقط وقتی TLS فعال باشد.
gatewayTlsSha256=<sha256> فقط وقتی TLS فعال باشد و اثر انگشت در دسترس باشد.
gatewayDirectReachable=1 فقط وقتی Gateway مستقیماً قابل دسترسی باشد (نه فقط از طریق مسیر relay/proxy).
canvasPort=<port> فقط وقتی میزبان canvas فعال باشد؛ در حال حاضر همان gatewayPort است.
tailnetDns=<magicdns> فقط در حالت کامل mDNS؛ راهنمایی اختیاری هنگام دردسترس‌بودن Tailnet.
sshPort=<port> فقط حالت کامل؛ در حالت‌های حداقلی و خاموش حذف می‌شود.
cliPath=<path> فقط حالت کامل؛ در حالت‌های حداقلی و خاموش حذف می‌شود.

نکات امنیتی:

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

اشکال‌زدایی در macOS

ابزارهای داخلی:

bash
# مرور نمونه‌هاdns-sd -B _openclaw-gw._tcp local. # تفکیک یک نمونه (جایگزین‌کردن <instance>)dns-sd -L "<instance>" _openclaw-gw._tcp local.

اگر مرور کار می‌کند اما تفکیک ناموفق است، معمولاً با مشکل سیاست LAN یا تفکیک‌کننده mDNS روبه‌رو هستید.

اشکال‌زدایی در گزارش‌های Gateway

Gateway یک فایل گزارش چرخشی می‌نویسد (که هنگام راه‌اندازی به‌صورت gateway log file: ... چاپ می‌شود). به‌ویژه به‌دنبال خطوط bonjour: زیر باشید:

  • bonjour: advertise failed ...
  • bonjour: suppressing ciao netmask assertion ...
  • bonjour: ... name conflict resolved / hostname conflict resolved

OpenClaw هر سرویس Bonjour را یک‌بار راه‌اندازی می‌کند و کاوش، تلاش مجدد، رفع تعارض نام و انتشار مجدد هنگام تغییر رابط را به پاسخ‌دهنده mDNS واگذار می‌کند. این کار از هم‌پوشانی تلاش‌های انتشار هنگام نوسانات عادی شبکه جلوگیری می‌کند. پیام‌های تکراری کاوش داخلی خودِ سرویس سرکوب می‌شوند تا نتوانند گزارش Gateway را اشباع کنند.

وقتی چند Gateway متعلق به OpenClaw از یک میزبان تبلیغ می‌کنند، Bonjour ممکن است برای منحصربه‌فرد نگه‌داشتن نام نمونه‌های سرویس، پسوندهایی مانند (2) یا (3) اضافه کند. این پسوندها نتیجه عادی رفع تعارض هستند و نشان‌دهنده نظارت تکراری OCM نیستند.

Bonjour هنگامی که نام میزبان سیستم یک برچسب معتبر DNS باشد، آن را برای میزبان تبلیغ‌شده .local استفاده می‌کند. اگر نام میزبان سیستم حاوی فاصله، زیرخط یا نویسه نامعتبر دیگری برای برچسب DNS باشد، OpenClaw به openclaw.local برمی‌گردد. اگر به یک برچسب میزبان صریح نیاز دارید، پیش از راه‌اندازی Gateway، ‏OPENCLAW_MDNS_HOSTNAME=<name> را تنظیم کنید.

اشکال‌زدایی در Node ‏iOS

Node ‏iOS از NWBrowser برای کشف _openclaw-gw._tcp استفاده می‌کند.

برای ثبت گزارش‌ها: Settings -> Gateway -> Advanced -> Discovery Debug Logs، سپس Settings -> Gateway -> Advanced -> Discovery Logs -> بازتولید -> Copy. گزارش شامل گذارهای وضعیت مرورگر و تغییرات مجموعه نتایج است.

چه زمانی Bonjour را فعال کنیم

Bonjour برای شروع Gateway با پیکربندی خالی روی میزبان‌های macOS به‌طور خودکار راه‌اندازی می‌شود، زیرا برنامه محلی و Nodeهای نزدیک iOS/Android معمولاً به کشف در همان LAN متکی هستند.

هنگامی که کشف خودکار در همان LAN روی Linux، ‏Windows یا میزبان غیر macOS دیگری مفید است، آن را صریحاً فعال کنید:

bash
openclaw plugins enable bonjour

وقتی Bonjour فعال باشد، از discovery.mdns.mode برای تعیین میزان فراداده TXT قابل انتشار استفاده می‌کند؛ همین حالت، راهنمایی‌های اختیاری TXT را در رکوردهای DNS-SD گسترده نیز کنترل می‌کند. حالت‌ها:

حالت رفتار
minimal (پیش‌فرض) فقط کلیدهای اصلی TXT؛ ‏sshPort، ‏cliPath و tailnetDns را حذف می‌کند.
full ‏sshPort، ‏cliPath و tailnetDns را اضافه می‌کند — زمانی استفاده کنید که کلاینت‌ها به این راهنمایی‌ها نیاز دارند.
off چندپخشی LAN را بدون تغییر فعال‌بودن Plugin سرکوب می‌کند؛ وقتی discovery.wideArea.domain تنظیم شده باشد، DNS-SD گسترده همچنان می‌تواند منتشر کند.

چه زمانی Bonjour را غیرفعال کنیم

وقتی تبلیغ چندپخشی LAN غیرضروری، دردسترس‌ناپذیر یا زیان‌آور است، Bonjour را غیرفعال نگه دارید — موارد رایج شامل سرورهای غیر macOS، شبکه‌سازی bridge در Docker، ‏WSL یا سیاست شبکه‌ای است که چندپخشی mDNS را حذف می‌کند. Gateway از طریق URL منتشرشده، SSH، ‏Tailnet یا DNS-SD گسترده قابل دسترسی می‌ماند؛ فقط کشف خودکار LAN قابل اتکا نیست.

برای مشکلات محدود به استقرار از بازنویسی متغیر محیطی استفاده کنید (برای ایمیج‌های Docker، فایل‌های سرویس، اسکریپت‌های راه‌اندازی و اشکال‌زدایی موقت امن است — با حذف محیط ناپدید می‌شود):

bash
OPENCLAW_DISABLE_BONJOUR=1

وقتی عمداً می‌خواهید Plugin همراه کشف LAN را برای آن پیکربندی OpenClaw خاموش کنید، از پیکربندی Plugin استفاده کنید:

bash
openclaw plugins disable bonjour

نکات مهم Docker

Plugin همراه Bonjour در کانتینرهای شناسایی‌شده، هنگامی که OPENCLAW_DISABLE_BONJOUR تنظیم نشده باشد، تبلیغ چندپخشی LAN را به‌طور خودکار غیرفعال می‌کند. شبکه‌های bridge در Docker معمولاً چندپخشی mDNS ‏(224.0.0.251:5353) را بین کانتینر و LAN عبور نمی‌دهند، بنابراین تبلیغ از داخل کانتینر به‌ندرت باعث کارکرد کشف می‌شود.

نکات مهم:

  • Bonjour روی میزبان‌های macOS به‌طور خودکار راه‌اندازی می‌شود و در جاهای دیگر نیازمند فعال‌سازی است. غیرفعال نگه‌داشتن آن Gateway را متوقف نمی‌کند — فقط تبلیغ چندپخشی LAN را نادیده می‌گیرد.
  • غیرفعال‌کردن Bonjour مقدار gateway.bind را تغییر نمی‌دهد؛ Docker همچنان به‌طور پیش‌فرض از OPENCLAW_GATEWAY_BIND=lan استفاده می‌کند تا درگاه منتشرشده میزبان کار کند.
  • غیرفعال‌کردن Bonjour، ‏DNS-SD گسترده را غیرفعال نمی‌کند. وقتی Gateway و Node در یک LAN نیستند، از کشف گسترده یا Tailnet استفاده کنید.
  • استفاده مجدد از همان OPENCLAW_CONFIG_DIR خارج از Docker، سیاست غیرفعال‌سازی خودکار کانتینر را ماندگار نمی‌کند.
  • ‏OPENCLAW_DISABLE_BONJOUR=0 را فقط برای شبکه‌سازی میزبان، macvlan یا شبکه دیگری تنظیم کنید که عبور چندپخشی mDNS در آن قطعی باشد؛ برای غیرفعال‌سازی اجباری، آن را روی 1 تنظیم کنید.

عیب‌یابی Bonjour غیرفعال

اگر پس از راه‌اندازی Docker، یک Node دیگر Gateway را به‌طور خودکار کشف نمی‌کند:

  1. بررسی کنید که Gateway در حالت خودکار، روشن اجباری یا خاموش اجباری اجرا می‌شود:

    bash
    docker compose config | grep OPENCLAW_DISABLE_BONJOUR

  2. بررسی کنید که خود Gateway از طریق درگاه منتشرشده قابل دسترسی است:

    bash
    curl -fsS http://127.0.0.1:18789/healthz

  3. وقتی Bonjour غیرفعال است، از یک مقصد مستقیم استفاده کنید:

    • رابط کاربری کنترل یا ابزارهای محلی: http://127.0.0.1:18789
    • کلاینت‌های LAN: ‏http://<gateway-host>:18789
    • کلاینت‌های بین‌شبکه‌ای: Tailnet MagicDNS، ‏IP ‏Tailnet، تونل SSH یا DNS-SD گسترده

  4. اگر عمداً Plugin ‏Bonjour را در Docker فعال کرده‌اید و تبلیغ را با OPENCLAW_DISABLE_BONJOUR=0 اجباری کرده‌اید، چندپخشی را از میزبان آزمایش کنید:

    bash
    dns-sd -B _openclaw-gw._tcp local.

    اگر مرور خالی است یا گزارش‌های Gateway شکست‌های تکراری کاوش ciao را نشان می‌دهند، OPENCLAW_DISABLE_BONJOUR=1 را بازگردانید و از یک مسیر مستقیم یا Tailnet استفاده کنید.

حالت‌های رایج خرابی

  • Bonjour از شبکه‌ها عبور نمی‌کند: از Tailnet یا SSH استفاده کنید.
  • Multicast مسدود است: برخی شبکه‌های Wi-Fi، mDNS را غیرفعال می‌کنند.
  • تبلیغ‌کننده در مرحله بررسی/اعلام گیر کرده است: میزبان‌هایی با Multicast مسدود، پل‌های کانتینر، WSL یا تغییرات مکرر رابط می‌توانند پاسخ‌دهنده را در وضعیت اعلام‌نشده باقی بگذارند. Gateway همچنان از طریق مسیرهای مستقیم، SSH، Tailnet یا DNS-SD گسترده در دسترس است؛ وقتی Multicast در دسترس نیست، Bonjour شبکه محلی را با discovery.mdns.mode: "off" یا OPENCLAW_DISABLE_BONJOUR=1 غیرفعال کنید.
  • شبکه پل Docker: Bonjour در کانتینرهای شناسایی‌شده به‌طور خودکار غیرفعال می‌شود. OPENCLAW_DISABLE_BONJOUR=0 را فقط برای شبکه میزبان، macvlan یا شبکه دیگری که از mDNS پشتیبانی می‌کند تنظیم کنید.
  • تغییرات ناشی از خواب/رابط: macOS ممکن است نتایج mDNS را موقتاً از دست بدهد؛ دوباره تلاش کنید.
  • مرور کار می‌کند اما تفکیک نام ناموفق است: نام دستگاه‌ها را ساده نگه دارید (از ایموجی یا نشانه‌گذاری بپرهیزید)، سپس Gateway را راه‌اندازی مجدد کنید. نام نمونه سرویس از نام میزبان مشتق می‌شود؛ بنابراین نام‌های بیش‌ازحد پیچیده می‌توانند برخی تفکیک‌کننده‌ها را سردرگم کنند.

نام‌های نمونه گریزگذاری‌شده (\032)

Bonjour/DNS-SD اغلب بایت‌های موجود در نام نمونه سرویس را به‌شکل دنباله‌های ده‌دهی \DDD گریزگذاری می‌کند (فاصله‌ها به \032 تبدیل می‌شوند). این رفتار در سطح پروتکل عادی است؛ رابط‌های کاربری باید آن‌ها را برای نمایش رمزگشایی کنند (iOS از BonjourEscapes.decode استفاده می‌کند).

فعال‌سازی / غیرفعال‌سازی / پیکربندی

تنظیم اثر
openclaw plugins enable bonjour Plugin اکتشاف شبکه محلی همراه را روی میزبان‌هایی که به‌طور پیش‌فرض فعال نیست، فعال می‌کند.
openclaw plugins disable bonjour با غیرفعال‌کردن Plugin همراه، تبلیغات Multicast شبکه محلی را غیرفعال می‌کند.
OPENCLAW_DISABLE_BONJOUR=1 (یا true/yes/on) تبلیغات Multicast شبکه محلی را بدون تغییر پیکربندی Plugin غیرفعال می‌کند.
OPENCLAW_DISABLE_BONJOUR=0 (یا false/no/off) تبلیغات Multicast شبکه محلی را، از جمله داخل کانتینرهای شناسایی‌شده، به‌اجبار فعال می‌کند.
discovery.mdns.mode off | minimal (پیش‌فرض) | full — حالت‌های بالا را ببینید.
gateway.bind حالت اتصال Gateway را در ~/.openclaw/openclaw.json کنترل می‌کند.
OPENCLAW_SSH_PORT هنگام تبلیغ sshPort، درگاه SSH را بازنویسی می‌کند (حالت کامل).
OPENCLAW_TAILNET_DNS وقتی حالت کامل mDNS فعال است، یک راهنمای MagicDNS را در TXT منتشر می‌کند.
OPENCLAW_CLI_PATH مسیر CLI تبلیغ‌شده را بازنویسی می‌کند (حالت کامل).

میزبان‌های macOS به‌طور پیش‌فرض Plugin اکتشاف شبکه محلی همراه را خودکار راه‌اندازی می‌کنند. وقتی Plugin مربوط به Bonjour فعال و OPENCLAW_DISABLE_BONJOUR تنظیم‌نشده باشد، Bonjour روی میزبان‌های عادی تبلیغ می‌کند و داخل کانتینرهای شناسایی‌شده (Docker، ماشین‌های Fly.io و محیط‌های اجرای رایج کانتینر) به‌طور خودکار غیرفعال می‌شود.

مستندات مرتبط

Was this useful?
On this page

On this page