Windows

OpenClaw는 기본 Windows Hub 컴패니언 앱과 Windows CLI 지원을 함께 제공합니다. 설정, 트레이 상태, 채팅, Command Center 진단, Windows 노드 기능을 갖춘 데스크톱 앱이 필요할 때는 Windows Hub를 사용하세요. CLI/Gateway를 직접 사용하려면 PowerShell 설치 프로그램을 사용하세요. 가장 Linux와 호환성이 높은 Gateway 런타임이 필요할 때는 WSL2를 사용하세요.

권장: Windows Hub

Windows Hub는 Windows 10 20H2+ 및 Windows 11용 네이티브 WinUI 컴패니언 앱입니다. 관리자 권한 없이 설치되며 OpenClaw 릴리스에서 서명된 x64 및 ARM64 설치 프로그램으로 제공됩니다.

OpenClaw 릴리스 페이지에서 최신 안정 설치 프로그램을 다운로드하세요.

• OpenClawCompanion-Setup-x64.exe
• OpenClawCompanion-Setup-arm64.exe
• 체크섬

위 다운로드 링크가 404를 반환하면 릴리스 페이지를 방문하여 최신 릴리스의 OpenClawCompanion-Setup-* 자산을 찾으세요.

설치 후 시작 메뉴 또는 시스템 트레이에서 OpenClaw Companion을 실행하세요. 설치 프로그램은 Gateway 설정, 채팅, 설정, 업데이트 확인 및 제거 바로가기도 추가합니다.

Windows Hub에 포함된 항목

• 시스템 트레이 상태 및 로그인 시 실행
• 로컬 앱 소유 WSL Gateway를 위한 첫 실행 설정
• 로컬, 원격, SSH 터널링된 Gateway에 대한 연결 설정
• 네이티브 채팅 창 및 브라우저 Control UI 접근
• 세션, 사용량, 채널, 노드, 페어링 및 복구 명령을 위한 Command Center 진단
• 에이전트 제어 캔버스, 화면, 카메라, 알림, 기기 상태, 텍스트 음성 변환, 음성 텍스트 변환, 제어된 system.run을 위한 Windows 노드 모드
• Claude Desktop, Claude Code, Cursor 같은 MCP 클라이언트를 위한 local MCP 서버 모드

첫 실행

첫 실행 시 사용 가능한 저장된 Gateway가 없으면 Windows Hub가 설정을 엽니다. 가장 빠른 경로는 로컬로 설정이며, 앱 소유 OpenClawGateway WSL 배포판을 프로비저닝하고 그 안에 Gateway를 설치한 다음 앱을 페어링합니다. 이는 기존 Ubuntu 배포판을 내보내거나 변경하지 않습니다.

이미 Gateway가 있는 경우 고급 설정을 선택하거나 연결 탭을 여세요. 다음에 연결할 수 있습니다.

• 이 PC의 로컬 Gateway
• 이 PC의 WSL Gateway
• URL 및 토큰 또는 설정 코드로 연결하는 원격 Gateway
• SSH 터널을 통해 도달하는 Gateway

설정이 완료되면 트레이 아이콘이 녹색으로 바뀝니다. 트레이에서 Command Center를 열어 연결, 페어링, 노드 상태 및 채널 상태를 확인하세요.

Windows 노드 모드

Windows Hub는 1급 OpenClaw 노드로 등록될 수 있습니다. 그러면 에이전트가 Gateway를 통해 선언된 Windows 네이티브 기능을 사용할 수 있습니다.

일반적인 명령은 다음과 같습니다.

• canvas.present, canvas.hide, canvas.navigate, canvas.eval, canvas.snapshot
• screen.snapshot 및 명시적으로 옵트인한 경우 screen.record
• camera.list 및 명시적으로 옵트인한 경우 camera.snap, camera.clip
• system.notify, system.run, system.run.prepare, system.which
• location.get, device.info, device.status
• stt.transcribe, tts.speak

노드 모드에는 Gateway 페어링이 필요합니다. 앱에 페어링 요청이 표시되면 Gateway 호스트에서 승인하세요.

openclaw devices listopenclaw devices approve <request-id>openclaw nodes status

Gateway는 노드가 선언하고 서버 정책이 허용하는 명령만 전달합니다. screen.record, camera.snap, camera.clip 같은 개인정보에 민감한 명령은 명시적인 gateway.nodes.allowCommands 옵트인이 필요합니다.

local MCP 모드

Windows Hub는 동일한 Windows 네이티브 기능 레지스트리를 루프백의 local MCP 서버로 노출할 수 있습니다. 이는 실행 중인 OpenClaw Gateway 없이 local MCP 클라이언트가 Windows 기능을 구동하게 하려는 경우에 유용합니다.

Windows Hub 설정의 개발자/고급 섹션에서 활성화하세요. 서버가 활성화되면 앱이 루프백 엔드포인트와 전달자 토큰을 표시합니다.

모드 매트릭스:

네이티브 Windows CLI 및 Gateway

터미널 우선 사용을 위해 PowerShell에서 OpenClaw를 설치하세요.

iwr -useb https://openclaw.ai/install.ps1 | iex

확인:

openclaw --versionopenclaw doctoropenclaw gateway status --json

네이티브 Windows CLI 및 Gateway 흐름은 지원되며 계속 개선되고 있습니다. 관리형 시작은 사용 가능한 경우 Windows 예약 작업을 사용합니다. 작업은 OpenClaw 상태 디렉터리에 읽을 수 있는 gateway.cmd 스크립트를 유지하지만, 생성된 gateway.vbs WScript 래퍼를 통해 실행하여 백그라운드 Gateway가 보이는 콘솔 창을 열지 않도록 합니다. 작업 생성이 거부되면 OpenClaw는 사용자별 시작 폴더 로그인 항목으로 대체합니다.

Gateway 서비스를 설치하려면:

openclaw gateway installopenclaw gateway status --json

관리형 Gateway 서비스 없이 CLI만 사용하려면:

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

WSL2 Gateway

WSL2는 Windows에서 가장 Linux와 호환성이 높은 Gateway 런타임으로 남아 있습니다. Windows Hub가 앱 소유 WSL Gateway를 설정해 줄 수 있으며, 사용자가 직접 자신의 배포판 안에 수동으로 설치할 수도 있습니다.

수동 설정:

wsl --install# 또는 배포판을 명시적으로 선택:wsl --list --onlinewsl --install -d Ubuntu-24.04

WSL 안에서 systemd를 활성화하세요.

sudo tee /etc/wsl.conf >/dev/null <<'EOF'[boot]systemd=trueEOF

PowerShell에서 WSL을 다시 시작하세요.

wsl --shutdown

그런 다음 Linux 빠른 시작으로 WSL 안에 OpenClaw를 설치하세요.

curl -fsSL https://openclaw.ai/install.sh | bashopenclaw gateway status

Windows 로그인 전 Gateway 자동 시작

헤드리스 WSL 설정의 경우 아무도 Windows에 로그인하지 않아도 전체 부팅 체인이 실행되도록 하세요.

WSL 안에서:

sudo apt-get install -y dbus-x11sudo loginctl enable-linger "$(whoami)"openclaw gateway install

관리자 권한 PowerShell에서:

schtasks /create /tn "WSL Boot" /tr "wsl.exe -d Ubuntu --exec dbus-launch true" /sc onstart /ru "$env:USERNAME"

Ubuntu를 다음에서 확인한 배포판 이름으로 바꾸세요.

wsl --list --verbose

참고: 이전 레시피와 다른 두 가지 변경 사항:

• /bin/true 대신 dbus-launch true — WSL ≥ 2.6.1.0에서 회귀(microsoft/WSL #13416)로 인해 linger가 활성화되어 있어도 마지막 클라이언트가 종료된 뒤 15~20초 후 배포판이 유휴 종료됩니다. dbus-launch true는 우회 방법으로 init의 자식 프로세스를 살아 있게 유지합니다(커뮤니티 논의, microsoft/WSL #9245).
• /ru SYSTEM 대신 /ru "$env:USERNAME" — 사용자별 WSL 배포판(기본 설정)은 SYSTEM 계정에 보이지 않습니다. 작업은 실행되는 것처럼 보이지만 배포판은 시작되지 않습니다. 자신의 계정으로 실행하면 이를 피할 수 있습니다. Windows는 작업 생성 시 암호를 요청합니다.

재부팅 후 WSL에서 확인하세요.

systemctl --user is-enabled openclaw-gateway.servicesystemctl --user status openclaw-gateway.service --no-pager

LAN을 통해 WSL 서비스 노출

WSL은 자체 가상 네트워크를 가집니다. 다른 머신이 WSL 안의 서비스에 도달해야 하는 경우 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 New-NetFirewallRule -DisplayName "WSL SSH $ListenPort" -Direction Inbound `  -Protocol TCP -LocalPort $ListenPort -Action Allow

참고:

• 다른 머신에서 SSH는 Windows 호스트 IP를 대상으로 합니다. 예: ssh user@windows-host -p 2222.
• 원격 노드는 127.0.0.1이 아니라 도달 가능한 Gateway URL을 가리켜야 합니다.
• LAN 접근에는 listenaddress=0.0.0.0을 사용하세요. 로컬 전용 접근에는 127.0.0.1을 사용하세요.

문제 해결

트레이 아이콘이 나타나지 않음

작업 관리자에서 OpenClaw.Tray.WinUI.exe를 확인하세요. 실행 중이면 숨겨진 트레이 아이콘 영역을 열어 고정하세요. 실행 중이 아니면 시작 메뉴에서 OpenClaw Companion을 실행하세요.

로컬 설정 실패

Windows Hub에서 설정 로그를 열거나 다음을 확인하세요.

notepad "$env:LOCALAPPDATA\OpenClawTray\Logs\Setup\easy-setup-latest.txt"

일반적인 원인은 비활성화된 WSL, 차단된 가상화, 오래된 앱 소유 WSL 상태, 또는 Gateway 패키지 설치 중 네트워크 실패입니다.

앱에서 페어링이 필요하다고 표시됨

Gateway에서 운영자 또는 노드 요청을 승인하세요.

openclaw devices listopenclaw devices approve <request-id>

기기에 이미 토큰이 있었다면 승인 후 연결 탭에서 다시 연결하세요.

웹 채팅이 원격 Gateway에 도달할 수 없음

원격 웹 채팅에는 HTTPS 또는 localhost가 필요합니다. 자체 서명 인증서의 경우 Windows에서 인증서를 신뢰하도록 설정하거나, localhost URL로 SSH 터널을 사용하세요.

screen.snapshot, 카메라 또는 오디오 명령 실패

카메라, 마이크, 화면 캡처 및 알림에 대한 Windows 권한을 확인하세요. 패키징된 설치는 보호된 기능을 선언하지만, 명령이 처음 사용할 때 Windows가 여전히 프롬프트를 표시할 수 있습니다.

Git 또는 GitHub 연결 실패

일부 네트워크는 GitHub로 가는 HTTPS를 차단하거나 제한합니다. git clone 또는 gh auth login이 실패하면 다른 네트워크, VPN 또는 HTTP/HTTPS 프록시를 시도하세요.

현재 세션에서 토큰 기반 gh 인증을 사용하려면:

$env:GH_TOKEN="<your-token>"gh auth statusgh auth setup-git

토큰을 절대 커밋하거나 이슈 또는 풀 리퀘스트에 붙여넣지 마세요.

관련 항목

• 설치 개요
• Node.js 설정
• 노드
• Control UI
• Gateway 구성