Bonjour / mDNS 탐색

OpenClaw는 활성 게이트웨이(WebSocket 엔드포인트)를 탐색하기 위한 LAN 전용 편의 기능으로 Bonjour(mDNS / DNS-SD)를 사용합니다. 최선형 방식이며 SSH 또는 Tailnet 기반 연결을 대체하지 않습니다.

광역 Bonjour (유니캐스트 DNS-SD) over Tailscale

노드와 게이트웨이가 서로 다른 네트워크에 있는 경우, 멀티캐스트 mDNS는 경계를 넘지 못합니다. Tailscale을 통한 유니캐스트 DNS-SD(“광역 Bonjour”)로 전환하면 동일한 탐색 UX를 유지할 수 있습니다.

대략적인 절차:

게이트웨이 호스트에서 DNS 서버를 실행합니다 (Tailnet을 통해 접근 가능).
전용 존(예: openclaw.internal.) 하에 _openclaw-gw._tcp에 대한 DNS-SD 레코드를 게시합니다.
클라이언트(iOS 포함)가 선택한 도메인을 해당 DNS 서버를 통해 해석하도록 Tailscale 분할 DNS를 설정합니다.

OpenClaw는 모든 탐색 도메인을 지원합니다. openclaw.internal.은 단지 예시일 뿐입니다. iOS/Android 노드는 local.과 설정된 광역 도메인 모두를 탐색합니다.

게이트웨이 설정 (권장)

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

일회성 DNS 서버 설정 (게이트웨이 호스트)

openclaw dns setup --apply

이렇게 하면 CoreDNS가 설치되고 다음과 같이 설정됩니다:

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

Tailnet에 연결된 머신에서 검증:

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

Tailscale DNS 설정

Tailscale 관리 콘솔에서:

게이트웨이의 Tailnet IP를 가리키는 네임서버를 추가합니다 (UDP/TCP 53).
탐색 도메인이 해당 네임서버를 사용하도록 분할 DNS를 추가합니다.

클라이언트가 Tailnet DNS를 수락하면, iOS 노드가 멀티캐스트 없이 탐색 도메인에서 _openclaw-gw._tcp를 탐색할 수 있습니다.

게이트웨이 리스너 보안 (권장)

게이트웨이 WS 포트(기본값 18789)는 기본적으로 루프백에 바인딩됩니다. LAN/Tailnet 접근을 위해서는 명시적으로 바인딩하고 인증을 활성화된 상태로 유지하세요.

Tailnet 전용 설정의 경우:

~/.openclaw/openclaw.json에서 gateway.bind: "tailnet"을 설정합니다.
게이트웨이를 재시작합니다 (또는 macOS 메뉴바 앱을 재시작합니다).

광고하는 것

게이트웨이만 _openclaw-gw._tcp를 광고합니다.

서비스 유형

_openclaw-gw._tcp — 게이트웨이 전송 비콘 (macOS/iOS/Android 노드에서 사용).

TXT 키 (비밀이 아닌 힌트)

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

role=gateway
displayName=<친숙한 이름>
lanHost=<호스트명>.local
gatewayPort=<포트> (게이트웨이 WS + HTTP)
gatewayTls=1 (TLS가 활성화된 경우에만)
gatewayTlsSha256=<sha256> (TLS가 활성화되고 핑거프린트를 사용할 수 있는 경우에만)
canvasPort=<포트> (캔버스 호스트가 활성화된 경우에만; 현재 gatewayPort와 동일)
sshPort=<포트> (오버라이드되지 않으면 기본값 22)
transport=gateway
cliPath=<경로> (선택적; 실행 가능한 openclaw 엔트리포인트의 절대 경로)
tailnetDns=<magicdns> (Tailnet을 사용할 수 있는 경우 선택적 힌트)

보안 참고 사항:

Bonjour/mDNS TXT 레코드는 인증되지 않습니다. 클라이언트는 TXT를 신뢰할 수 있는 라우팅으로 취급해서는 안 됩니다.
클라이언트는 해석된 서비스 엔드포인트(SRV + A/AAAA)를 사용하여 라우팅해야 합니다. lanHost, tailnetDns, gatewayPort, gatewayTlsSha256은 힌트로만 취급하세요.
TLS 고정은 광고된 gatewayTlsSha256이 이전에 저장된 핀을 덮어쓰는 것을 절대 허용해서는 안 됩니다.
iOS/Android 노드는 탐색 기반 직접 연결을 TLS 전용으로 취급하고, 최초 핑거프린트를 신뢰하기 전에 명시적인 사용자 확인을 요구해야 합니다.

macOS에서 디버깅

유용한 내장 도구:

인스턴스 탐색:
```
dns-sd -B _openclaw-gw._tcp local.
```
하나의 인스턴스 해석 (<instance>를 교체):
```
dns-sd -L "<instance>" _openclaw-gw._tcp local.
```

탐색은 되지만 해석이 실패하는 경우, 대개 LAN 정책 또는 mDNS 리졸버 문제입니다.

게이트웨이 로그에서 디버깅

게이트웨이는 롤링 로그 파일을 기록합니다 (시작 시 gateway log file: ...로 출력됨). bonjour: 줄을 찾아보세요:

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

iOS 노드에서 디버깅

iOS 노드는 NWBrowser를 사용하여 _openclaw-gw._tcp를 탐색합니다.

로그 캡처 방법:

설정 → 게이트웨이 → 고급 → Discovery Debug Logs
설정 → 게이트웨이 → 고급 → Discovery Logs → 재현 → 복사

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

일반적인 장애 모드

Bonjour는 네트워크를 넘지 못합니다: Tailnet 또는 SSH를 사용하세요.
멀티캐스트 차단: 일부 Wi-Fi 네트워크는 mDNS를 비활성화합니다.
절전 / 인터페이스 변동: macOS에서 mDNS 결과가 일시적으로 누락될 수 있습니다. 재시도하세요.
탐색은 되지만 해석 실패: 머신 이름을 단순하게 유지하고(이모지나 구두점 피하기), 게이트웨이를 재시작하세요. 서비스 인스턴스 이름은 호스트 이름에서 파생되므로, 지나치게 복잡한 이름은 일부 리졸버를 혼동시킬 수 있습니다.

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

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

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

비활성화 / 설정

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