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 컴패니언 앱입니다. 관리자 권한 없이 설치할 수 있으며 자체 릴리스 페이지에서 서명된 x64 및 ARM64 설치 프로그램을 제공합니다.

Windows Hub는 OpenClaw CLI 및 Gateway와 별도로 배포됩니다. 최신 안정 버전 Hub 설치 프로그램은 Windows Hub 릴리스 페이지에서 다운로드하거나 releases/latest/download를 통해 직접 다운로드하십시오.

• OpenClawCompanion-Setup-x64.exe
• OpenClawCompanion-Setup-arm64.exe

위 링크에서 404 오류가 발생하면 Windows Hub 릴리스 페이지를 방문하여 최신 안정 버전 Windows Hub 릴리스를 여십시오. 일반 OpenClaw 안정 버전 릴리스에도 고정되고 릴리스 검증을 거친 Windows Hub 빌드가 미러링되지만, 이 미러는 더 최신인 독립 Hub 릴리스보다 늦을 수 있습니다.

설치 후 시작 메뉴 또는 시스템 트레이에서 OpenClaw Companion을 실행하십시오. 설치 프로그램은 Gateway Setup, Chat, Settings, Check for Updates 및 제거 바로 가기도 추가합니다.

Windows Hub에 포함된 기능

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

최초 실행

최초 실행 시 사용할 수 있는 저장된 Gateway가 없으면 Windows Hub에서 설정이 열립니다. 가장 빠른 방법은 Set up locally입니다. 이 옵션은 앱 소유 OpenClawGateway WSL 배포판을 프로비저닝하고, 내부에 Gateway를 설치한 다음 앱을 페어링합니다. 기존 Ubuntu 배포판을 내보내거나 변경하지 않습니다.

이미 Gateway가 있다면 Advanced setup을 선택하거나 Connections 탭을 여십시오. 다음 대상에 연결할 수 있습니다.

• 이 PC의 로컬 Gateway
• 이 PC의 WSL Gateway
• URL과 토큰 또는 설정 코드를 사용하는 원격 Gateway
• SSH 터널을 통해 연결되는 Gateway

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

Windows 노드 모드

Windows Hub를 OpenClaw 노드로 등록하면 에이전트가 Gateway를 통해 선언된 Windows 네이티브 기능을 사용할 수 있습니다. 노드 명령을 실행하려면 먼저 노드에서 이를 선언하고 Gateway 정책에서 허용해야 합니다. 전체 허용/거부 모델은 노드를 참조하십시오.

일반적인 명령:

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

openclaw devices listopenclaw devices approve <requestId>openclaw nodes status

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

로컬 MCP 모드

Windows Hub는 동일한 Windows 네이티브 기능 레지스트리를 루프백의 로컬 MCP 서버로 노출할 수 있습니다. 따라서 로컬 MCP 클라이언트는 실행 중인 OpenClaw Gateway 없이도 Windows 기능을 제어할 수 있습니다.

Windows Hub Settings의 개발자/고급 섹션에서 이 기능을 활성화하십시오. 서버가 활성화되면 앱에 루프백 엔드포인트와 전달자 토큰이 표시됩니다.

모드 매트릭스:

네이티브 Windows CLI 및 Gateway

터미널 중심으로 사용하려면 PowerShell에서 OpenClaw을 설치하십시오.

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

확인:

openclaw --versionopenclaw doctoropenclaw gateway status --json

관리형 시작은 가능한 경우 Windows Scheduled Tasks를 사용합니다. 작업은 OpenClaw 상태 디렉터리에 읽을 수 있는 gateway.cmd 스크립트를 유지하지만, 생성된 gateway.vbs WScript 래퍼를 통해 실행하므로 백그라운드 Gateway가 표시되는 콘솔 창을 열지 않습니다. 작업 생성이 거부되면 OpenClaw은 사용자별 Startup 폴더 로그인 항목으로 대체합니다.

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

재부팅 후 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를 찾을 수 없습니다." } 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을 사용하십시오.

문제 해결

트레이 아이콘이 표시되지 않음

Task Manager에서 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 <requestId>

장치에 이미 토큰이 있었다면 승인 후 Connections 탭에서 다시 연결하십시오.

웹 채팅에서 원격 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 구성