Bonjour 검색

OpenClaw은 Bonjour(mDNS / DNS-SD)를 사용해 활성 Gateway(WebSocket 엔드포인트)를 발견할 수 있습니다. 멀티캐스트 local. 브라우징은 LAN 전용 편의 기능입니다. 번들된 bonjour Plugin이 LAN 광고를 담당합니다. macOS 호스트에서는 자동 시작되며, Linux, Windows, 컨테이너화된 Gateway 배포에서는 옵트인 방식입니다. 네트워크 간 발견을 위해 동일한 비콘을 구성된 광역 DNS-SD 도메인을 통해 게시할 수도 있습니다. 발견은 여전히 최선 노력 방식이며 SSH 또는 Tailnet 기반 연결을 대체하지 않습니다.

Tailscale을 통한 광역 Bonjour(Unicast DNS-SD)

Node와 gateway가 서로 다른 네트워크에 있으면 멀티캐스트 mDNS는 경계를 넘지 않습니다. Tailscale을 통해 unicast DNS-SD (“광역 Bonjour”)로 전환하면 동일한 발견 UX를 유지할 수 있습니다. 상위 단계:

gateway 호스트에서 DNS 서버를 실행합니다(Tailnet을 통해 접근 가능).
전용 영역 아래에 _openclaw-gw._tcp에 대한 DNS-SD 레코드를 게시합니다 (예: openclaw.internal.).
Tailscale split DNS를 구성해 선택한 도메인이 클라이언트(iOS 포함)에서 해당 DNS 서버를 통해 해석되도록 합니다.

OpenClaw은 어떤 발견 도메인도 지원합니다. openclaw.internal.은 예시일 뿐입니다. iOS/Android Node는 local.과 구성한 광역 도메인을 모두 탐색합니다.

Gateway 구성(권장)

{
  gateway: { bind: "tailnet" }, // tailnet-only (recommended)
  discovery: { wideArea: { enabled: true } }, // enables wide-area DNS-SD publishing
}

1회성 DNS 서버 설정(gateway 호스트)

openclaw dns setup --apply

이 명령은 CoreDNS를 설치하고 다음과 같이 구성합니다.

gateway의 Tailscale 인터페이스에서만 포트 53을 수신합니다
~/.openclaw/dns/<domain>.db에서 선택한 도메인(예: openclaw.internal.)을 제공합니다

tailnet에 연결된 머신에서 검증합니다.

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

Tailscale DNS 설정

Tailscale 관리자 콘솔에서:

gateway의 tailnet IP(UDP/TCP 53)를 가리키는 네임서버를 추가합니다.
발견 도메인이 해당 네임서버를 사용하도록 split DNS를 추가합니다.

클라이언트가 tailnet DNS를 수락하면 iOS Node와 CLI 발견은 멀티캐스트 없이도 발견 도메인에서 _openclaw-gw._tcp를 탐색할 수 있습니다.

Gateway 리스너 보안(권장)

Gateway WS 포트(기본값 18789)는 기본적으로 루프백에 바인딩됩니다. LAN/tailnet 접근의 경우 명시적으로 바인딩하고 인증을 활성화된 상태로 유지하세요. tailnet 전용 설정의 경우:

~/.openclaw/openclaw.json에서 gateway.bind: "tailnet"을 설정합니다.
Gateway를 재시작합니다(또는 macOS 메뉴 막대 앱을 재시작합니다).

광고 대상

Gateway만 _openclaw-gw._tcp를 광고합니다. LAN 멀티캐스트 광고는 Plugin이 활성화되어 있을 때 번들된 bonjour Plugin이 제공하며, 광역 DNS-SD 게시는 계속 Gateway가 담당합니다.

서비스 유형

_openclaw-gw._tcp - gateway 전송 비콘(macOS/iOS/Android Node가 사용).

TXT 키(비밀이 아닌 힌트)

Gateway는 UI 흐름을 편리하게 만들기 위해 작은 비밀이 아닌 힌트를 광고합니다.

role=gateway
displayName=<friendly name>
lanHost=<hostname>.local
gatewayPort=<port> (Gateway WS + HTTP)
gatewayTls=1 (TLS가 활성화된 경우에만)
gatewayTlsSha256=<sha256> (TLS가 활성화되어 있고 지문을 사용할 수 있는 경우에만)
canvasPort=<port> (canvas 호스트가 활성화된 경우에만. 현재는 gatewayPort와 동일)
transport=gateway
tailnetDns=<magicdns> (mDNS 전체 모드에서만, Tailnet을 사용할 수 있을 때의 선택적 힌트)
sshPort=<port> (전체 모드에서만. 최소 및 꺼짐 모드에서는 생략)
cliPath=<path> (전체 모드에서만. 최소 및 꺼짐 모드에서는 생략)

보안 참고 사항:

Bonjour/mDNS TXT 레코드는 인증되지 않습니다. 클라이언트는 TXT를 권위 있는 라우팅 정보로 취급해서는 안 됩니다.
클라이언트는 해석된 서비스 엔드포인트(SRV + A/AAAA)를 사용해 라우팅해야 합니다. lanHost, tailnetDns, gatewayPort, gatewayTlsSha256는 힌트로만 취급하세요.
SSH 자동 대상 지정도 TXT 전용 힌트가 아니라 해석된 서비스 호스트를 사용해야 합니다.
TLS pinning은 광고된 gatewayTlsSha256이 이전에 저장된 pin을 재정의하도록 허용해서는 절대 안 됩니다.
iOS/Android Node는 발견 기반 직접 연결을 TLS 전용으로 취급하고, 처음 보는 지문을 신뢰하기 전에 명시적인 사용자 확인을 요구해야 합니다.

macOS에서 디버깅

유용한 기본 제공 도구:

인스턴스 탐색:
```
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 ...

watchdog은 활성 probing, announcing, 그리고 최근 충돌 이름 변경을 진행 중 상태로 취급합니다. 서비스가 끝내 announced에 도달하지 못하면 OpenClaw은 결국 광고자를 다시 생성하고, 반복 실패 후에는 계속 재광고하는 대신 해당 Gateway 프로세스에서 Bonjour를 비활성화합니다. Bonjour는 유효한 DNS 레이블인 경우 광고되는 .local 호스트에 시스템 호스트 이름을 사용합니다. 시스템 호스트 이름에 공백, 밑줄 또는 다른 유효하지 않은 DNS 레이블 문자가 포함되어 있으면 OpenClaw은 openclaw.local로 폴백합니다. 명시적 호스트 레이블이 필요하면 Gateway를 시작하기 전에 OPENCLAW_MDNS_HOSTNAME=<name>을 설정하세요.

iOS Node에서 디버깅

iOS Node는 NWBrowser를 사용해 _openclaw-gw._tcp를 발견합니다. 로그를 캡처하려면:

Settings → Gateway → Advanced → Discovery Debug Logs
Settings → Gateway → Advanced → Discovery Logs → 재현 → Copy

로그에는 브라우저 상태 전환과 결과 집합 변경이 포함됩니다.

Bonjour를 활성화해야 하는 경우

Bonjour는 로컬 앱과 근처 iOS/Android Node가 같은 LAN 발견에 흔히 의존하기 때문에 macOS 호스트에서 빈 구성 Gateway 시작 시 자동 시작됩니다. Linux, Windows 또는 다른 비-macOS 호스트에서 같은 LAN 자동 발견이 유용한 경우 Bonjour를 명시적으로 활성화하세요.

openclaw plugins enable bonjour

활성화되면 Bonjour는 discovery.mdns.mode를 사용해 게시할 TXT 메타데이터의 양을 결정합니다. 같은 모드는 광역 DNS-SD 레코드의 선택적 TXT 힌트도 제어합니다. 기본 모드는 minimal입니다. 클라이언트에 cliPath 또는 sshPort 힌트가 필요할 때만 full을 사용하세요. Plugin 활성화 상태를 바꾸지 않고 LAN 멀티캐스트를 억제하려면 off를 사용하세요. discovery.wideArea.enabled가 true이면 광역 DNS-SD는 여전히 최소 Gateway 비콘을 게시할 수 있습니다.

Bonjour를 비활성화해야 하는 경우

LAN 멀티캐스트 광고가 불필요하거나, 사용할 수 없거나, 해로운 경우 Bonjour를 비활성화된 상태로 두세요. 일반적인 경우는 비-macOS 서버, Docker 브리지 네트워킹, WSL, 또는 mDNS 멀티캐스트를 차단하는 네트워크 정책입니다. 이러한 환경에서도 Gateway는 게시된 URL, SSH, Tailnet 또는 광역 DNS-SD를 통해 여전히 접근 가능하지만 LAN 자동 발견은 신뢰할 수 없습니다. 문제가 배포 범위에 한정되어 있다면 기존 환경 재정의를 우선 사용하세요.

OPENCLAW_DISABLE_BONJOUR=1

이는 Plugin 구성을 변경하지 않고 LAN 멀티캐스트 광고를 비활성화합니다. 이 설정은 환경이 사라지면 함께 사라지므로 Docker 이미지, 서비스 파일, 시작 스크립트, 일회성 디버깅에 안전합니다. 해당 OpenClaw 구성에서 번들된 LAN 발견 Plugin을 의도적으로 끄고 싶을 때는 Plugin 구성을 사용하세요.

openclaw plugins disable bonjour

Docker 주의 사항

번들된 Bonjour Plugin은 OPENCLAW_DISABLE_BONJOUR가 설정되지 않았을 때 감지된 컨테이너에서 LAN 멀티캐스트 광고를 자동 비활성화합니다. Docker 브리지 네트워크는 일반적으로 컨테이너와 LAN 사이에서 mDNS 멀티캐스트(224.0.0.251:5353)를 전달하지 않으므로, 컨테이너에서 광고해도 발견이 작동하는 경우는 드뭅니다. 중요한 주의 사항:

Bonjour는 macOS 호스트에서는 자동 시작되고 그 외 환경에서는 옵트인입니다. 비활성화된 상태로 두어도 Gateway가 중지되지는 않으며, LAN 멀티캐스트 광고만 건너뜁니다.
Bonjour를 비활성화해도 gateway.bind는 변경되지 않습니다. Docker는 게시된 호스트 포트가 작동할 수 있도록 여전히 기본값으로 OPENCLAW_GATEWAY_BIND=lan을 사용합니다.
Bonjour를 비활성화해도 광역 DNS-SD는 비활성화되지 않습니다. Gateway와 Node가 같은 LAN에 있지 않을 때는 광역 발견 또는 Tailnet을 사용하세요.
Docker 밖에서 같은 OPENCLAW_CONFIG_DIR을 재사용해도 컨테이너 자동 비활성화 정책은 유지되지 않습니다.
호스트 네트워킹, macvlan 또는 mDNS 멀티캐스트가 통과한다고 알려진 다른 네트워크에서만 OPENCLAW_DISABLE_BONJOUR=0을 설정하세요. 강제로 비활성화하려면 1로 설정하세요.

비활성화된 Bonjour 문제 해결

Docker 설정 후 Node가 더 이상 Gateway를 자동 발견하지 못하면:

Gateway가 자동, 강제 켜짐, 강제 꺼짐 모드 중 어디에서 실행 중인지 확인합니다.
```
docker compose config | grep OPENCLAW_DISABLE_BONJOUR
```
게시된 포트를 통해 Gateway 자체에 접근할 수 있는지 확인합니다.
```
curl -fsS http://127.0.0.1:18789/healthz
```
Bonjour가 비활성화된 경우 직접 대상을 사용합니다.
- Control UI 또는 로컬 도구: http://127.0.0.1:18789
- LAN 클라이언트: http://<gateway-host>:18789
- 네트워크 간 클라이언트: Tailnet MagicDNS, Tailnet IP, SSH 터널 또는 광역 DNS-SD
Docker에서 Bonjour Plugin을 의도적으로 활성화하고 OPENCLAW_DISABLE_BONJOUR=0으로 광고를 강제했다면 호스트에서 멀티캐스트를 테스트합니다.
```
dns-sd -B _openclaw-gw._tcp local.
```
탐색 결과가 비어 있거나 Gateway 로그에 ciao watchdog 취소가 반복 표시되면 OPENCLAW_DISABLE_BONJOUR=1을 복원하고 직접 또는 Tailnet 경로를 사용하세요.

일반적인 실패 모드

Bonjour는 네트워크를 넘지 않습니다: Tailnet 또는 SSH를 사용하세요.
멀티캐스트가 차단됨: 일부 Wi-Fi 네트워크는 mDNS를 비활성화합니다.
광고자가 probing/announcing 상태에 멈춤: 멀티캐스트가 차단된 호스트, 컨테이너 브리지, WSL 또는 인터페이스 변동은 ciao 광고자를 announced가 아닌 상태로 남겨둘 수 있습니다. OpenClaw은 몇 번 재시도한 다음 광고자를 계속 재시작하는 대신 현재 Gateway 프로세스에서 Bonjour를 비활성화합니다.
Docker 브리지 네트워킹: Bonjour는 감지된 컨테이너에서 자동 비활성화됩니다. 호스트, macvlan 또는 다른 mDNS 지원 네트워크에서만 OPENCLAW_DISABLE_BONJOUR=0을 설정하세요.
절전 / 인터페이스 변동: macOS는 일시적으로 mDNS 결과를 잃을 수 있습니다. 다시 시도하세요.
탐색은 작동하지만 해석이 실패함: 머신 이름을 단순하게 유지하고(이모지나 문장 부호 피하기) Gateway를 재시작하세요. 서비스 인스턴스 이름은 호스트 이름에서 파생되므로 지나치게 복잡한 이름은 일부 리졸버를 혼란스럽게 할 수 있습니다.

이스케이프된 인스턴스 이름(`\032`)

Bonjour/DNS-SD는 서비스 인스턴스 이름의 바이트를 종종 십진수 \DDD 시퀀스(예: 공백은 \032)로 이스케이프합니다.

이는 프로토콜 수준에서 정상입니다.
UI는 표시를 위해 디코딩해야 합니다(iOS는 BonjourEscapes.decode 사용).

활성화 / 비활성화 / 구성

macOS 호스트는 기본적으로 번들 LAN 탐색 Plugin을 자동 시작합니다.
openclaw plugins enable bonjour는 기본 활성화되지 않은 호스트에서 번들 LAN 탐색 Plugin을 활성화합니다.
openclaw plugins disable bonjour는 번들 Plugin을 비활성화하여 LAN 멀티캐스트 광고를 비활성화합니다.
OPENCLAW_DISABLE_BONJOUR=1은 Plugin 구성을 변경하지 않고 LAN 멀티캐스트 광고를 비활성화합니다. 허용되는 truthy 값은 1, true, yes, on입니다(레거시: OPENCLAW_DISABLE_BONJOUR).
OPENCLAW_DISABLE_BONJOUR=0은 감지된 컨테이너 내부를 포함하여 LAN 멀티캐스트 광고를 강제로 활성화합니다. 허용되는 falsy 값은 0, false, no, off입니다.
Bonjour Plugin이 활성화되어 있고 OPENCLAW_DISABLE_BONJOUR가 설정되지 않은 경우, Bonjour는 일반 호스트에서는 광고하고 감지된 컨테이너 내부에서는 자동으로 비활성화됩니다.
~/.openclaw/openclaw.json의 gateway.bind는 Gateway 바인딩 모드를 제어합니다.
sshPort가 광고될 때 OPENCLAW_SSH_PORT는 SSH 포트를 재정의합니다(레거시: OPENCLAW_SSH_PORT).
OPENCLAW_TAILNET_DNS는 mDNS 전체 모드가 활성화된 경우 TXT에 MagicDNS 힌트를 게시합니다(레거시: OPENCLAW_TAILNET_DNS).
OPENCLAW_CLI_PATH는 광고되는 CLI 경로를 재정의합니다(레거시: OPENCLAW_CLI_PATH).

Gateway

Remote access

Security

Nodes and media

Web interfaces

Tailscale을 통한 광역 Bonjour(Unicast DNS-SD)

Gateway 구성(권장)

1회성 DNS 서버 설정(gateway 호스트)

Tailscale DNS 설정

Gateway 리스너 보안(권장)

광고 대상

서비스 유형

TXT 키(비밀이 아닌 힌트)

macOS에서 디버깅

Gateway 로그에서 디버깅

iOS Node에서 디버깅

Bonjour를 활성화해야 하는 경우

Bonjour를 비활성화해야 하는 경우

Docker 주의 사항

비활성화된 Bonjour 문제 해결

일반적인 실패 모드

이스케이프된 인스턴스 이름(`\032`)

활성화 / 비활성화 / 구성

관련 문서

Gateway

Remote access

Security

Nodes and media

Web interfaces

Documentation Index

​Tailscale을 통한 광역 Bonjour(Unicast DNS-SD)

​Gateway 구성(권장)

​1회성 DNS 서버 설정(gateway 호스트)

​Tailscale DNS 설정

​Gateway 리스너 보안(권장)

​광고 대상

​서비스 유형

​TXT 키(비밀이 아닌 힌트)

​macOS에서 디버깅

​Gateway 로그에서 디버깅

​iOS Node에서 디버깅

​Bonjour를 활성화해야 하는 경우

​Bonjour를 비활성화해야 하는 경우

​Docker 주의 사항

​비활성화된 Bonjour 문제 해결

​일반적인 실패 모드

​이스케이프된 인스턴스 이름(\032)

​활성화 / 비활성화 / 구성

​관련 문서

Tailscale을 통한 광역 Bonjour(Unicast DNS-SD)

Gateway 구성(권장)

1회성 DNS 서버 설정(gateway 호스트)

Tailscale DNS 설정

Gateway 리스너 보안(권장)

광고 대상

서비스 유형

TXT 키(비밀이 아닌 힌트)

macOS에서 디버깅

Gateway 로그에서 디버깅

iOS Node에서 디버깅

Bonjour를 활성화해야 하는 경우

Bonjour를 비활성화해야 하는 경우

Docker 주의 사항

비활성화된 Bonjour 문제 해결

일반적인 실패 모드

이스케이프된 인스턴스 이름(`\032`)

활성화 / 비활성화 / 구성

관련 문서