Bonjour / mDNS discovery

OpenClaw는 Bonjour (mDNS / DNS‑SD)를 LAN 전용 편의 기능으로 사용하여 활성 Gateway (WebSocket endpoint)를 검색합니다. 이는 best-effort이며 SSH 또는 Tailnet 기반 연결을 대체하지 않습니다.

Tailscale을 통한 Wide‑area Bonjour (Unicast DNS‑SD)

node와 gateway가 서로 다른 네트워크에 있으면 multicast mDNS가 경계를 넘지 못합니다. unicast DNS‑SD("Wide‑Area Bonjour")를 Tailscale을 통해 사용하여 동일한 discovery UX를 유지할 수 있습니다.

상위 수준 단계:

gateway host에서 DNS 서버를 실행합니다 (Tailnet을 통해 접근 가능).
전용 zone 아래에 _openclaw-gw._tcp에 대한 DNS‑SD 레코드를 게시합니다 (예: openclaw.internal.).
Tailscale split DNS를 구성하여 선택한 domain이 client (iOS 포함)에 대해 해당 DNS 서버를 통해 확인되도록 합니다.

OpenClaw는 모든 discovery domain을 지원합니다. openclaw.internal.은 단지 예시일 뿐입니다. iOS/Android node는 local.과 구성된 wide-area domain을 모두 탐색합니다.

Gateway config (권장)

{
  gateway: { bind: "tailnet" }, // tailnet 전용 (권장)
  discovery: { wideArea: { enabled: true } } // wide-area DNS-SD 게시 활성화
}

일회성 DNS 서버 설정 (gateway host)

openclaw dns setup --apply

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

gateway의 Tailscale interface에서만 포트 53에서 수신
~/.openclaw/dns/<domain>.db에서 선택한 domain (예: 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 admin console에서:

gateway의 tailnet IP를 가리키는 nameserver를 추가합니다 (UDP/TCP 53).
discovery domain이 해당 nameserver를 사용하도록 split DNS를 추가합니다.

client가 tailnet DNS를 수락하면 iOS node는 multicast 없이도 discovery domain에서 _openclaw-gw._tcp를 탐색할 수 있습니다.

Gateway listener 보안 (권장)

Gateway WS 포트 (기본값 18789)는 기본적으로 loopback에 바인딩됩니다. LAN/tailnet 액세스를 위해 명시적으로 바인딩하고 auth를 활성화 상태로 유지하세요.

tailnet 전용 설정의 경우:

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

광고하는 대상

Gateway만 _openclaw-gw._tcp를 광고합니다.

Service type

_openclaw-gw._tcp — gateway transport beacon (macOS/iOS/Android node에서 사용됨).

TXT key (비밀이 아닌 힌트)

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

role=gateway
displayName=<friendly name>
lanHost=<hostname>.local
gatewayPort=<port> (Gateway WS + HTTP)
gatewayTls=1 (TLS가 활성화된 경우에만)
gatewayTlsSha256=<sha256> (TLS가 활성화되고 fingerprint를 사용할 수 있는 경우에만)
canvasPort=<port> (canvas host가 활성화된 경우에만; 기본값 18793)
sshPort=<port> (재정의되지 않은 경우 기본값 22)
transport=gateway
cliPath=<path> (선택 사항; 실행 가능한 openclaw entrypoint의 절대 경로)
tailnetDns=<magicdns> (선택적 힌트; Tailnet을 사용할 수 있을 때)

macOS에서 디버깅

유용한 내장 tool:

instance 탐색:
```
dns-sd -B _openclaw-gw._tcp local.
```

하나의 instance 확인 (<instance> 교체):

dns-sd -L "<instance>" _openclaw-gw._tcp local.

탐색은 작동하지만 확인이 실패하는 경우, 일반적으로 LAN 정책 또는 mDNS resolver 문제입니다.

Gateway log에서 디버깅

Gateway는 rolling log 파일을 작성합니다 (시작 시 gateway log file: ...로 출력됨). bonjour: line을 찾아보세요, 특히:

bonjour: advertise failed ...
bonjour: ... name conflict resolved / hostname conflict resolved
bonjour: watchdog detected non-announced service ...

iOS node에서 디버깅

iOS node는 NWBrowser를 사용하여 _openclaw-gw._tcp를 검색합니다.

log를 캡처하려면:

설정 → Gateway → 고급 → Discovery Debug Logs
설정 → Gateway → 고급 → Discovery Logs → 재현 → 복사

log에는 browser 상태 전환 및 result-set 변경이 포함됩니다.

일반적인 장애 모드

Bonjour는 네트워크를 넘지 못함: Tailnet 또는 SSH를 사용하세요.
Multicast 차단됨: 일부 Wi‑Fi 네트워크는 mDNS를 비활성화합니다.
절전 / interface 변동: macOS가 mDNS 결과를 일시적으로 삭제할 수 있습니다; 재시도하세요.
탐색은 작동하지만 확인 실패: 머신 이름을 단순하게 유지하세요 (emoji 또는 구두점 피하기), 그런 다음 Gateway를 재시작하세요. service instance 이름은 host 이름에서 파생되므로 지나치게 복잡한 이름은 일부 resolver를 혼동할 수 있습니다.

이스케이프된 instance 이름 (\032)

Bonjour/DNS‑SD는 종종 service instance 이름의 byte를 십진수 \DDD 시퀀스로 이스케이프합니다 (예: 공백은 \032가 됨).

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

비활성화 / 구성

OPENCLAW_DISABLE_BONJOUR=1은 광고를 비활성화합니다 (레거시: OPENCLAW_DISABLE_BONJOUR).
~/.openclaw/openclaw.json의 gateway.bind는 Gateway 바인딩 모드를 제어합니다.
OPENCLAW_SSH_PORT는 TXT에 광고된 SSH 포트를 재정의합니다 (레거시: OPENCLAW_SSH_PORT).
OPENCLAW_TAILNET_DNS는 TXT에 MagicDNS 힌트를 게시합니다 (레거시: OPENCLAW_TAILNET_DNS).
OPENCLAW_CLI_PATH는 광고된 CLI 경로를 재정의합니다 (레거시: OPENCLAW_CLI_PATH).