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

Gateway

کشف Bonjour

OpenClaw می‌تواند برای کشف یک Gateway فعال (نقطه پایانی WebSocket) از Bonjour ‏(mDNS/DNS-SD) استفاده کند. مرور چندپخشی 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) به‌طور پیش‌فرض به local 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 مستقیماً قابل دسترسی است (نه فقط از طریق مسیر رله/پراکسی).
canvasPort=<port> فقط هنگامی که میزبان بوم فعال است؛ در حال حاضر با 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 cancellation ...
  • bonjour: ... name conflict resolved / hostname conflict resolved
  • bonjour: watchdog detected non-announced service ...
  • bonjour: disabling advertiser after ... failed restarts ...

دیده‌بان، حالت‌های فعال probing، announcing و تغییرنام‌های تازه ناشی از تعارض را حالت‌های در حال انجام تلقی می‌کند. اگر سرویس هرگز به announced نرسد، OpenClaw اعلان‌کننده را دوباره ایجاد می‌کند و پس از شکست‌های مکرر، به‌جای اعلان مجدد بی‌پایان، Bonjour را برای آن فرایند Gateway غیرفعال می‌کند.

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

اشکال‌زدایی در Node مربوط به iOS

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

برای ثبت گزارش‌ها: 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.enabled برابر true باشد، DNS-SD گسترده همچنان می‌تواند بیکن حداقلی را منتشر کند.

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

هنگامی که اعلان چندپخشی LAN غیرضروری، ناممکن یا زیان‌آور است، Bonjour را غیرفعال نگه دارید — موارد رایج شامل سرورهای غیر macOS، شبکه‌سازی پل 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 را در کانتینرهای شناسایی‌شده به‌طور خودکار غیرفعال می‌کند. شبکه‌های پل 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، سیاست غیرفعال‌سازی خودکار کانتینر را پایدار نمی‌کند.
  • فقط برای شبکه میزبان، macvlan یا شبکه دیگری که عبور چندپخشی mDNS در آن قطعی است، OPENCLAW_DISABLE_BONJOUR=0 را تنظیم کنید؛ برای غیرفعال‌سازی اجباری، آن را روی 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
    • کلاینت‌های میان‌شبکه‌ای: MagicDNS در Tailnet،‏ 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 استفاده کنید.
  • چندپخشی مسدود است: برخی شبکه‌های Wi-Fi، mDNS را غیرفعال می‌کنند.
  • تبلیغ‌کننده در مرحلهٔ کاوش/اعلام گیر کرده است: میزبان‌هایی با چندپخشی مسدود، پل‌های کانتینری، WSL یا تغییرات مکرر رابط می‌توانند تبلیغ‌کنندهٔ ciao را در وضعیت اعلام‌نشده باقی بگذارند. OpenClaw چند بار تلاش مجدد می‌کند و سپس، به‌جای راه‌اندازی مجدد همیشگی تبلیغ‌کننده، Bonjour را برای فرایند Gateway فعلی غیرفعال می‌کند.
  • شبکه‌سازی پل 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 یکپارچهٔ کشف در LAN را روی میزبان‌هایی فعال می‌کند که به‌طور پیش‌فرض روی آن‌ها فعال نیست.
openclaw plugins disable bonjour با غیرفعال‌کردن Plugin یکپارچه، تبلیغات چندپخشی LAN را غیرفعال می‌کند.
OPENCLAW_DISABLE_BONJOUR=1 (یا true/yes/on) بدون تغییر پیکربندی Plugin، تبلیغات چندپخشی LAN را غیرفعال می‌کند.
OPENCLAW_DISABLE_BONJOUR=0 (یا false/no/off) تبلیغات چندپخشی LAN را حتی در کانتینرهای شناسایی‌شده به‌اجبار فعال می‌کند.
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 یکپارچهٔ کشف در LAN را به‌صورت خودکار راه‌اندازی می‌کنند. هنگامی که Plugin مربوط به Bonjour فعال باشد و OPENCLAW_DISABLE_BONJOUR تنظیم نشده باشد، Bonjour روی میزبان‌های عادی تبلیغ می‌کند و در کانتینرهای شناسایی‌شده (Docker، ماشین‌های Fly.io و محیط‌های اجرای رایج کانتینر) به‌طور خودکار غیرفعال می‌شود.

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

Was this useful?
On this page

On this page