Tailscale (게이트웨이 대시보드)

OpenClaw는 게이트웨이 대시보드 및 WebSocket 포트에 대해 Tailscale Serve (Tailnet) 또는 Funnel (공개)을 자동으로 설정할 수 있습니다. 게이트웨이는 루프백에 바인딩된 상태를 유지하면서 Tailscale이 HTTPS, 라우팅, (Serve의 경우) ID 헤더를 제공합니다.

모드

  • serve: tailscale serve를 통한 Tailnet 전용 Serve. 게이트웨이는 127.0.0.1에 유지됩니다.
  • funnel: tailscale funnel을 통한 공개 HTTPS. OpenClaw는 공유 비밀번호를 요구합니다.
  • off: 기본값 (Tailscale 자동화 없음).

인증

gateway.auth.mode로 핸드셰이크를 제어합니다:

  • token (OPENCLAW_GATEWAY_TOKEN 설정 시 기본값)
  • password (OPENCLAW_GATEWAY_PASSWORD 또는 설정을 통한 공유 비밀)

tailscale.mode = "serve"이고 gateway.auth.allowTailscale이 true이면, Control UI/WebSocket 인증에서 토큰/비밀번호 없이 Tailscale ID 헤더(tailscale-user-login)를 사용할 수 있습니다. OpenClaw는 x-forwarded-for 주소를 로컬 Tailscale 데몬(tailscale whois)을 통해 확인하고 헤더와 매칭하여 ID를 검증합니다. OpenClaw는 Tailscale의 x-forwarded-for, x-forwarded-proto, x-forwarded-host 헤더와 함께 루프백에서 도착한 요청만 Serve로 취급합니다. HTTP API 엔드포인트(예: /v1/*, /tools/invoke, /api/channels/*)는 여전히 토큰/비밀번호 인증이 필요합니다. 이 토큰 없는 흐름은 게이트웨이 호스트를 신뢰한다고 가정합니다. 동일 호스트에서 신뢰할 수 없는 로컬 코드가 실행될 수 있으면, gateway.auth.allowTailscale을 비활성화하고 토큰/비밀번호 인증을 요구하세요. 명시적 인증 정보를 요구하려면, gateway.auth.allowTailscale: false로 설정하거나 gateway.auth.mode: "password"를 강제하세요.

설정 예시

Tailnet 전용 (Serve)

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

열기: https://<magicdns>/ (또는 설정된 gateway.controlUi.basePath)

Tailnet 전용 (Tailnet IP에 직접 바인딩)

게이트웨이가 Tailnet IP에서 직접 수신하게 하려면 (Serve/Funnel 없이) 사용합니다.

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

다른 Tailnet 디바이스에서 연결:

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

참고: 이 모드에서는 루프백(http://127.0.0.1:18789)이 작동하지 않습니다.

공개 인터넷 (Funnel + 공유 비밀번호)

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

디스크에 비밀번호를 커밋하는 것보다 OPENCLAW_GATEWAY_PASSWORD를 선호하세요.

CLI 예시

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

참고

  • Tailscale Serve/Funnel은 tailscale CLI가 설치되어 있고 로그인 상태여야 합니다.
  • tailscale.mode: "funnel"은 공개 노출을 방지하기 위해 인증 모드가 password가 아니면 시작을 거부합니다.
  • OpenClaw가 종료 시 tailscale serve 또는 tailscale funnel 설정을 취소하게 하려면 gateway.tailscale.resetOnExit을 설정하세요.
  • gateway.bind: "tailnet"은 직접 Tailnet 바인딩입니다 (HTTPS 없음, Serve/Funnel 없음).
  • gateway.bind: "auto"는 루프백을 선호합니다. Tailnet 전용이 필요하면 tailnet을 사용하세요.
  • Serve/Funnel은 게이트웨이 제어 UI + WS만 노출합니다. 노드는 동일한 게이트웨이 WS 엔드포인트를 통해 연결되므로, Serve가 노드 접근에도 작동할 수 있습니다.

브라우저 제어 (원격 게이트웨이 + 로컬 브라우저)

게이트웨이를 한 머신에서 실행하지만 다른 머신에서 브라우저를 제어하고 싶다면, 브라우저 머신에서 노드 호스트를 실행하고 동일한 Tailnet에 연결하세요. 게이트웨이가 브라우저 작업을 노드에 프록시합니다. 별도의 제어 서버나 Serve URL은 필요 없습니다.

브라우저 제어에 Funnel 사용을 피하세요. 노드 페어링을 운영자 접근과 동일하게 취급하세요.

Tailscale 사전 요구사항 + 제한

  • Serve는 Tailnet에 HTTPS가 활성화되어 있어야 합니다. 누락된 경우 CLI가 안내합니다.
  • Serve는 Tailscale ID 헤더를 삽입합니다. Funnel은 삽입하지 않습니다.
  • Funnel은 Tailscale v1.38.3+, MagicDNS, HTTPS 활성화, funnel 노드 속성이 필요합니다.
  • Funnel은 TLS를 통해 포트 443, 8443, 10000만 지원합니다.
  • macOS에서 Funnel은 오픈소스 Tailscale 앱 변형이 필요합니다.

더 알아보기

arrow_back
이전
Remote Gateway Readme
다음
Formal Verification
arrow_forward