Windows (WSL2)

Windows에서 OpenClaw은 WSL2를 통해 사용하는 것을 권장합니다 (Ubuntu 권장). CLI + 게이트웨이는 Linux 내부에서 실행되어, 런타임이 일관되고 도구 호환성이 훨씬 높습니다 (Node/Bun/pnpm, Linux 바이너리, 스킬). 네이티브 Windows는 까다로울 수 있습니다. WSL2는 완전한 Linux 경험을 제공합니다 — 설치 명령 하나면 됩니다: wsl --install.

네이티브 Windows 컴패니언 앱은 계획 중입니다.

설치 (WSL2)

네이티브 Windows 현황

네이티브 Windows CLI 흐름은 개선 중이지만, WSL2가 여전히 권장 경로입니다.

현재 네이티브 Windows에서 잘 동작하는 것:

  • install.ps1을 통한 웹사이트 설치기
  • openclaw --version, openclaw doctor, openclaw plugins list --json 등 로컬 CLI 사용
  • 임베디드 로컬 에이전트/프로바이더 스모크 테스트:
openclaw agent --local --agent main --thinking low -m "Reply with exactly WINDOWS-HATCH-OK."

현재 주의 사항:

  • openclaw onboard --non-interactive는 --skip-health를 전달하지 않으면 접근 가능한 로컬 게이트웨이를 기대함
  • openclaw onboard --non-interactive --install-daemon 및 openclaw gateway install은 먼저 Windows 예약 작업을 시도함
  • 예약 작업 생성이 거부되면, OpenClaw은 사용자별 시작 프로그램 폴더의 로그인 항목으로 대체하고 게이트웨이를 즉시 시작함
  • schtasks 자체가 멈추거나 응답을 멈추면, OpenClaw은 영구 대기 대신 해당 경로를 빠르게 중단하고 대체 경로를 사용함
  • 예약 작업은 더 나은 감독 상태를 제공하므로 가능한 경우 여전히 선호됨

게이트웨이 서비스 설치 없이 네이티브 CLI만 원한다면:

openclaw onboard --non-interactive --skip-health
openclaw gateway run

네이티브 Windows에서 관리 시작을 원한다면:

openclaw gateway install
openclaw gateway status --json

예약 작업 생성이 차단되면, 대체 서비스 모드가 현재 사용자의 시작 프로그램 폴더를 통해 로그인 후 자동 시작합니다.

게이트웨이

게이트웨이 서비스 설치 (CLI)

WSL2 내부에서:

openclaw onboard --install-daemon

또는:

openclaw gateway install

또는:

openclaw configure

프롬프트에서 Gateway service를 선택하세요.

복구/마이그레이션:

openclaw doctor

Windows 로그인 전 게이트웨이 자동 시작

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

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

WSL 내부에서:

sudo loginctl enable-linger "$(whoami)"

2) OpenClaw 게이트웨이 사용자 서비스 설치

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
systemctl --user status openclaw-gateway --no-pager

고급: LAN을 통한 WSL 서비스 노출 (portproxy)

WSL은 자체 가상 네트워크를 가집니다. 다른 머신이 WSL 내부에서 실행 중인 서비스(SSH, 로컬 TTS 서버 또는 게이트웨이)에 접근하려면, 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 방화벽에서 포트 허용 (최초 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).
  • 원격 노드는 접근 가능한 게이트웨이 URL(127.0.0.1이 아닌)을 가리켜야 합니다. openclaw status --all로 확인하세요.
  • LAN 접근에는 listenaddress=0.0.0.0, 로컬 전용에는 127.0.0.1을 사용하세요.
  • 자동화를 원하면, 로그인 시 갱신 단계를 실행하는 예약 작업을 등록하세요.

WSL2 단계별 설치

1) WSL2 + Ubuntu 설치

관리자 권한의 PowerShell에서:

wsl --install
# 또는 디스트로를 명시적으로 선택:
wsl --list --online
wsl --install -d Ubuntu-24.04

Windows가 요청하면 재부팅하세요.

2) systemd 활성화 (게이트웨이 설치에 필요)

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 시작하기 흐름을 따르세요:

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build # 최초 실행 시 UI 의존성 자동 설치
pnpm build
openclaw onboard

전체 가이드: 시작하기

Windows 컴패니언 앱

아직 Windows 컴패니언 앱이 없습니다. 개발에 참여하고 싶다면 기여를 환영합니다.

arrow_back
이전
Linux
다음
Android
arrow_forward