English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisहिन्दीالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiРусскийفارسیไทย
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in PerplexityAsk questions about this page

Remote access

Tailscale

OpenClaw는 Gateway 대시보드와 WebSocket 포트에 대해 Tailscale Serve(tailnet) 또는 Funnel(공개)을 자동 구성할 수 있습니다. 이렇게 하면 Gateway는 loopback에 바인딩된 상태를 유지하면서 Tailscale이 HTTPS, 라우팅, 그리고 (Serve의 경우) ID 헤더를 제공합니다.

모드

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

상태 및 감사 출력은 이 OpenClaw Serve/Funnel 모드에 대해 Tailscale 노출을 사용합니다. off는 OpenClaw가 Serve 또는 Funnel을 관리하지 않는다는 뜻이며, local Tailscale 데몬이 중지되었거나 로그아웃되었다는 뜻은 아닙니다.

인증

핸드셰이크를 제어하려면 gateway.auth.mode를 설정하세요.

  • none(비공개 인그레스 전용)
  • token(OPENCLAW_GATEWAY_TOKEN이 설정된 경우 기본값)
  • password(OPENCLAW_GATEWAY_PASSWORD 또는 설정을 통한 공유 비밀)
  • trusted-proxy(ID 인식 리버스 프록시; 신뢰할 수 있는 프록시 인증 참조)

tailscale.mode = "serve"이고 gateway.auth.allowTailscale이 true이면 Control UI/WebSocket 인증은 토큰/비밀번호를 제공하지 않고 Tailscale ID 헤더(tailscale-user-login)를 사용할 수 있습니다. OpenClaw는 local Tailscale 데몬(tailscale whois)을 통해 x-forwarded-for 주소를 확인하고, 이를 헤더와 일치시킨 뒤 ID를 검증합니다. OpenClaw는 요청이 loopback에서 들어오고 Tailscale의 x-forwarded-for, x-forwarded-proto, x-forwarded-host 헤더가 있을 때만 해당 요청을 Serve로 취급합니다. 브라우저 장치 ID를 포함하는 Control UI 운영자 세션의 경우, 이 검증된 Serve 경로는 장치 페어링 왕복도 건너뜁니다. 브라우저 장치 ID를 우회하지는 않습니다. 장치가 없는 클라이언트는 여전히 거부되며, 노드 역할 또는 Control UI가 아닌 WebSocket 연결은 계속 일반 페어링 및 인증 검사를 따릅니다. HTTP API 엔드포인트(예: /v1/*, /tools/invoke, /api/channels/*)는 Tailscale ID 헤더 인증을 사용하지 않습니다. 이들은 계속 Gateway의 일반 HTTP 인증 모드를 따릅니다. 기본적으로 공유 비밀 인증을 사용하거나, 의도적으로 구성한 trusted-proxy / 비공개 인그레스 none 설정을 사용합니다. 이 토큰 없는 흐름은 Gateway 호스트를 신뢰할 수 있다고 가정합니다. 신뢰할 수 없는 local 코드가 같은 호스트에서 실행될 수 있다면 gateway.auth.allowTailscale을 비활성화하고 대신 토큰/비밀번호 인증을 요구하세요. 명시적인 공유 비밀 자격 증명을 요구하려면 gateway.auth.allowTailscale: false를 설정하고 gateway.auth.mode: "token" 또는 "password"를 사용하세요.

설정 예시

Tailnet 전용(Serve)

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

열기: https://<magicdns>/(또는 구성한 gateway.controlUi.basePath)

장치 호스트 이름 대신 이름이 지정된 Tailscale Service를 통해 Control UI를 노출하려면 gateway.tailscale.serviceName을 Service 이름으로 설정하세요.

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

위 예시를 사용하면 시작 시 Service URL이 장치 호스트 이름 대신 https://openclaw.<tailnet-name>.ts.net/로 보고됩니다. Tailscale Services를 사용하려면 호스트가 tailnet에서 승인된 태그 지정 노드여야 합니다. 이 옵션을 활성화하기 전에 Tailscale에서 태그를 구성하고 Service를 승인하세요. 그렇지 않으면 Gateway 시작 중 tailscale serve --service=...가 실패합니다.

Tailnet 전용(Tailnet IP에 바인딩)

Gateway가 Tailnet IP에서 직접 수신 대기하도록 하려면 이 모드를 사용하세요(Serve/Funnel 없음).

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

다른 Tailnet 장치에서 연결:

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

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

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

비밀번호를 디스크에 커밋하는 것보다 OPENCLAW_GATEWAY_PASSWORD를 사용하는 것을 권장합니다.

CLI 예시

bash
openclaw gateway --tailscale serveopenclaw gateway --tailscale funnel --auth password

참고

  • Tailscale Serve/Funnel을 사용하려면 tailscale CLI가 설치되어 있고 로그인되어 있어야 합니다.
  • tailscale.mode: "funnel"은 공개 노출을 피하기 위해 인증 모드가 password가 아니면 시작을 거부합니다.
  • gateway.tailscale.serviceName은 Serve 모드에만 적용되며 tailscale serve --service=<name>에 전달됩니다. 값은 Tailscale의 svc:<dns-label> Service 이름 형식을 사용해야 합니다. 예: svc:openclaw. Tailscale은 Service 호스트가 태그 지정 노드일 것을 요구하며, Serve가 이를 게시하기 전에 관리자 콘솔에서 Service 승인이 필요할 수 있습니다.
  • 종료 시 OpenClaw가 tailscale serve 또는 tailscale funnel 구성을 되돌리게 하려면 gateway.tailscale.resetOnExit를 설정하세요.
  • 외부에서 구성한 tailscale funnel 경로를 Gateway 재시작 사이에도 유지하려면 gateway.tailscale.preserveFunnel: true를 설정하세요. 활성화되어 있고 Gateway가 mode: "serve"로 실행되는 경우, OpenClaw는 Serve를 다시 적용하기 전에 tailscale funnel status를 확인하고 Funnel 경로가 이미 Gateway 포트를 포함하면 이를 건너뜁니다. OpenClaw가 관리하는 Funnel의 비밀번호 전용 정책은 변경되지 않습니다.
  • gateway.bind: "tailnet"은 직접 Tailnet 바인딩입니다(HTTPS 없음, Serve/Funnel 없음).
  • gateway.bind: "auto"는 loopback을 우선합니다. Tailnet 전용을 원하면 tailnet을 사용하세요.
  • Serve/Funnel은 Gateway 제어 UI + WS만 노출합니다. 노드는 동일한 Gateway WS 엔드포인트를 통해 연결하므로, Serve는 노드 접근에도 사용할 수 있습니다.

브라우저 제어(원격 Gateway + local 브라우저)

한 머신에서 Gateway를 실행하지만 다른 머신의 브라우저를 구동하려면, 브라우저 머신에서 노드 호스트를 실행하고 둘 다 같은 tailnet에 두세요. Gateway가 브라우저 작업을 노드로 프록시합니다. 별도의 제어 서버나 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 앱 변형이 필요합니다.

자세히 알아보기

관련 항목

Was this useful?
On this page

On this page