---
read_when:
    - اشکال‌زدایی مشکلات کشف Bonjour در macOS/iOS
    - تغییر انواع سرویس mDNS، رکوردهای TXT یا تجربه کاربری کشف سرویس
summary: کشف و اشکال‌زدایی Bonjour/mDNS (بیکن‌های Gateway، کلاینت‌ها و حالت‌های رایج خرابی)
title: کشف Bonjour
x-i18n:
    generated_at: "2026-07-27T14:03:49Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: f43ef71b323b59362655c390a4df621c2571abbe3b2c1cd2728918c6f76d6f99
    source_path: gateway/bonjour.md
    workflow: 16
---

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 @<TAILNET_IPV4> -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 و محیط‌های اجرای رایج کانتینر) به‌طور خودکار غیرفعال می‌شود.

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

- سیاست اکتشاف و انتخاب انتقال: [اکتشاف](/fa/gateway/discovery)
- جفت‌سازی Node و تأییدها: [جفت‌سازی Gateway](/fa/gateway/pairing)
