메인 콘텐츠로 건너뛰기

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

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

​
모드

  • 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 신원 헤더(tailscale-user-login)를 사용할 수 있습니다. OpenClaw는 로컬 Tailscale 데몬(tailscale whois)을 통해 x-forwarded-for 주소를 조회하고 이를 헤더와 대조하여 신원을 검증한 후 요청을 수락합니다. 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 장치에서 연결:
  • 제어 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 신원 헤더를 주입합니다; Funnel은 그렇지 않습니다.
  • Funnel은 Tailscale v1.38.3+, MagicDNS, HTTPS 활성화 및 funnel 노드 속성이 필요합니다.
  • Funnel은 TLS를 통해 포트 443, 8443, 10000만 지원합니다.
  • macOS에서의 Funnel은 오픈소스 Tailscale 앱 변형이 필요합니다.

​
자세히 알아보기