고급4분 소요openclawgatewaydiscovery

Discovery and transports

Discovery and transports 문서는 OpenClaw 공식 문서(gateway/discovery)를 한국어로 정리한 가이드입니다. Node discovery and transports (Bonjour, Tailscale, SSH) for finding the gateway 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Node discovery and transports (Bonjour, Tailscale, SSH) for finding the gateway

한국어 가이드 범위: gateway/discovery 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Terms
Why direct and SSH both exist
Discovery inputs
1) Bonjour / DNS-SD
2) Tailnet (cross-network)
3) Manual / SSH target
Transport selection (client policy)
Pairing and auth (direct transport)
Responsibilities by component
관련 문서

상세 내용

본문

OpenClaw has two related but distinct discovery problems:

Terms

pairing, node registry) and runs channels. Most setups use one per host; isolated multi-gateway setups are possible.

주요 항목:

Gateway: a single long-running process that owns state (sessions,
Gateway WS (control plane): the WebSocket endpoint on 127.0.0.1:18789
Direct WS transport: a LAN/tailnet-facing Gateway WS endpoint (no SSH).
SSH transport (fallback): remote control by forwarding
Legacy TCP bridge (removed): older node transport (see

Why direct and SSH both exist

auto-discovery via Bonjour, pairing tokens and ACLs owned by the gateway, and no shell access required.

주요 항목:

Direct WS is the best UX on the same network and within a tailnet: LAN
SSH is the universal fallback: works anywhere you have SSH access, even

Discovery inputs

이 섹션의 세부 항목은 공식 문서 Discovery inputs를 참고하세요.

1) Bonjour / DNS-SD

Multicast Bonjour is best-effort and does not cross networks. OpenClaw also supports browsing the same gateway beacon via a configured wide-area DNS-SD domain, so discovery can cover both local. on the same LAN and a configured unicast DNS-SD domain for cross-network discovery.

주요 항목:

Service type: _openclaw-gw._tcp (gateway transport beacon).
TXT keys (non-secret):
Bonjour/mDNS TXT records are unauthenticated. Clients must treat TXT
Routing (host/port) should prefer the resolved service endpoint
TLS pinning must never let an advertised gatewayTlsSha256 override a
iOS/Android nodes should require an explicit "trust this fingerprint"
openclaw plugins enable bonjour enables LAN multicast advertising.
discovery.mdns.mode in openclaw.json controls mDNS broadcast:
OPENCLAW_DISABLE_BONJOUR=1 force-disables advertising; discovery.mdns.mode="off"
gateway.bind in ~/.openclaw/openclaw.json controls the Gateway bind mode.
OPENCLAW_SSH_PORT overrides the advertised SSH port (only takes effect
OPENCLAW_TAILNET_DNS publishes a tailnetDns hint (MagicDNS).
OPENCLAW_CLI_PATH overrides the advertised CLI path.

2) Tailnet (cross-network)

For gateways on different physical networks, Bonjour will not help. The recommended direct target is a Tailscale MagicDNS name (preferred) or a stable tailnet IP.

주요 항목:

iOS/Android still require a secure first-time tailnet/public connect path
A discovered raw tailnet IP is a routing hint, not permission to use
Private LAN direct-connect ws:// remains supported.
For the simplest Tailscale path on mobile nodes, use Tailscale Serve so

3) Manual / SSH target

When there is no direct route (or direct is disabled), clients can always connect via SSH by forwarding the loopback gateway port. See Remote access.

Transport selection (client policy)

If a paired direct endpoint is configured and reachable, use it. 2. Else, if discovery finds a gateway on local. or the configured wide-area domain, offer a one-tap "Use this gateway" choice and save it as the direct endpoint. 3. Else, if a tailnet DNS/IP is configured, try direct. For mobile nodes on tailnet/public routes, direct means a secure endpoint, not plaintext remote ws://. 4. Else, fall back to SSH.

Pairing and auth (direct transport)

The gateway is the source of truth for node/client admission:

주요 항목:

Pairing requests are created/approved/rejected in the gateway (see
The gateway enforces auth (token/keypair), scopes/ACLs (it is not a raw

Responsibilities by component

주요 항목:

Gateway: advertises discovery beacons, owns pairing decisions, hosts
macOS app: helps you pick a gateway, shows pairing prompts, uses SSH
iOS/Android nodes: browse Bonjour as a convenience, connect to the

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/gateway/discovery
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

Discovery and transports

핵심 요약

Node discovery and transports (Bonjour, Tailscale, SSH) for finding the gateway

한국어 가이드 범위: gateway/discovery 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Terms
Why direct and SSH both exist
Discovery inputs
1) Bonjour / DNS-SD
2) Tailnet (cross-network)
3) Manual / SSH target
Transport selection (client policy)
Pairing and auth (direct transport)
Responsibilities by component
관련 문서

상세 내용

본문

OpenClaw has two related but distinct discovery problems:

Terms

pairing, node registry) and runs channels. Most setups use one per host; isolated multi-gateway setups are possible.

주요 항목:

Gateway: a single long-running process that owns state (sessions,
Gateway WS (control plane): the WebSocket endpoint on 127.0.0.1:18789
Direct WS transport: a LAN/tailnet-facing Gateway WS endpoint (no SSH).
SSH transport (fallback): remote control by forwarding
Legacy TCP bridge (removed): older node transport (see

Why direct and SSH both exist

auto-discovery via Bonjour, pairing tokens and ACLs owned by the gateway, and no shell access required.

주요 항목:

Direct WS is the best UX on the same network and within a tailnet: LAN
SSH is the universal fallback: works anywhere you have SSH access, even

Discovery inputs

이 섹션의 세부 항목은 공식 문서 Discovery inputs를 참고하세요.

1) Bonjour / DNS-SD

주요 항목:

Service type: _openclaw-gw._tcp (gateway transport beacon).
TXT keys (non-secret):
Bonjour/mDNS TXT records are unauthenticated. Clients must treat TXT
Routing (host/port) should prefer the resolved service endpoint
TLS pinning must never let an advertised gatewayTlsSha256 override a
iOS/Android nodes should require an explicit "trust this fingerprint"
openclaw plugins enable bonjour enables LAN multicast advertising.
discovery.mdns.mode in openclaw.json controls mDNS broadcast:
OPENCLAW_DISABLE_BONJOUR=1 force-disables advertising; discovery.mdns.mode="off"
gateway.bind in ~/.openclaw/openclaw.json controls the Gateway bind mode.
OPENCLAW_SSH_PORT overrides the advertised SSH port (only takes effect
OPENCLAW_TAILNET_DNS publishes a tailnetDns hint (MagicDNS).
OPENCLAW_CLI_PATH overrides the advertised CLI path.

2) Tailnet (cross-network)

For gateways on different physical networks, Bonjour will not help. The recommended direct target is a Tailscale MagicDNS name (preferred) or a stable tailnet IP.

주요 항목:

iOS/Android still require a secure first-time tailnet/public connect path
A discovered raw tailnet IP is a routing hint, not permission to use
Private LAN direct-connect ws:// remains supported.
For the simplest Tailscale path on mobile nodes, use Tailscale Serve so

3) Manual / SSH target

When there is no direct route (or direct is disabled), clients can always connect via SSH by forwarding the loopback gateway port. See Remote access.

Transport selection (client policy)

If a paired direct endpoint is configured and reachable, use it. 2. Else, if discovery finds a gateway on local. or the configured wide-area domain, offer a one-tap "Use this gateway" choice and save it as the direct endpoint. 3. Else, if a tailnet DNS/IP is configured, try direct. For mobile nodes on tailnet/public routes, direct means a secure endpoint, not plaintext remote ws://. 4. Else, fall back to SSH.

Pairing and auth (direct transport)

The gateway is the source of truth for node/client admission:

주요 항목:

Pairing requests are created/approved/rejected in the gateway (see
The gateway enforces auth (token/keypair), scopes/ACLs (it is not a raw

Responsibilities by component

주요 항목:

Gateway: advertises discovery beacons, owns pairing decisions, hosts
macOS app: helps you pick a gateway, shows pairing prompts, uses SSH
iOS/Android nodes: browse Bonjour as a convenience, connect to the

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/gateway/discovery
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

Discovery and transports

핵심 요약

문서 구성

상세 내용

본문

Terms

Why direct and SSH both exist

Discovery inputs

1) Bonjour / DNS-SD

2) Tailnet (cross-network)

3) Manual / SSH target

Transport selection (client policy)

Pairing and auth (direct transport)

Responsibilities by component

관련 문서

실습 체크리스트

관련 링크

관련 가이드

Discovery and transports

핵심 요약

문서 구성

상세 내용

본문

Terms

Why direct and SSH both exist

Discovery inputs

1) Bonjour / DNS-SD

2) Tailnet (cross-network)

3) Manual / SSH target

Transport selection (client policy)

Pairing and auth (direct transport)

Responsibilities by component

관련 문서

실습 체크리스트

관련 링크

관련 가이드