> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openclaw.kr/llms.txt
> Use this file to discover all available pages before exploring further.

# 검색 및 전송 프로토콜

# 검색 및 전송 프로토콜

OpenClaw에는 표면적으로는 유사해 보이는 두 가지 뚜렷한 문제가 있습니다:

1. **운영자 원격 제어**: 다른 곳에서 실행 중인 게이트웨이를 제어하는 macOS 메뉴 바 앱.
2. **노드 페어링**: iOS/Android(및 향후 노드들)가 게이트웨이를 찾아 안전하게 페어링하기.

설계 목표는 모든 네트워크 검색/광고를 **노드 게이트웨이**(`openclaw gateway`)에 집중하고 클라이언트(mac 앱, iOS)는 소비자 역할만 하도록 유지하는 것입니다.

## 용어

* **Gateway (게이트웨이)**: 상태(세션, 페어링, 노드 레지스트리)를 소유하고 채널을 실행하는 단일 장기 실행 게이트웨이 프로세스. 대부분의 설정에서는 호스트당 하나를 사용하며, 격리된 다중 게이트웨이 설정도 가능합니다.
* **Gateway WS (제어 플레인)**: 기본적으로 `127.0.0.1:18789`의 WebSocket 엔드포인트; `gateway.bind`를 통해 LAN/tailnet에 바인딩할 수 있습니다.
* **직접 WS 전송**: LAN/tailnet을 향하는 게이트웨이 WS 엔드포인트 (SSH 없음).
* **SSH 전송 (대체)**: `127.0.0.1:18789`를 SSH로 포워딩하여 원격 제어.
* **레거시 TCP 브리지 (사용 중단/제거됨)**: 이전 노드 전송 방식 ([브리지 프로토콜](/ko-KR/gateway/bridge-protocol) 참조); 더 이상 검색에 광고되지 않습니다.

프로토콜 세부 사항:

* [게이트웨이 프로토콜](/ko-KR/gateway/protocol)
* [브리지 프로토콜 (레거시)](/ko-KR/gateway/bridge-protocol)

## 직접 연결과 SSH를 모두 유지하는 이유

* **직접 WS**는 동일 네트워크 및 tailnet 내에서 최고의 사용자 경험을 제공합니다:
  * Bonjour를 통한 LAN 자동 검색
  * 게이트웨이가 소유하는 페어링 토큰 + ACL
  * 셸 접근 불필요; 프로토콜 표면을 엄격하고 감사 가능하게 유지 가능
* **SSH**는 보편적인 대체 수단으로 유지됩니다:
  * SSH 접근이 가능한 어디서나 작동 (관련 없는 네트워크에서도)
  * 멀티캐스트/mDNS 문제를 우회할 수 있음
  * SSH 외에 새로운 인바운드 포트 불필요

## 검색 입력 (클라이언트가 게이트웨이 위치를 파악하는 방법)

### 1) Bonjour / mDNS (LAN 전용)

Bonjour는 최선을 다하지만 네트워크를 넘어가지 않습니다. "동일 LAN" 편의를 위해서만 사용됩니다.

대상 방향:

* **게이트웨이**는 Bonjour를 통해 WS 엔드포인트를 광고합니다.
* 클라이언트는 탐색하여 "게이트웨이 선택" 목록을 표시하고, 선택한 엔드포인트를 저장합니다.

문제 해결 및 비콘 세부 사항: [Bonjour](/ko-KR/gateway/bonjour).

#### 서비스 비콘 세부 사항

* 서비스 유형:
  * `_openclaw-gw._tcp` (게이트웨이 전송 비콘)
* TXT 키 (비밀 아님):
  * `role=gateway`
  * `lanHost=<hostname>.local`
  * `sshPort=22` (광고된 값)
  * `gatewayPort=18789` (게이트웨이 WS + HTTP)
  * `gatewayTls=1` (TLS가 활성화된 경우에만)
  * `gatewayTlsSha256=<sha256>` (TLS가 활성화되고 지문이 사용 가능한 경우에만)
  * `canvasPort=<port>` (캔버스 호스트 포트; 현재 캔버스 호스트가 활성화된 경우 `gatewayPort`와 동일)
  * `cliPath=<path>` (선택; 실행 가능한 `openclaw` 진입점 또는 바이너리의 절대 경로)
  * `tailnetDns=<magicdns>` (선택적 힌트; Tailscale 사용 시 자동 감지됨)

보안 주의사항:

* Bonjour/mDNS TXT 레코드는 **인증되지 않습니다**. 클라이언트는 TXT 값을 UX 힌트로만 처리해야 합니다.
* 라우팅(호스트/포트)은 TXT로 제공된 `lanHost`, `tailnetDns`, 또는 `gatewayPort`보다 **해결된 서비스 엔드포인트**(SRV + A/AAAA)를 우선해야 합니다.
* TLS 피닝(pinning)은 이전에 저장된 핀을 광고된 `gatewayTlsSha256`이 덮어쓰지 않도록 해야 합니다.
* iOS/Android 노드는 검색 기반 직접 연결을 **TLS 전용**으로 처리하고, 첫 번째 핀 저장 전에 명시적인 "이 지문 신뢰" 확인이 필요합니다 (대역 외 검증).

비활성화/재정의:

* `OPENCLAW_DISABLE_BONJOUR=1`은 광고를 비활성화합니다.
* `~/.openclaw/openclaw.json`의 `gateway.bind`는 게이트웨이 바인드 모드를 제어합니다.
* `OPENCLAW_SSH_PORT`는 TXT에서 광고하는 SSH 포트를 재정의합니다 (기본값: 22).
* `OPENCLAW_TAILNET_DNS`는 `tailnetDns` 힌트(MagicDNS)를 게시합니다.
* `OPENCLAW_CLI_PATH`는 광고된 CLI 경로를 재정의합니다.

### 2) Tailnet (크로스 네트워크)

런던/비엔나 스타일 설정처럼 서로 다른 네트워크에서는 Bonjour가 도움이 되지 않습니다. 권장하는 "직접" 대상은:

* Tailscale MagicDNS 이름(권장) 또는 안정적인 tailnet IP입니다.

게이트웨이가 Tailscale 환경에서 실행 중임을 감지할 수 있다면, 클라이언트에 대한 선택적 힌트로 `tailnetDns`를 게시합니다 (광역 비콘 포함).

### 3) 수동 / SSH 대상

직접 경로가 없거나 비활성화된 경우, 클라이언트는 루프백 게이트웨이 포트를 SSH로 포워딩하여 항상 연결할 수 있습니다.

[원격 접근](/ko-KR/gateway/remote)을 참조하세요.

## 전송 선택 (클라이언트 정책)

권장 클라이언트 동작:

1. 페어링된 직접 엔드포인트가 설정되어 있고 도달 가능하면 사용합니다.
2. 그렇지 않으면, Bonjour가 LAN에서 게이트웨이를 발견하면 "이 게이트웨이 사용" 선택지를 제공하고 직접 엔드포인트로 저장하세요.
3. 그렇지 않으면, tailnet DNS/IP가 설정되어 있으면 직접 연결을 시도하세요.
4. 그렇지 않으면, SSH로 대체합니다.

## 페어링 + 인증 (직접 전송)

게이트웨이는 노드/클라이언트 허가에 대한 단일 진실 원천(source of truth)입니다.

* 페어링 요청은 게이트웨이에서 생성/승인/거부됩니다 ([게이트웨이 페어링](/ko-KR/gateway/pairing) 참조).
* 게이트웨이는 다음을 강제합니다:
  * 인증 (토큰 / 키페어)
  * 범위/ACL (게이트웨이는 모든 메서드에 대한 원시 프록시가 아닙니다)
  * 속도 제한

## 구성 요소별 책임

* **게이트웨이**: 검색 비콘을 광고하고, 페어링 결정을 소유하며, WS 엔드포인트를 호스팅합니다.
* **macOS 앱**: 게이트웨이를 선택하도록 돕고, 페어링 프롬프트를 표시하며, SSH는 대체 수단으로만 사용합니다.
* **iOS/Android 노드**: 편의를 위해 Bonjour를 탐색하고, 페어링된 게이트웨이 WS에 연결합니다.