English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Platforms overview

Windows

OpenClaw는 네이티브 Windows와 WSL2를 모두 지원합니다. WSL2가 더 안정적인 경로이며 전체 경험에 권장됩니다. CLI, Gateway, 도구가 Linux 내부에서 완전한 호환성으로 실행됩니다. 네이티브 Windows는 핵심 CLI와 Gateway 사용에 동작하지만, 아래에 몇 가지 주의 사항이 있습니다.

네이티브 Windows 컴패니언 앱은 계획되어 있습니다.

WSL2(권장)

네이티브 Windows 상태

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

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

  • install.ps1을 통한 웹사이트 설치 프로그램
  • openclaw --version, openclaw doctor, openclaw plugins list --json 같은 로컬 CLI 사용
  • 다음과 같은 내장 local-agent/provider 스모크 테스트:
openclaw agent --local --agent main --thinking low -m "Reply with exactly WINDOWS-HATCH-OK."

현재 주의 사항:

  • openclaw onboard --non-interactive는 --skip-health를 전달하지 않는 한 여전히 연결 가능한 로컬 Gateway를 기대합니다
  • openclaw onboard --non-interactive --install-daemon과 openclaw gateway install은 먼저 Windows 예약 작업을 시도합니다
  • 예약 작업 생성이 거부되면 OpenClaw는 사용자별 Startup 폴더 로그인 항목으로 대체하고 즉시 Gateway를 시작합니다
  • schtasks 자체가 멈추거나 응답하지 않으면 이제 OpenClaw는 해당 경로를 빠르게 중단하고 영원히 멈추는 대신 대체 경로로 전환합니다
  • 예약 작업은 더 나은 감독자 상태를 제공하므로 사용 가능할 때는 여전히 선호됩니다

Gateway 서비스 설치 없이 네이티브 CLI만 원한다면 다음 중 하나를 사용하세요.

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

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

openclaw gateway install
openclaw gateway status --json

예약 작업 생성이 차단되더라도 대체 서비스 모드는 현재 사용자의 Startup 폴더를 통해 로그인 후 자동 시작됩니다.

Gateway

Gateway 서비스 설치(CLI)

WSL2 내부에서:

openclaw onboard --install-daemon

또는:

openclaw gateway install

또는:

openclaw configure

프롬프트가 표시되면 Gateway 서비스를 선택하세요.

복구/마이그레이션:

openclaw doctor

Windows 로그인 전 Gateway 자동 시작

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

1) 로그인 없이 사용자 서비스 계속 실행

WSL 내부에서:

sudo loginctl enable-linger "$(whoami)"

2) OpenClaw Gateway 사용자 서비스 설치

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

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

WSL에는 자체 가상 네트워크가 있습니다. 다른 머신이 WSL 내부에서 실행 중인 서비스(SSH, 로컬 TTS 서버 또는 Gateway)에 접근해야 한다면 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 Firewall을 통해 포트를 허용하세요(한 번만).

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).
  • 원격 노드는 도달 가능한 Gateway 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
# Or pick a distro explicitly:
wsl --list --online
wsl --install -d Ubuntu-24.04

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

2) systemd 활성화(Gateway 설치에 필요)

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 build
pnpm ui:build
pnpm openclaw onboard --install-daemon

최초 온보딩 대신 소스에서 개발하는 경우 설정의 소스 개발 루프를 사용하세요.

pnpm install
# First run only (or after resetting local OpenClaw config/workspace)
pnpm openclaw setup
pnpm gateway:watch

전체 가이드: 시작하기

Windows 컴패니언 앱

아직 Windows 컴패니언 앱은 없습니다. 구현을 돕고 싶다면 기여를 환영합니다.

Git 및 GitHub 연결(기여자)

일부 네트워크는 GitHub로의 HTTPS를 차단하거나 제한합니다. git clone이 시간 초과나 연결 재설정으로 실패하면 다른 네트워크, VPN 또는 조직에서 제공하는 HTTP/HTTPS 프록시를 시도하세요.

브라우저 디바이스 흐름 중 gh auth login이 실패하면(예: github.com:443에 도달하는 시간 초과) 대신 개인 액세스 토큰으로 인증하세요.

  1. 최소한 repo 범위(클래식 PAT) 또는 동등한 세분화된 액세스 권한이 있는 토큰을 만드세요.
  2. 현재 세션의 PowerShell에서:
$env:GH_TOKEN="<your-token>"
gh auth status
gh auth setup-git
  1. gh auth status가 누락된 read:org에 대해 경고하면 해당 범위를 포함하는 토큰을 만들고 변수를 다시 할당하세요.
$env:GH_TOKEN="<your-token-with-repo-and-read:org>"
gh auth status

gh auth refresh -s read:org는 gh auth login으로 인증했고 새로 고칠 저장된 자격 증명이 있는 경우에만 적용됩니다(GH_TOKEN 사용 시에는 해당하지 않음).

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

관련 항목