---
read_when:
    - Windows에 OpenClaw 설치하기
    - Windows Hub, 네이티브 Windows 및 WSL2 중 선택하기
    - Windows 컴패니언 앱 또는 Windows Node 모드 설정하기
summary: 'Windows 지원: Windows Hub, 네이티브 CLI 및 Gateway, WSL2 Gateway 설정, Node 모드 및 문제 해결'
title: Windows
x-i18n:
    generated_at: "2026-07-12T15:27:14Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 15
    provider: openai
    source_hash: f1a756d3af3898f211c27c34e16bbcc08f71e214ca1e0d5680c15a091ae1c2ca
    source_path: platforms/windows.md
    workflow: 16
---

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 릴리스 페이지](https://github.com/openclaw/openclaw-windows-node/releases/latest)에서 다운로드하거나
`releases/latest/download`를 통해 직접 다운로드하십시오.

- [OpenClawCompanion-Setup-x64.exe](https://github.com/openclaw/openclaw-windows-node/releases/latest/download/OpenClawCompanion-Setup-x64.exe)
- [OpenClawCompanion-Setup-arm64.exe](https://github.com/openclaw/openclaw-windows-node/releases/latest/download/OpenClawCompanion-Setup-arm64.exe)

위 링크에서 404 오류가 발생하면 [Windows Hub 릴리스 페이지](https://github.com/openclaw/openclaw-windows-node/releases)를 방문하여
최신 안정 버전 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 정책에서 허용해야 합니다. 전체 허용/거부 모델은
[노드](/ko/nodes#command-policy)를 참조하십시오.

일반적인 명령:

| 계열 | 명령                                                                                 |
| ------ | ------------------------------------------------------------------------------------ |
| 캔버스 | `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`                                       |
| 대화   | `talk.ptt.start`, `talk.ptt.stop`, `talk.ptt.cancel`, `talk.ptt.once`, `talk.speak`  |

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

```powershell
openclaw devices list
openclaw 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의 개발자/고급 섹션에서 이 기능을 활성화하십시오. 서버가 활성화되면
앱에 루프백 엔드포인트와 전달자 토큰이 표시됩니다.

모드 매트릭스:

| 노드 모드 | MCP 서버 | 동작                               |
| --------- | ---------- | ---------------------------------- |
| 꺼짐       | 꺼짐        | 운영자 전용 데스크톱 앱             |
| 켜짐       | 꺼짐        | Gateway에 연결된 Windows 노드       |
| 꺼짐       | 켜짐        | 로컬 MCP 서버만                     |
| 켜짐       | 켜짐        | Gateway 노드 및 로컬 MCP 서버       |

## 네이티브 Windows CLI 및 Gateway

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

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

확인:

```powershell
openclaw --version
openclaw doctor
openclaw gateway status --json
```

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

Gateway 서비스를 설치하십시오.

```powershell
openclaw gateway install
openclaw gateway status --json
```

관리형 Gateway 서비스 없이 CLI만 사용하려면 다음을 실행하십시오.

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

## WSL2 Gateway

WSL2는 Windows에서 Linux와 가장 호환되는 Gateway 런타임입니다. Windows
Hub에서 앱 소유 WSL Gateway를 설정하도록 하거나 자체 배포판 내부에
수동으로 설치할 수 있습니다.

수동 설정:

```powershell
wsl --install
# 또는 배포판을 명시적으로 선택합니다.
wsl --list --online
wsl --install -d Ubuntu-24.04
```

WSL 내부에서 systemd를 활성화하십시오.

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

PowerShell에서 WSL을 다시 시작하십시오.

```powershell
wsl --shutdown
```

그런 다음 Linux 빠른 시작을 사용하여 WSL 내부에 OpenClaw을 설치하십시오.

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

## Windows 로그인 전 Gateway 자동 시작

헤드리스 WSL 설정에서는 아무도
Windows에 로그인하지 않더라도 전체 부팅 체인이 실행되도록 하십시오.

WSL 내부:

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

관리자 권한 PowerShell:

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

`Ubuntu`를 다음 명령으로 확인한 배포판 이름으로 바꾸십시오.

```powershell
wsl --list --verbose
```

<Note>
이전 방법과 달라진 두 가지 사항:

- **`/bin/true` 대신 `dbus-launch true`**: WSL >= 2.6.1.0에서는
  회귀 문제([microsoft/WSL #13416](https://github.com/microsoft/WSL/issues/13416))로 인해 linger를 활성화해도
  마지막 클라이언트가 종료된 후 15-20초가 지나면 배포판이 유휴 종료됩니다.
  `dbus-launch true`는 우회 방법으로 init의 자식 프로세스를 계속 실행합니다
  (커뮤니티 토론: [microsoft/WSL #9245](https://github.com/microsoft/WSL/discussions/9245)).
- **`/ru SYSTEM` 대신 `/ru "$env:USERNAME"`**: 사용자별 WSL 배포판은
  (기본 설정) SYSTEM 계정에 표시되지 않으므로 작업이 실행되는 것처럼 보이지만
  배포판은 시작되지 않습니다. 본인 계정으로 실행하면 이를 방지할 수 있으며,
  작업을 생성할 때 Windows에서 암호를 입력하라는 메시지가 표시됩니다.

</Note>

재부팅 후 WSL에서 확인하십시오.

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

## LAN을 통해 WSL 서비스 노출

WSL에는 자체 가상 네트워크가 있습니다. 다른 컴퓨터에서 WSL 내부 서비스에
접근해야 하는 경우 Windows 포트를 현재 WSL IP로 전달하십시오. WSL IP는
재시작 후 변경될 수 있으므로 필요할 때 전달 규칙을 갱신하십시오.

관리자 권한 PowerShell 예시:

```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에서 설정 로그를 열거나 다음 파일을 확인하십시오.

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

일반적인 원인으로는 비활성화된 WSL, 차단된 가상화, 오래된 앱 소유 WSL
상태 또는 Gateway 패키지 설치 중 발생한 네트워크 오류가 있습니다.

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

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

```powershell
openclaw devices list
openclaw 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` 인증을 사용하려면 다음을 실행하십시오.

```powershell
$env:GH_TOKEN="<your-token>"
gh auth status
gh auth setup-git
```

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

## 관련 항목

- [설치 개요](/ko/install)
- [Node.js 설정](/ko/install/node)
- [노드](/ko/nodes)
- [Control UI](/ko/web/control-ui)
- [Gateway 구성](/ko/gateway/configuration)