메인 콘텐츠로 건너뛰기

​
Windows

OpenClaw는 네이티브 Windows와 WSL2를 모두 지원합니다. WSL2가 더 안정적인 경로이며 전체 경험을 위해 권장됩니다. CLI, Gateway, tooling이 Linux 내부에서 완전한 호환성과 함께 실행됩니다. 네이티브 Windows도 핵심 CLI와 Gateway 사용에는 동작하지만, 아래에 설명된 몇 가지 주의 사항이 있습니다. 네이티브 Windows companion apps는 계획되어 있습니다.

​
WSL2 (권장)

​
네이티브 Windows 상태

네이티브 Windows CLI 흐름은 계속 개선되고 있지만, 여전히 WSL2가 권장 경로입니다. 현재 네이티브 Windows에서 잘 작동하는 항목:
  • install.ps1을 통한 웹사이트 설치 프로그램
  • openclaw --version, openclaw doctor, openclaw plugins list --json 같은 로컬 CLI 사용
  • 다음과 같은 내장 local-agent/provider 스모크 테스트:
openclaw agent --local --agent main --thinking low -m "Reply with exactly WINDOWS-HATCH-OK."
현재 주의 사항:
  • openclaw onboard --non-interactive는 --skip-health를 전달하지 않으면 여전히 도달 가능한 로컬 gateway를 기대합니다
  • openclaw onboard --non-interactive --install-daemon 및 openclaw gateway install은 먼저 Windows Scheduled Tasks를 시도합니다
  • Scheduled Task 생성이 거부되면 OpenClaw는 사용자별 Startup 폴더 로그인 항목으로 폴백하고 gateway를 즉시 시작합니다
  • schtasks 자체가 멈추거나 응답하지 않으면 OpenClaw는 이제 영원히 멈추는 대신 해당 경로를 빠르게 중단하고 폴백합니다
  • Scheduled Tasks는 더 나은 supervisor 상태를 제공하므로 사용 가능한 경우 여전히 선호됩니다
네이티브 CLI만 원하고 gateway 서비스 설치는 원하지 않는다면 다음 중 하나를 사용하세요. 
openclaw onboard --non-interactive --skip-health
openclaw gateway run
네이티브 Windows에서 관리형 시작을 원한다면: 
openclaw gateway install
openclaw gateway status --json
Scheduled Task 생성이 차단되더라도, 폴백 서비스 모드는 현재 사용자의 Startup 폴더를 통해 로그인 후 자동 시작됩니다.

​
Gateway

​
Gateway 서비스 설치 (CLI)

WSL2 내부에서: 
openclaw onboard --install-daemon
또는: 
openclaw gateway install
또는: 
openclaw configure
프롬프트가 뜨면 Gateway service를 선택하세요. 복구/마이그레이션: 
openclaw doctor

​
Windows 로그인 전 Gateway 자동 시작

헤드리스 구성에서는 아무도 Windows에 로그인하지 않아도 전체 부팅 체인이 실행되도록 해야 합니다.

​
1) 로그인 없이도 사용자 서비스 유지

WSL 내부에서: 
sudo loginctl enable-linger "$(whoami)"

​
2) OpenClaw gateway 사용자 서비스 설치

WSL 내부에서: 
openclaw gateway install

​
3) Windows 부팅 시 WSL 자동 시작

관리자 권한 PowerShell에서: 
schtasks /create /tn "WSL Boot" /tr "wsl.exe -d Ubuntu --exec /bin/true" /sc onstart /ru SYSTEM
Ubuntu는 다음 명령으로 확인한 배포판 이름으로 교체하세요. 
wsl --list --verbose

​
시작 체인 확인

재부팅 후(Windows 로그인 전) WSL에서 다음을 확인하세요. 
systemctl --user is-enabled openclaw-gateway.service
systemctl --user status openclaw-gateway.service --no-pager

​
고급: WSL 서비스를 LAN에 노출(portproxy)

WSL은 자체 가상 네트워크를 가집니다. 다른 머신이 WSL 내부에서 실행 중인 서비스(SSH, 로컬 TTS 서버, Gateway)에 도달해야 한다면, Windows 포트를 현재 WSL IP로 포워딩해야 합니다. WSL IP는 재시작 후 바뀌므로 포워딩 규칙을 새로 고쳐야 할 수 있습니다. 예시 (PowerShell 관리자 권한으로): 
$Distro = "Ubuntu-24.04"
$ListenPort = 2222
$TargetPort = 22

$WslIp = (wsl -d $Distro -- hostname -I).Trim().Split(" ")[0]
if (-not $WslIp) { throw "WSL IP not found." }

netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=$ListenPort `
  connectaddress=$WslIp connectport=$TargetPort
Windows Firewall에서 해당 포트를 허용합니다(1회): 
New-NetFirewallRule -DisplayName "WSL SSH $ListenPort" -Direction Inbound `
  -Protocol TCP -LocalPort $ListenPort -Action Allow
WSL 재시작 후 portproxy 새로 고침: 
netsh interface portproxy delete v4tov4 listenport=$ListenPort listenaddress=0.0.0.0 | Out-Null
netsh interface portproxy add v4tov4 listenport=$ListenPort listenaddress=0.0.0.0 `
  connectaddress=$WslIp connectport=$TargetPort | Out-Null
참고:
  • 다른 머신에서의 SSH는 Windows 호스트 IP를 대상으로 해야 합니다(예: ssh user@windows-host -p 2222)
  • 원격 노드는 도달 가능한 Gateway URL(127.0.0.1 아님)을 가리켜야 합니다. openclaw status --all로 확인하세요.
  • LAN 액세스에는 listenaddress=0.0.0.0를 사용하고, 127.0.0.1은 로컬 전용입니다.
  • 이를 자동화하려면 로그인 시 새로 고침 단계를 실행하는 Scheduled Task를 등록하세요.

​
단계별 WSL2 설치

​
1) WSL2 + Ubuntu 설치

PowerShell(관리자)에서: 
wsl --install
# 또는 배포판을 명시적으로 선택:
wsl --list --online
wsl --install -d Ubuntu-24.04
Windows가 요청하면 재부팅하세요.

​
2) systemd 활성화 (gateway 설치에 필요)

WSL 터미널에서: 
sudo tee /etc/wsl.conf >/dev/null <<'EOF'
[boot]
systemd=true
EOF
그런 다음 PowerShell에서: 
wsl --shutdown
Ubuntu를 다시 열고 다음으로 확인하세요. 
systemctl --user status

​
3) OpenClaw 설치 (WSL 내부)

WSL 내부에서 Linux Getting Started 흐름을 따르세요. 
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build # 첫 실행 시 UI 종속성 자동 설치
pnpm build
openclaw onboard
전체 가이드: Getting Started

​
Windows companion app

아직 Windows companion app은 없습니다. 이를 실현하고 싶다면 contributions는 환영합니다.