OpenClaw Gateway와 Tailscale 연결하기

로컬에서 실행 중인 대시보드나 API를 외부에서 안전하게 접속하고 싶을 때가 많아요. 하지만 방화벽을 설정하고, SSL 인증서를 직접 관리하고, 공개 IP를 노출하는 과정은 늘 번거롭고 보안 걱정도 따르죠. 특히 원격에 있는 기기에서 브라우저를 제어해야 하거나 팀원들과 대시보드를 공유해야 할 때, 복잡한 네트워크 설정 때문에 시간을 허비하곤 해요.

OpenClaw는 Tailscale과 연동하여 이런 문제를 간단히 해결해 줘요. 복잡한 설정 없이도 HTTPS와 안전한 라우팅을 바로 적용할 수 있습니다.

What You’ll Need

시작하기 전에 다음 조건이 갖춰졌는지 확인하세요.

tailscale CLI가 설치되어 있고 로그인된 상태여야 해요.
Serve 기능을 쓰려면 Tailnet에 HTTPS가 활성화되어 있어야 합니다.
Funnel 기능을 쓰려면 Tailscale v1.38.3 이상, MagicDNS 사용, HTTPS 활성화, Funnel 노드 속성 설정이 필요해요.
macOS에서 Funnel을 사용한다면 오픈 소스 버전의 Tailscale 앱을 사용해야 합니다.

Quick Start

5분 안에 설정을 마치는 가장 빠른 방법이에요.

1. CLI로 실행하기

가장 간단하게 Tailscale Serve나 Funnel을 활성화할 수 있어요.

# Tailnet 내부에서만 접근할 때 (Serve)
openclaw gateway --tailscale serve

# 외부 인터넷에 공개할 때 (Funnel)
openclaw gateway --tailscale funnel --auth password

2. 설정 파일(JSON5) 사용하기

설정 파일에 저장해두면 매번 명령어를 입력할 필요가 없어요.

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

이제 https://<magicdns>/ 주소로 대시보드에 접속할 수 있습니다.

주요 모드와 인증 방식

OpenClaw Gateway는 세 가지 모드를 지원해요.

serve: Tailnet 내부 사용자만 접속할 수 있는 HTTPS 주소를 제공해요. Gateway는 127.0.0.1에 바인딩된 상태를 유지하므로 안전해요.
funnel: 외부 인터넷에서도 접속할 수 있는 공개 HTTPS 주소를 생성해요. 보안을 위해 반드시 공유 비밀번호(password) 인증을 사용해야 합니다.
off: 기본값이며 Tailscale 자동화를 사용하지 않아요.

인증의 경우, tailscale.mode = "serve"이고 gateway.auth.allowTailscale이 true라면 별도의 토큰이나 비밀번호 없이 Tailscale 계정 정보(tailscale-user-login 헤더)로 자동 인증할 수 있어요. OpenClaw가 tailscale whois를 통해 신원을 직접 검증하거든요.

직접 Tailnet IP에 바인딩하고 싶다면 아래 설정을 사용하세요. 이 모드에서는 HTTPS가 제공되지 않으며 루프백(127.0.0.1) 접속이 불가능해집니다.

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

Troubleshooting

설정 중 문제가 발생하면 다음 내용을 확인해 보세요.

Funnel이 시작되지 않아요: Funnel 모드는 보안을 위해 인증 모드가 password가 아니면 실행을 거부해요. OPENCLAW_GATEWAY_PASSWORD 환경 변수를 설정했는지 확인하세요.
포트 접속 문제: Tailscale Funnel은 TLS를 통해 443, 8443, 10000 포트만 지원해요.
macOS 사용 시 주의사항: App Store에서 받은 Tailscale 앱은 Funnel 기능을 지원하지 않을 수 있어요. 오픈 소스 변체(variant)를 설치했는지 확인하세요.
인증 헤더 문제: OpenClaw는 루프백으로 들어오는 요청 중 Tailscale의 x-forwarded-for, x-forwarded-proto, x-forwarded-host 헤더가 있는 경우에만 Serve 요청으로 처리해요.

설정 과정에서 더 궁금한 점이 있다면 AI Setup Assistant를 활용해 보세요.

What’s Next

OpenClaw Expert

아직 막혀 있나요?

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.