Bonjour discovery

Bonjour discovery 문서는 OpenClaw 공식 문서(gateway/bonjour)를 한국어로 정리한 가이드입니다. Bonjour/mDNS discovery + debugging (Gateway beacons, clients, and common failure modes) 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Bonjour/mDNS discovery + debugging (Gateway beacons, clients, and common failure modes)

한국어 가이드 범위: gateway/bonjour 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Wide-area Bonjour (Unicast DNS-SD) over Tailscale
Gateway config
One-time DNS server setup (gateway host, macOS only)
Tailscale DNS settings
Gateway listener security
What advertises
Service types
TXT keys (non-secret hints)
Debugging on macOS
Browse instances
Resolve one instance (replace )
Debugging in Gateway logs
Debugging on iOS node
When to enable Bonjour
When to disable Bonjour
Docker gotchas
Troubleshooting disabled Bonjour
Common failure modes
Escaped instance names (\032)
Enabling / disabling / configuration
Related docs

상세 내용

본문

OpenClaw can use Bonjour (mDNS/DNS-SD) to discover an active gateway (WebSocket endpoint). Multicast local. browsing is a LAN-only convenience: the bundled bonjour plugin owns LAN advertising, auto-starting on macOS hosts and opt-in on Linux, Windows, and containerized gateway deployments. The same beacon can also publish through a configured wide-area DNS-SD domain for cross-network discovery. Discovery is best-effort and does not replace SSH or Tailnet-based connectivity.

Wide-area Bonjour (Unicast DNS-SD) over Tailscale

If the node and gateway are on different networks, multicast mDNS can't cross the boundary. Keep the same discovery UX by switching to unicast DNS-SD ("Wide-Area Bonjour") over Tailscale:

Gateway config

discovery.wideArea.domain also accepts the OPENCLAW_WIDE_AREA_DOMAIN env var as a fallback when unset.

{
  gateway: { bind: "tailnet" }, // tailnet-only (recommended)
  discovery: { wideArea: { enabled: true, domain: "openclaw.internal" } },
}

One-time DNS server setup (gateway host, macOS only)

This command is macOS-only and requires Homebrew and a running Tailscale connection. It installs CoreDNS (brew install coredns) and configures it to:

주요 항목:

listen on port 53 only on the gateway's Tailscale interfaces
serve your chosen domain (example: openclaw.internal.) from ~/.openclaw/dns/<domain>.db

openclaw dns setup --apply

dns-sd -B _openclaw-gw._tcp openclaw.internal.
dig @<TAILNET_IPV4> -p 53 _openclaw-gw._tcp.openclaw.internal PTR +short

Tailscale DNS settings

Once clients accept Tailnet DNS, iOS nodes and CLI discovery can browse _openclaw-gw._tcp in your discovery domain without multicast.

주요 항목:

Add a nameserver pointing at the gateway's Tailnet IP (UDP/TCP 53).
Add split DNS so your discovery domain uses that nameserver.

Gateway listener security

The gateway WS port (default 18789) binds to loopback by default. For LAN/Tailnet access, bind explicitly and keep auth enabled. For Tailnet-only setups, set gateway.bind: "tailnet" in ~/.openclaw/openclaw.json and restart the gateway (or the macOS menubar app).

What advertises

Only the gateway advertises _openclaw-gw._tcp. LAN multicast advertising comes from the bundled bonjour plugin when enabled; wide-area DNS-SD publishing stays gateway-owned.

Service types

주요 항목:

_openclaw-gw._tcp - gateway transport beacon, used by macOS/iOS/Android nodes.

TXT keys (non-secret hints)

주요 항목:

Bonjour/mDNS TXT records are unauthenticated. Clients must not treat TXT as authoritative routing.
Clients should route using the resolved service endpoint (SRV + A/AAAA). Treat lanHost, tailnetDns, gatewayPort, and gatewayTlsSha256 as hints only.
SSH auto-targeting should likewise use the resolved service host, not TXT-only hints.
TLS pinning must never let an advertised gatewayTlsSha256 override a previously stored pin.
iOS/Android nodes should treat discovery-based direct connects as TLS-only and require explicit user confirmation before trusting a first-time fingerprint.

Key	When present
`role=gateway`	Always.
`displayName=<friendly name>`	Always.
`lanHost=<hostname>.local`	Always.
`gatewayPort=<port>`	Always (gateway WS + HTTP).
`transport=gateway`	Always.
`gatewayTls=1`	Only when TLS is enabled.
`gatewayTlsSha256=<sha256>`	Only when TLS is enabled and a fingerprint is available.
`gatewayDirectReachable=1`	Only when the gateway is directly reachable (not only via a relay/proxy path).
`canvasPort=<port>`	Only when the canvas host is enabled; currently the same as `gatewayPort`.
`tailnetDns=<magicdns>`	mDNS full mode only; optional hint when Tailnet is available.
`sshPort=<port>`	Full mode only; omitted in minimal and off modes.
`cliPath=<path>`	Full mode only; omitted in minimal and off modes.

Debugging on macOS

Built-in tools:


### Browse instances

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

### Resolve one instance (replace <instance>)

dns-sd -L "" _openclaw-gw._tcp local. ```

> 위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 `--help`를 확인하세요.

### Debugging in Gateway logs

The gateway writes a rolling log file (printed on startup as `gateway log file: ...`). Look for `bonjour:` lines, especially:

> 위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 `--help`를 확인하세요.

주요 항목:

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

### Debugging on iOS node

The iOS node uses `NWBrowser` to discover `_openclaw-gw._tcp`.

> 위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 `--help`를 확인하세요.

### When to enable Bonjour

Bonjour auto-starts for empty-config gateway startup on macOS hosts, since the local app and nearby iOS/Android nodes commonly rely on same-LAN discovery.

> 위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 `--help`를 확인하세요.

| Mode                | Behavior                                                                                                                                 |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `minimal` (default) | Core TXT keys only; omits `sshPort`, `cliPath`, `tailnetDns`.                                                                            |
| `full`              | Adds `sshPort`, `cliPath`, `tailnetDns` — use when clients need those hints.                                                             |
| `off`               | Suppresses LAN multicast without changing plugin enablement; wide-area DNS-SD can still publish when `discovery.wideArea.domain` is set. |

```bash
openclaw plugins enable bonjour

When to disable Bonjour

Leave Bonjour disabled when LAN multicast advertising is unnecessary, unavailable, or harmful — common cases are non-macOS servers, Docker bridge networking, WSL, or a network policy that drops mDNS multicast. The gateway stays reachable through its published URL, SSH, Tailnet, or wide-area DNS-SD; only LAN auto-discovery is unreliable.

OPENCLAW_DISABLE_BONJOUR=1

openclaw plugins disable bonjour

Docker gotchas

The bundled Bonjour plugin auto-disables LAN multicast advertising in detected containers when OPENCLAW_DISABLE_BONJOUR is unset. Docker bridge networks usually don't forward mDNS multicast (224.0.0.251:5353) between the container and the LAN, so advertising from the container rarely makes discovery work.

주요 항목:

Bonjour auto-starts on macOS hosts and is opt-in elsewhere. Leaving it disabled doesn't stop the gateway — it only skips LAN multicast advertising.
Disabling Bonjour doesn't change gateway.bind; Docker still defaults to OPENCLAW_GATEWAY_BIND=lan so the published host port works.
Disabling Bonjour doesn't disable wide-area DNS-SD. Use wide-area discovery or Tailnet when the gateway and node aren't on the same LAN.
Reusing the same OPENCLAW_CONFIG_DIR outside Docker doesn't persist the container auto-disable policy.
Set OPENCLAW_DISABLE_BONJOUR=0 only for host networking, macvlan, or another network where mDNS multicast is known to pass; set it to 1 to force-disable.

Troubleshooting disabled Bonjour

If a node no longer auto-discovers the gateway after Docker setup:

주요 항목:

Control UI or local tools: http://127.0.0.1:18789
LAN clients: http://<gateway-host>:18789
Cross-network clients: Tailnet MagicDNS, Tailnet IP, SSH tunnel, or wide-area DNS-SD

docker compose config | grep OPENCLAW_DISABLE_BONJOUR

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

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

Common failure modes

주요 항목:

Bonjour doesn't cross networks: use Tailnet or SSH.
Multicast blocked: some Wi-Fi networks disable mDNS.
Advertiser stuck in probing/announcing: hosts with blocked multicast, container bridges, WSL, or interface churn can leave the responder in a non-announced state. The gateway remains available through direct, SSH, Tailnet, or wide-area DNS-SD routes; disable LAN Bonjour with discovery.mdns.mode: "off" or OPENCLAW_DISABLE_BONJOUR=1 when multicast is unavailable.
Docker bridge networking: Bonjour auto-disables in detected containers. Set OPENCLAW_DISABLE_BONJOUR=0 only for host, macvlan, or another mDNS-capable network.
Sleep/interface churn: macOS may temporarily drop mDNS results; retry.
Browse works but resolve fails: keep machine names simple (avoid emojis or punctuation), then restart the gateway. The service instance name derives from the host name, so overly complex names can confuse some resolvers.

Escaped instance names (\032)

Bonjour/DNS-SD often escapes bytes in service instance names as decimal \DDD sequences (spaces become \032). This is normal at the protocol level; UIs should decode for display (iOS uses BonjourEscapes.decode).

Enabling / disabling / configuration

macOS hosts auto-start the bundled LAN discovery plugin by default. When the Bonjour plugin is enabled and OPENCLAW_DISABLE_BONJOUR is unset, Bonjour advertises on normal hosts and auto-disables inside detected containers (Docker, Fly.io machines, and common container runtimes).

Setting	Effect
`openclaw plugins enable bonjour`	Enables the bundled LAN discovery plugin on hosts where it isn't default-enabled.
`openclaw plugins disable bonjour`	Disables LAN multicast advertising by disabling the bundled plugin.
`OPENCLAW_DISABLE_BONJOUR=1` (or `true`/`yes`/`on`)	Disables LAN multicast advertising without changing plugin config.
`OPENCLAW_DISABLE_BONJOUR=0` (or `false`/`no`/`off`)	Forces LAN multicast advertising on, including inside detected containers.
`discovery.mdns.mode`	`off` \| `minimal` (default) \| `full` — see modes above.
`gateway.bind`	Controls the gateway bind mode in `~/.openclaw/openclaw.json`.
`OPENCLAW_SSH_PORT`	Overrides the SSH port when `sshPort` is advertised (full mode).
`OPENCLAW_TAILNET_DNS`	Publishes a MagicDNS hint in TXT when mDNS full mode is enabled.
`OPENCLAW_CLI_PATH`	Overrides the advertised CLI path (full mode).

주요 항목:

Discovery policy and transport selection: Discovery
Node pairing + approvals: Gateway pairing

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/gateway/bonjour
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

{
  gateway: { bind: "tailnet" }, // tailnet-only (recommended)
  discovery: { wideArea: { enabled: true, domain: "openclaw.internal" } },
}

openclaw dns setup --apply

dns-sd -B _openclaw-gw._tcp openclaw.internal.
dig @<TAILNET_IPV4> -p 53 _openclaw-gw._tcp.openclaw.internal PTR +short

# Browse instances
dns-sd -B _openclaw-gw._tcp local.

# Resolve one instance (replace <instance>)
dns-sd -L "<instance>" _openclaw-gw._tcp local.

openclaw plugins enable bonjour

OPENCLAW_DISABLE_BONJOUR=1

Bonjour discovery

핵심 요약

Bonjour/mDNS discovery + debugging (Gateway beacons, clients, and common failure modes)

한국어 가이드 범위: gateway/bonjour 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Wide-area Bonjour (Unicast DNS-SD) over Tailscale
Gateway config
One-time DNS server setup (gateway host, macOS only)
Tailscale DNS settings
Gateway listener security
What advertises
Service types
TXT keys (non-secret hints)
Debugging on macOS
Browse instances
Resolve one instance (replace )
Debugging in Gateway logs
Debugging on iOS node
When to enable Bonjour
When to disable Bonjour
Docker gotchas
Troubleshooting disabled Bonjour
Common failure modes
Escaped instance names (\032)
Enabling / disabling / configuration
Related docs

상세 내용

본문

Wide-area Bonjour (Unicast DNS-SD) over Tailscale

If the node and gateway are on different networks, multicast mDNS can't cross the boundary. Keep the same discovery UX by switching to unicast DNS-SD ("Wide-Area Bonjour") over Tailscale:

Gateway config

discovery.wideArea.domain also accepts the OPENCLAW_WIDE_AREA_DOMAIN env var as a fallback when unset.

{
  gateway: { bind: "tailnet" }, // tailnet-only (recommended)
  discovery: { wideArea: { enabled: true, domain: "openclaw.internal" } },
}

One-time DNS server setup (gateway host, macOS only)

This command is macOS-only and requires Homebrew and a running Tailscale connection. It installs CoreDNS (brew install coredns) and configures it to:

주요 항목:

listen on port 53 only on the gateway's Tailscale interfaces
serve your chosen domain (example: openclaw.internal.) from ~/.openclaw/dns/<domain>.db

openclaw dns setup --apply

dns-sd -B _openclaw-gw._tcp openclaw.internal.
dig @<TAILNET_IPV4> -p 53 _openclaw-gw._tcp.openclaw.internal PTR +short

Tailscale DNS settings

Once clients accept Tailnet DNS, iOS nodes and CLI discovery can browse _openclaw-gw._tcp in your discovery domain without multicast.

주요 항목:

Add a nameserver pointing at the gateway's Tailnet IP (UDP/TCP 53).
Add split DNS so your discovery domain uses that nameserver.

Gateway listener security

What advertises

Only the gateway advertises _openclaw-gw._tcp. LAN multicast advertising comes from the bundled bonjour plugin when enabled; wide-area DNS-SD publishing stays gateway-owned.

Service types

주요 항목:

_openclaw-gw._tcp - gateway transport beacon, used by macOS/iOS/Android nodes.

TXT keys (non-secret hints)

주요 항목:

Bonjour/mDNS TXT records are unauthenticated. Clients must not treat TXT as authoritative routing.
Clients should route using the resolved service endpoint (SRV + A/AAAA). Treat lanHost, tailnetDns, gatewayPort, and gatewayTlsSha256 as hints only.
SSH auto-targeting should likewise use the resolved service host, not TXT-only hints.
TLS pinning must never let an advertised gatewayTlsSha256 override a previously stored pin.
iOS/Android nodes should treat discovery-based direct connects as TLS-only and require explicit user confirmation before trusting a first-time fingerprint.

Key	When present
`role=gateway`	Always.
`displayName=<friendly name>`	Always.
`lanHost=<hostname>.local`	Always.
`gatewayPort=<port>`	Always (gateway WS + HTTP).
`transport=gateway`	Always.
`gatewayTls=1`	Only when TLS is enabled.
`gatewayTlsSha256=<sha256>`	Only when TLS is enabled and a fingerprint is available.
`gatewayDirectReachable=1`	Only when the gateway is directly reachable (not only via a relay/proxy path).
`canvasPort=<port>`	Only when the canvas host is enabled; currently the same as `gatewayPort`.
`tailnetDns=<magicdns>`	mDNS full mode only; optional hint when Tailnet is available.
`sshPort=<port>`	Full mode only; omitted in minimal and off modes.
`cliPath=<path>`	Full mode only; omitted in minimal and off modes.

Debugging on macOS

Built-in tools:


### Browse instances

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

### Resolve one instance (replace <instance>)

dns-sd -L "" _openclaw-gw._tcp local. ```

> 위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 `--help`를 확인하세요.

### Debugging in Gateway logs

The gateway writes a rolling log file (printed on startup as `gateway log file: ...`). Look for `bonjour:` lines, especially:

> 위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 `--help`를 확인하세요.

주요 항목:

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

### Debugging on iOS node

The iOS node uses `NWBrowser` to discover `_openclaw-gw._tcp`.

> 위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 `--help`를 확인하세요.

### When to enable Bonjour

Bonjour auto-starts for empty-config gateway startup on macOS hosts, since the local app and nearby iOS/Android nodes commonly rely on same-LAN discovery.

> 위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 `--help`를 확인하세요.

| Mode                | Behavior                                                                                                                                 |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `minimal` (default) | Core TXT keys only; omits `sshPort`, `cliPath`, `tailnetDns`.                                                                            |
| `full`              | Adds `sshPort`, `cliPath`, `tailnetDns` — use when clients need those hints.                                                             |
| `off`               | Suppresses LAN multicast without changing plugin enablement; wide-area DNS-SD can still publish when `discovery.wideArea.domain` is set. |

```bash
openclaw plugins enable bonjour

When to disable Bonjour

OPENCLAW_DISABLE_BONJOUR=1

openclaw plugins disable bonjour

Docker gotchas

주요 항목:

Bonjour auto-starts on macOS hosts and is opt-in elsewhere. Leaving it disabled doesn't stop the gateway — it only skips LAN multicast advertising.
Disabling Bonjour doesn't change gateway.bind; Docker still defaults to OPENCLAW_GATEWAY_BIND=lan so the published host port works.
Disabling Bonjour doesn't disable wide-area DNS-SD. Use wide-area discovery or Tailnet when the gateway and node aren't on the same LAN.
Reusing the same OPENCLAW_CONFIG_DIR outside Docker doesn't persist the container auto-disable policy.
Set OPENCLAW_DISABLE_BONJOUR=0 only for host networking, macvlan, or another network where mDNS multicast is known to pass; set it to 1 to force-disable.

Troubleshooting disabled Bonjour

If a node no longer auto-discovers the gateway after Docker setup:

주요 항목:

Control UI or local tools: http://127.0.0.1:18789
LAN clients: http://<gateway-host>:18789
Cross-network clients: Tailnet MagicDNS, Tailnet IP, SSH tunnel, or wide-area DNS-SD

docker compose config | grep OPENCLAW_DISABLE_BONJOUR

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

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

Common failure modes

주요 항목:

Bonjour doesn't cross networks: use Tailnet or SSH.
Multicast blocked: some Wi-Fi networks disable mDNS.
Advertiser stuck in probing/announcing: hosts with blocked multicast, container bridges, WSL, or interface churn can leave the responder in a non-announced state. The gateway remains available through direct, SSH, Tailnet, or wide-area DNS-SD routes; disable LAN Bonjour with discovery.mdns.mode: "off" or OPENCLAW_DISABLE_BONJOUR=1 when multicast is unavailable.
Docker bridge networking: Bonjour auto-disables in detected containers. Set OPENCLAW_DISABLE_BONJOUR=0 only for host, macvlan, or another mDNS-capable network.
Sleep/interface churn: macOS may temporarily drop mDNS results; retry.
Browse works but resolve fails: keep machine names simple (avoid emojis or punctuation), then restart the gateway. The service instance name derives from the host name, so overly complex names can confuse some resolvers.

Escaped instance names (\032)

Enabling / disabling / configuration

Setting	Effect
`openclaw plugins enable bonjour`	Enables the bundled LAN discovery plugin on hosts where it isn't default-enabled.
`openclaw plugins disable bonjour`	Disables LAN multicast advertising by disabling the bundled plugin.
`OPENCLAW_DISABLE_BONJOUR=1` (or `true`/`yes`/`on`)	Disables LAN multicast advertising without changing plugin config.
`OPENCLAW_DISABLE_BONJOUR=0` (or `false`/`no`/`off`)	Forces LAN multicast advertising on, including inside detected containers.
`discovery.mdns.mode`	`off` \| `minimal` (default) \| `full` — see modes above.
`gateway.bind`	Controls the gateway bind mode in `~/.openclaw/openclaw.json`.
`OPENCLAW_SSH_PORT`	Overrides the SSH port when `sshPort` is advertised (full mode).
`OPENCLAW_TAILNET_DNS`	Publishes a MagicDNS hint in TXT when mDNS full mode is enabled.
`OPENCLAW_CLI_PATH`	Overrides the advertised CLI path (full mode).

주요 항목:

Discovery policy and transport selection: Discovery
Node pairing + approvals: Gateway pairing

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/gateway/bonjour
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

{
  gateway: { bind: "tailnet" }, // tailnet-only (recommended)
  discovery: { wideArea: { enabled: true, domain: "openclaw.internal" } },
}

openclaw dns setup --apply

dns-sd -B _openclaw-gw._tcp openclaw.internal.
dig @<TAILNET_IPV4> -p 53 _openclaw-gw._tcp.openclaw.internal PTR +short

# Browse instances
dns-sd -B _openclaw-gw._tcp local.

# Resolve one instance (replace <instance>)
dns-sd -L "<instance>" _openclaw-gw._tcp local.

openclaw plugins enable bonjour

OPENCLAW_DISABLE_BONJOUR=1

Bonjour discovery

핵심 요약

문서 구성

상세 내용

본문

Wide-area Bonjour (Unicast DNS-SD) over Tailscale

Gateway config

One-time DNS server setup (gateway host, macOS only)

Tailscale DNS settings

Gateway listener security

What advertises

Service types

TXT keys (non-secret hints)

Debugging on macOS

When to disable Bonjour

Docker gotchas

Troubleshooting disabled Bonjour

Common failure modes

Escaped instance names (\032)

Enabling / disabling / configuration

Related docs

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Bonjour discovery

핵심 요약

문서 구성

상세 내용

본문

Wide-area Bonjour (Unicast DNS-SD) over Tailscale

Gateway config

One-time DNS server setup (gateway host, macOS only)

Tailscale DNS settings

Gateway listener security

What advertises

Service types

TXT keys (non-secret hints)

Debugging on macOS

When to disable Bonjour

Docker gotchas

Troubleshooting disabled Bonjour

Common failure modes

Escaped instance names (\032)

Enabling / disabling / configuration

Related docs

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드