Windows

Windows 문서는 OpenClaw 공식 문서(platforms/windows)를 한국어로 정리한 가이드입니다. Windows support: Windows Hub, native CLI and Gateway, WSL2 gateway setup, node mode, and troubleshooting 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Windows support: Windows Hub, native CLI and Gateway, WSL2 gateway setup, node mode, and troubleshooting

한국어 가이드 범위: platforms/windows 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Recommended: Windows Hub
What Windows Hub includes
First launch
Windows node mode
Local MCP mode
Native Windows CLI and Gateway
WSL2 Gateway
Or pick a distro explicitly:
Gateway auto-start before Windows login
Expose WSL services over LAN
트러블슈팅
The tray icon does not appear
Local setup fails
The app says pairing is required
Web chat cannot reach a remote Gateway
screen.snapshot, camera, or audio commands fail
Git or GitHub connectivity fails
관련 문서

상세 내용

본문

OpenClaw ships a native Windows Hub companion app plus Windows CLI support. Use Windows Hub for a desktop app with setup, tray status, chat, Command Center diagnostics, and Windows node capabilities. Use the PowerShell installer for the CLI/Gateway directly. Use WSL2 for the most Linux-compatible Gateway runtime.

Recommended: Windows Hub

Windows Hub is the native WinUI companion app for Windows 10 20H2+ and Windows 11. It installs without administrator privileges and ships signed x64 and ARM64 installers from its own release page.

주요 항목:

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

What Windows Hub includes

notifications, device status, talk, and controlled system.run.

주요 항목:

System tray status and launch-at-login.
First-run setup for a local app-owned WSL Gateway.
Connection settings for local, remote, and SSH-tunneled Gateways.
Native chat window plus access to the browser Control UI.
Command Center diagnostics for sessions, usage, channels, nodes, pairing,
Windows node mode for agent-controlled canvas, screen, camera,
Local MCP server mode for MCP clients such as Claude Desktop, Claude Code,

First launch

On first launch, Windows Hub opens setup when there is no usable saved Gateway. The fastest path is Set up locally, which provisions an app-owned OpenClawGateway WSL distro, installs the Gateway inside it, and pairs the app. This does not export or mutate your existing Ubuntu distro.

주요 항목:

a local Gateway on this PC
a WSL Gateway on this PC
a remote Gateway by URL and token or setup code
a Gateway reached through an SSH tunnel

Windows node mode

Windows Hub can register as an OpenClaw node so the agent can use declared Windows-native capabilities through the Gateway. Node commands must be declared by the node and allowed by Gateway policy before they run; see Nodes for the full allow/deny model.

Family	Commands
Canvas	`canvas.present`, `canvas.hide`, `canvas.navigate`, `canvas.eval`, `canvas.snapshot`
Screen	`screen.snapshot`; `screen.record` requires explicit opt-in
Camera	`camera.list`; `camera.snap`, `camera.clip` require explicit opt-in
System	`system.notify`, `system.run`, `system.run.prepare`, `system.which`
Device	`location.get`, `device.info`, `device.status`
Talk	`talk.ptt.start`, `talk.ptt.stop`, `talk.ptt.cancel`, `talk.ptt.once`, `talk.speak`

openclaw devices list
openclaw devices approve <requestId>
openclaw nodes status

Local MCP mode

Windows Hub can expose the same Windows-native capability registry as a local MCP server on loopback, so local MCP clients can drive Windows capabilities without a running OpenClaw Gateway.

Node mode	MCP server	Behavior
off	off	Operator-only desktop app
on	off	Gateway-connected Windows node
off	on	Local MCP server only
on	on	Gateway node plus local MCP server

Native Windows CLI and Gateway

For terminal-first use, install OpenClaw from PowerShell:

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

openclaw --version
openclaw doctor
openclaw gateway status --json

openclaw gateway install
openclaw gateway status --json

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

WSL2 Gateway

WSL2 remains the most Linux-compatible Gateway runtime on Windows. Windows Hub can set up an app-owned WSL Gateway for you, or install manually inside your own distro.

Or pick a distro explicitly:

wsl --list --online wsl --install -d Ubuntu-24.04 bash sudo tee /etc/wsl.conf >/dev/null <<'EOF' [boot] systemd=true EOF powershell wsl --shutdown bash curl -fsSL https://openclaw.ai/install.sh | bash openclaw gateway status ```

Enable systemd inside WSL:

Restart WSL from PowerShell:

Then install OpenClaw inside WSL with the Linux quickstart:

For headless WSL setups, make sure the full boot chain runs even when no one logs into Windows.

주요 항목:

dbus-launch true instead of /bin/true: on WSL >= 2.6.1.0 a
/ru "$env:USERNAME" instead of /ru SYSTEM: per-user WSL distros (the

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

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

wsl --list --verbose

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

Expose WSL services over LAN

WSL has its own virtual network. If another machine must reach a service inside WSL, forward a Windows port to the current WSL IP. The WSL IP can change after restarts, so refresh the forwarding rule when needed.

주요 항목:

SSH from another machine targets the Windows host IP, e.g. ssh user@windows-host -p 2222.
Remote nodes must point at a reachable Gateway URL, not 127.0.0.1.
Use listenaddress=0.0.0.0 for LAN access, 127.0.0.1 for local-only access.

$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

트러블슈팅

이 섹션의 세부 항목은 공식 문서 트러블슈팅를 참고하세요.

The tray icon does not appear

Check Task Manager for OpenClaw.Tray.WinUI.exe. If it is running, open the hidden tray-icons area and pin it. If not, launch OpenClaw Companion from the Start menu.

Local setup fails

Open the setup log from Windows Hub or inspect:

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

The app says pairing is required

Approve the operator or node request from the Gateway:

openclaw devices list
openclaw devices approve <requestId>

Web chat cannot reach a remote Gateway

Remote web chat needs HTTPS or localhost. For self-signed certificates, trust the certificate in Windows, or use an SSH tunnel to a localhost URL.

screen.snapshot, camera, or audio commands fail

Confirm Windows permissions for camera, microphone, screen capture, and notifications. Packaged installs declare the protected capabilities, but Windows may still prompt the first time a command uses them.

Git or GitHub connectivity fails

Some networks block or throttle HTTPS to GitHub. If git clone or gh auth login fails, try another network, a VPN, or an HTTP/HTTPS proxy.

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

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/platforms/windows
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

openclaw devices list
openclaw devices approve <requestId>
openclaw nodes status

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

openclaw --version
openclaw doctor
openclaw gateway status --json

openclaw gateway install
openclaw gateway status --json

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

wsl --install
# Or pick a distro explicitly:
wsl --list --online
wsl --install -d Ubuntu-24.04

Windows

핵심 요약

Windows support: Windows Hub, native CLI and Gateway, WSL2 gateway setup, node mode, and troubleshooting

한국어 가이드 범위: platforms/windows 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Recommended: Windows Hub
What Windows Hub includes
First launch
Windows node mode
Local MCP mode
Native Windows CLI and Gateway
WSL2 Gateway
Or pick a distro explicitly:
Gateway auto-start before Windows login
Expose WSL services over LAN
트러블슈팅
The tray icon does not appear
Local setup fails
The app says pairing is required
Web chat cannot reach a remote Gateway
screen.snapshot, camera, or audio commands fail
Git or GitHub connectivity fails
관련 문서

상세 내용

본문

Recommended: Windows Hub

Windows Hub is the native WinUI companion app for Windows 10 20H2+ and Windows 11. It installs without administrator privileges and ships signed x64 and ARM64 installers from its own release page.

주요 항목:

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

What Windows Hub includes

notifications, device status, talk, and controlled system.run.

주요 항목:

System tray status and launch-at-login.
First-run setup for a local app-owned WSL Gateway.
Connection settings for local, remote, and SSH-tunneled Gateways.
Native chat window plus access to the browser Control UI.
Command Center diagnostics for sessions, usage, channels, nodes, pairing,
Windows node mode for agent-controlled canvas, screen, camera,
Local MCP server mode for MCP clients such as Claude Desktop, Claude Code,

First launch

주요 항목:

a local Gateway on this PC
a WSL Gateway on this PC
a remote Gateway by URL and token or setup code
a Gateway reached through an SSH tunnel

Windows node mode

Family	Commands
Canvas	`canvas.present`, `canvas.hide`, `canvas.navigate`, `canvas.eval`, `canvas.snapshot`
Screen	`screen.snapshot`; `screen.record` requires explicit opt-in
Camera	`camera.list`; `camera.snap`, `camera.clip` require explicit opt-in
System	`system.notify`, `system.run`, `system.run.prepare`, `system.which`
Device	`location.get`, `device.info`, `device.status`
Talk	`talk.ptt.start`, `talk.ptt.stop`, `talk.ptt.cancel`, `talk.ptt.once`, `talk.speak`

openclaw devices list
openclaw devices approve <requestId>
openclaw nodes status

Local MCP mode

Windows Hub can expose the same Windows-native capability registry as a local MCP server on loopback, so local MCP clients can drive Windows capabilities without a running OpenClaw Gateway.

Node mode	MCP server	Behavior
off	off	Operator-only desktop app
on	off	Gateway-connected Windows node
off	on	Local MCP server only
on	on	Gateway node plus local MCP server

Native Windows CLI and Gateway

For terminal-first use, install OpenClaw from PowerShell:

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

openclaw --version
openclaw doctor
openclaw gateway status --json

openclaw gateway install
openclaw gateway status --json

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

WSL2 Gateway

WSL2 remains the most Linux-compatible Gateway runtime on Windows. Windows Hub can set up an app-owned WSL Gateway for you, or install manually inside your own distro.

Or pick a distro explicitly:

Enable systemd inside WSL:

Restart WSL from PowerShell:

Then install OpenClaw inside WSL with the Linux quickstart:

For headless WSL setups, make sure the full boot chain runs even when no one logs into Windows.

주요 항목:

dbus-launch true instead of /bin/true: on WSL >= 2.6.1.0 a
/ru "$env:USERNAME" instead of /ru SYSTEM: per-user WSL distros (the

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

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

wsl --list --verbose

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

Expose WSL services over LAN

주요 항목:

SSH from another machine targets the Windows host IP, e.g. ssh user@windows-host -p 2222.
Remote nodes must point at a reachable Gateway URL, not 127.0.0.1.
Use listenaddress=0.0.0.0 for LAN access, 127.0.0.1 for local-only access.

$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

트러블슈팅

이 섹션의 세부 항목은 공식 문서 트러블슈팅를 참고하세요.

The tray icon does not appear

Check Task Manager for OpenClaw.Tray.WinUI.exe. If it is running, open the hidden tray-icons area and pin it. If not, launch OpenClaw Companion from the Start menu.

Local setup fails

Open the setup log from Windows Hub or inspect:

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

The app says pairing is required

Approve the operator or node request from the Gateway:

openclaw devices list
openclaw devices approve <requestId>

Web chat cannot reach a remote Gateway

Remote web chat needs HTTPS or localhost. For self-signed certificates, trust the certificate in Windows, or use an SSH tunnel to a localhost URL.

screen.snapshot, camera, or audio commands fail

Git or GitHub connectivity fails

Some networks block or throttle HTTPS to GitHub. If git clone or gh auth login fails, try another network, a VPN, or an HTTP/HTTPS proxy.

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

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/platforms/windows
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

openclaw devices list
openclaw devices approve <requestId>
openclaw nodes status

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

openclaw --version
openclaw doctor
openclaw gateway status --json

openclaw gateway install
openclaw gateway status --json

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

wsl --install
# Or pick a distro explicitly:
wsl --list --online
wsl --install -d Ubuntu-24.04

Windows

핵심 요약

문서 구성

상세 내용

본문

Recommended: Windows Hub

What Windows Hub includes

First launch

Windows node mode

Local MCP mode

Native Windows CLI and Gateway

WSL2 Gateway

Or pick a distro explicitly:

Gateway auto-start before Windows login

Expose WSL services over LAN

트러블슈팅

The tray icon does not appear

Local setup fails

The app says pairing is required

Web chat cannot reach a remote Gateway

screen.snapshot, camera, or audio commands fail

Git or GitHub connectivity fails

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Windows

핵심 요약

문서 구성

상세 내용

본문

Recommended: Windows Hub

What Windows Hub includes

First launch

Windows node mode

Local MCP mode

Native Windows CLI and Gateway

WSL2 Gateway

Or pick a distro explicitly:

Gateway auto-start before Windows login

Expose WSL services over LAN

트러블슈팅

The tray icon does not appear

Local setup fails

The app says pairing is required

Web chat cannot reach a remote Gateway

screen.snapshot, camera, or audio commands fail

Git or GitHub connectivity fails

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드