Tailscale

기준일: 2026-07-26
공식 기준: Tailscale

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

핵심 요약

Integrated Tailscale Serve/Funnel for the Gateway dashboard

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

문서 구성

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

• Modes
• Config examples
• Tailnet-only (Serve)
• Tailnet-only (bind to Tailnet IP)
• Public internet (Funnel + shared password)
• CLI examples
• Auth
• Tailscale identity headers (Serve only)
• 참고
• Tailscale prerequisites and limits
• Browser control (remote Gateway + local browser)
• Learn more
• 관련 문서

상세 내용

본문

OpenClaw can auto-configure Tailscale Serve (tailnet) or Funnel (public) for the Gateway dashboard and WebSocket port. This keeps the gateway bound to loopback while Tailscale provides HTTPS, routing, and (for Serve) identity headers.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Modes

Status and audit output use Tailscale exposure for this OpenClaw Serve/Funnel mode. off means OpenClaw is not managing Serve or Funnel; it does not mean the local Tailscale daemon is stopped or logged out.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Mode	Behavior
serve	Tailnet-only Serve via tailscale serve. The gateway stays on 127.0.0.1.
funnel	Public HTTPS via tailscale funnel. Requires a shared password.
off (default)	No Tailscale automation.

Config examples

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

Tailnet-only (Serve)

Open: https:/// (or your configured gateway.controlUi.basePath)

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

{
  gateway: {
    bind: "loopback",
    tailscale: { mode: "serve" },
  },
}

{
  gateway: {
    bind: "loopback",
    tailscale: { mode: "serve", serviceName: "svc:openclaw" },
  },
}

Tailnet-only (bind to Tailnet IP)

Use this to have the gateway listen directly on the Tailnet IP, with no Serve/Funnel:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Control UI: http://<tailscale-ip>:18789/
• WebSocket: ws://<tailscale-ip>:18789

{
  gateway: {
    bind: "tailnet",
    auth: { mode: "token", token: "your-token" },
  },
}

Public internet (Funnel + shared password)

Prefer OPENCLAW_GATEWAY_PASSWORD over committing a password to disk.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

{
  gateway: {
    bind: "loopback",
    tailscale: { mode: "funnel" },
    auth: { mode: "password", password: "replace-me" },
  },
}

CLI examples

openclaw gateway --tailscale serve
openclaw gateway --tailscale funnel --auth password

Auth

gateway.auth.mode controls the handshake:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Mode	Use case
none	Private ingress only
token (default when OPENCLAW_GATEWAY_TOKEN is set)	Shared token
password	Shared secret via OPENCLAW_GATEWAY_PASSWORD or config
trusted-proxy	Identity-aware reverse proxy; see Trusted Proxy Auth

Tailscale identity headers (Serve only)

When tailscale.mode: "serve" and gateway.auth.allowTailscale is true, Control UI/WebSocket auth can use Tailscale identity headers (tailscale-user-login) instead of a token/password. OpenClaw verifies the header by resolving the request's x-forwarded-for address via the local Tailscale daemon (tailscale whois) and matching it to the header login before accepting it. A request only qualifies for this path when it arrives from loopback carrying Tailscale's x-forwarded-for, x-forwarded-proto, and x-forwarded-host headers.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Applies only to the Control UI WebSocket auth surface. HTTP API endpoints (/v1/*, /tools/invoke, /api/channels/*, etc.) never use Tailscale identity-header auth; they always follow the gateway's normal HTTP auth mode.
• For Control UI operator sessions that already carry browser device identity, a verified Tailscale identity skips the bootstrap-token/QR pairing round trip.
• It does not bypass device identity itself: device-less clients are still rejected, and node-role connections still go through normal pairing and auth checks.

참고

주요 항목:

• Tailscale Serve/Funnel requires the tailscale CLI installed and logged in.
• tailscale.mode: "funnel" refuses to start unless auth mode is password, to avoid public exposure.
• gateway.tailscale.serviceName applies only to Serve mode and is passed to tailscale serve --service=<name>. The value must use Tailscale's svc:<dns-label> format, for example svc:openclaw. Tailscale requires Service hosts to be tagged nodes, and the Service may need admin-console approval before Serve can publish it.
• gateway.tailscale.resetOnExit undoes tailscale serve/tailscale funnel configuration on shutdown.
• gateway.tailscale.preserveFunnel: true keeps an externally configured tailscale funnel route alive across gateway restarts. With mode: "serve", OpenClaw checks tailscale funnel status before re-applying Serve and skips it when a Funnel route already covers the gateway port. The OpenClaw-managed Funnel password-only policy is unchanged.
• gateway.bind: "tailnet" uses a direct Tailnet bind (no HTTPS, no Serve/Funnel) plus required local 127.0.0.1 when a Tailnet IPv4 is available; otherwise it falls back to loopback only.
• gateway.bind: "auto" prefers loopback; use tailnet to limit network exposure to the Tailnet while retaining same-host loopback access.
• Serve/Funnel only expose the Gateway control UI + WS. Nodes connect over the same Gateway WS endpoint, so Serve works for node access too.

Tailscale prerequisites and limits

주요 항목:

• Serve requires HTTPS enabled for your tailnet; the CLI prompts if it is missing.
• Serve injects Tailscale identity headers; Funnel does not.
• Funnel requires Tailscale v1.38.3+, MagicDNS, HTTPS enabled, and a funnel node attribute.
• Funnel only supports ports 443, 8443, and 10000 over TLS.
• Funnel on macOS requires the open-source Tailscale app variant.

Browser control (remote Gateway + local browser)

To run the Gateway on one machine but drive a browser on another, run a node host on the browser machine and keep both on the same tailnet. The Gateway proxies browser actions to the node; no separate control server or Serve URL is needed.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Learn more

주요 항목:

• Tailscale Serve overview: https://tailscale.com/kb/1312/serve
• tailscale serve command: https://tailscale.com/kb/1242/tailscale-serve
• Tailscale Funnel overview: https://tailscale.com/kb/1223/tailscale-funnel
• tailscale funnel command: https://tailscale.com/kb/1311/tailscale-funnel

관련 문서

주요 항목:

• Remote access
• Discovery
• Authentication

실습 체크리스트

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

자주 쓰는 명령·설정 예시

{
  gateway: {
    bind: "loopback",
    tailscale: { mode: "serve" },
  },
}

{
  gateway: {
    bind: "loopback",
    tailscale: { mode: "serve", serviceName: "svc:openclaw" },
  },
}

{
  gateway: {
    bind: "tailnet",
    auth: { mode: "token", token: "your-token" },
  },
}

{
  gateway: {
    bind: "loopback",
    tailscale: { mode: "funnel" },
    auth: { mode: "password", password: "replace-me" },
  },
}

openclaw gateway --tailscale serve
openclaw gateway --tailscale funnel --auth password

관련 링크

• 공식 원문: gateway/tailscale
• OpenClaw 문서 홈

이 가이드는 공식 문서를 한국어 학습용으로 재구성한 것입니다. 옵션 기본값·플래그 이름은 설치 버전에 따라 달라질 수 있습니다.