봉쥬르 / mDNS 검색

OpenClaw는 LAN 전용 편의로 Bonjour(mDNS / DNS‑SD)를 사용하여 활성 게이트웨이(WebSocket 엔드포인트) 이는 최선의 노력이며 SSH를 대체하지 않습니다 Tailnet 기반 연결.

Tailscale을 통한 광역 Bonjour(유니캐스트 DNS-SD)

노드와 게이트웨이가 서로 다른 네트워크에 있는 경우 멀티캐스트 mDNS는 경계. 유니캐스트 DNS‑SD로 전환하여 동일한 검색 UX를 유지할 수 있습니다. ("Wide‑Area Bonjour")(Tailscale을 통한).

개략적인 단계:

1. 게이트웨이 호스트(Tailnet을 통해 연결 가능)에서 DNS 서버를 실행합니다.
2. 전용 영역에 _openclaw-gw._tcp에 대한 DNS‑SD 레코드 게시 (예: openclaw.internal.).
3. 선택한 도메인이 이를 통해 확인되도록 Tailscale 분할 DNS를 구성합니다. 클라이언트용 DNS 서버(iOS 포함)

OpenClaw는 모든 검색 도메인을 지원합니다. openclaw.internal.는 단지 예시일 뿐입니다. iOS/Android 노드는 local. 및 구성된 광역 도메인을 모두 탐색합니다.

게이트웨이 구성(권장)

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

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

openclaw dns setup --apply

그러면 CoreDNS가 설치되고 다음과 같이 구성됩니다.

• 게이트웨이의 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 관리 콘솔에서:

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

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

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

Gateway WS 포트(기본값 18789)는 기본적으로 루프백에 바인딩됩니다. LAN/테일넷용 액세스하고, 명시적으로 바인딩하고, 인증을 활성화한 상태로 유지하세요.

tailnet 전용 설정의 경우:

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

광고하는 것

게이트웨이만 _openclaw-gw._tcp를 알립니다.

서비스 유형

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

TXT 키(비밀 힌트가 아님)

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

• role=gateway
• displayName=<friendly name>
• lanHost=<hostname>.local
• gatewayPort=<port> (게이트웨이 WS + HTTP)
• gatewayTls=1 (TLS가 활성화된 경우에만)
• gatewayTlsSha256=<sha256> (TLS가 활성화되고 지문이 사용 가능한 경우에만)
• canvasPort=<port> (캔버스 호스트가 활성화된 경우에만, 기본값 18793)
• sshPort=<port> (재정의되지 않은 경우 기본값은 22)
• transport=gateway
• cliPath=<path> (선택 사항, 실행 가능한 openclaw 진입점에 대한 절대 경로)
• tailnetDns=<magicdns> (Tailnet을 사용할 수 있는 경우 선택적 힌트)

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를 검색합니다.

로그를 캡처하려면 다음을 수행하십시오.

• 설정 → 게이트웨이 → 고급 → 검색 디버그 로그
• 설정 → 게이트웨이 → 고급 → 검색 로그 → 재현 → 복사

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

일반적인 실패 모드

• 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)를 재정의합니다.

관련 문서

• 발견 정책 및 전송 선택: Discovery
• 노드 페어링 + 승인: 게이트웨이 페어링