Windows WSL2 설치 & 텔레그램 연동 가이드

왜 WSL2인가요?
Windows 네이티브(PowerShell)에서는 ESM 경로 오류(ERR_UNSUPPORTED_ESM_URL_SCHEME)가 발생합니다. WSL2(Ubuntu)를 사용하면 Linux 환경처럼 안정적으로 실행됩니다.

왜 cloudflared인가요?
WSL2 안의 OpenClaw 게이트웨이는 127.0.0.1(로컬)에만 바인딩되어 외부 접근 불가. Telegram 봇은 외부에서 접근해야 하므로 cloudflared 터널로 임시 공개 URL을 만듭니다. Tailscale은 WSL2와 Windows의 네트워크가 분리되어 있어 직접 사용 어렵습니다.

섹션 1: WSL2 + OpenClaw 설치

기존 Windows OpenClaw 삭제 (해당 시)

이전에 Windows PowerShell에서 OpenClaw을 설치했다면 WSL2와 충돌할 수 있습니다. 먼저 제거합니다.

PowerShell (관리자)

npm uninstall -g openclaw clawhub
Remove-Item -Recurse -Force "$env:USERPROFILE\.openclaw"
where.exe openclaw

✅ 확인: where.exe openclaw 실행 시 아무것도 안 나오면 삭제 완료.

처음 설치하는 경우 이 단계를 건너뛰세요. 상세: /uninstall 페이지

WSL2 + Ubuntu 설치

PowerShell (관리자)

wsl --install

⚠️ 재부팅 필요! 설치 완료 후 PC를 재부팅하세요.

재부팅 후 Ubuntu가 자동으로 열리며, 사용자 이름과 비밀번호를 설정합니다.

💡 Tip: 이후 Ubuntu를 다시 열고 싶으면 PowerShell에서 wsl만 입력하면 됩니다.

Node.js 설치 (WSL Ubuntu)

WSL Ubuntu 터미널

# nvm 설치
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

# nvm 활성화
source ~/.bashrc

# Node.js 22 설치 (OpenClaw 최소 요구: v22.14.0)
nvm install 22

# 확인
node -v

✅ 확인: v22.x.x 이상 버전이 표시되면 성공.

OpenClaw 설치 & 초기 설정

WSL Ubuntu 터미널

# OpenClaw 설치
npm install -g openclaw

# 초기 설정 시작
openclaw onboard

onboard 진행 시 참고:

Security Warning → Yes
Setup mode → QuickStart
Channel → Telegram (봇 토큰 입력)
Model → Google Gemini (무료) 또는 OpenAI Codex (구독자)

💡 Telegram 봇 토큰: Telegram에서 @BotFather에게 /newbot 명령으로 발급받습니다.

섹션 2: Telegram 연동 — cloudflared 터널

이 섹션이 필요한 이유: WSL2의 OpenClaw 게이트웨이는 127.0.0.1에만 바인딩됩니다. Telegram 봇이 외부에서 접근하려면 공개 URL이 필요합니다. cloudflared가 그 다리 역할을 합니다.

cloudflared 설치

WSL Ubuntu 터미널

curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o ~/cloudflared
chmod +x ~/cloudflared

게이트웨이 설정 변경

WSL Ubuntu 터미널

openclaw gateway stop
openclaw config set gateway.tailscale.mode off
openclaw config set plugins.entries.device-pair.enabled true

터미널 2개로 실행

터미널 2개가 동시에 필요합니다. 각각 WSL Ubuntu 터미널을 열어주세요.

🔴 터미널 1 — cloudflared

~/cloudflared tunnel --url http://localhost:18789

🟣 터미널 2 — gateway

openclaw config set plugins.entries.device-pair.config.publicUrl "https://복사한-URL.trycloudflare.com"
openclaw gateway

💡 순서가 중요합니다:
1. 터미널 1에서 cloudflared 실행 → https://xxxx-xxxx.trycloudflare.com URL 복사
2. 터미널 2에서 복사한 URL을 publicUrl에 붙여넣기 → gateway 시작

Telegram 연동 확인

Telegram 앱에서 봇에게 아무 메시지(예: "안녕")를 보내세요.

✅ 봇이 응답하면 연동 성공! 🎉

봇이 응답하지 않으면:
1. 터미널 1(cloudflared)이 실행 중인지 확인
2. 터미널 2(gateway)가 실행 중인지 확인
3. publicUrl이 올바른지 확인 (openclaw config get plugins.entries.device-pair.config.publicUrl)

섹션 3: 재부팅 후 재연결 (매번)

⚠️ cloudflared URL은 매번 바뀝니다! PC를 재부팅하거나 터미널을 닫으면 아래 절차를 반복해야 합니다.

🔴 터미널 1 — PowerShell에서

wsl
openclaw gateway stop
~/cloudflared tunnel --url http://localhost:18789

🟣 터미널 2 — 또 PowerShell에서

wsl
openclaw config set plugins.entries.device-pair.config.publicUrl "https://새로나온URL.trycloudflare.com"
openclaw gateway

💡 요약: 터미널 1에서 새 URL 복사 → 터미널 2에 붙여넣기 → gateway 시작. 두 터미널 모두 열어두면 봇 바로 작동!

섹션 4: 주의사항 & 트러블슈팅

⚠️ 주의사항

터미널 2개(cloudflared + gateway)가 모두 켜져 있어야 봇이 작동합니다
cloudflared URL은 임시(ephemeral)이므로 재시작마다 새로 생성됩니다
상시 운영이 필요하면 항상 켜져 있는 서버(Linux 머신 등)에 설치하는 것을 권장합니다
복사-붙여넣기 시 --url의 하이픈(-)이 em dash(—)로 변환되지 않았는지 확인하세요

Gateway is only bound to loopback

외부에서 게이트웨이에 접근할 수 없는 상태입니다.

해결: cloudflared 터널을 설정하세요 (섹션 2 참고)

Tailscale Serve is enabled, but MagicDNS could not be resolved

Windows에 설치된 Tailscale과 WSL2의 네트워크가 분리되어 있어 발생합니다.

해결: Tailscale 모드를 끄고 cloudflared를 사용하세요.

openclaw config set gateway.tailscale.mode off

gateway already running (pid XXXX)

이전 게이트웨이가 종료되지 않은 상태입니다.

해결:

openclaw gateway stop

No pending pairing request found

페어링 코드가 만료되었습니다.

해결: Telegram에서 봇에게 다시 메시지를 보내 새 코드를 받으세요. 그리고 새 코드로 openclaw pairing approve 재시도.

`--url` 플래그가 em dash(—)로 입력됨

웹페이지에서 복사할 때 하이픈 2개(--)가 em dash(—)로 자동 변환되는 경우가 있습니다.

해결: 키보드로 하이픈(-) 키를 두 번 직접 입력하세요. 복사-붙여넣기 대신 수동 입력.

ERR_UNSUPPORTED_ESM_URL_SCHEME

Windows 네이티브 PowerShell에서 실행 시 발생하는 오류입니다.

해결: WSL2 Ubuntu에서 실행하세요. PowerShell이 아닌 WSL 터미널 필수!

섹션 5: Tailscale vs cloudflared 비교

항목	Tailscale	cloudflared
WSL2 지원	WSL 안에 별도 설치 필요 (복잡)	curl 한 줄로 설치
설정 난이도	중	하 (쉬움)
URL 안정성	고정 (변하지 않음)	매번 변경 (재시작마다)
추천 상황	상시 서버, 다중 기기	실습/테스트, 간헐적 사용
비용	무료 (개인)	무료

💡 결론: 세미나 실습이나 테스트 목적이라면 cloudflared가 간단합니다. 24시간 상시 운영이 필요하면 항상 켜져 있는 리눅스 서버(Mac Mini 등)에 설치하는 것을 권장합니다.

도움이 필요하신가요?
세미나 당일에 강사가 직접 도와드립니다. 미리 설치하지 못하셔도 걱정하지 마세요.
💬 #ai_native_education 슬랙 채널 | 📧 admin@nupik.kr

Windows WSL2에서OpenClaw 설치 & Telegram 연동

섹션 1: WSL2 + OpenClaw 설치

섹션 2: Telegram 연동 — cloudflared 터널

섹션 3: 재부팅 후 재연결 (매번)

섹션 4: 주의사항 & 트러블슈팅

⚠️ 주의사항

Gateway is only bound to loopback

Tailscale Serve is enabled, but MagicDNS could not be resolved

gateway already running (pid XXXX)

No pending pairing request found

--url 플래그가 em dash(—)로 입력됨

ERR_UNSUPPORTED_ESM_URL_SCHEME

섹션 5: Tailscale vs cloudflared 비교

Windows WSL2에서
OpenClaw 설치 & Telegram 연동

`--url` 플래그가 em dash(—)로 입력됨