OpenClaw 설치 가이드 (Windows / WSL2 Ubuntu)

대상

• Windows 10/11

• WSL2 + Ubuntu (권장: Ubuntu 24.04 LTS)

• Bash 기준

참고

• 설치/온보딩 과정에서 y 또는 yes 입력이 필요할 수 있습니다.

• 이 가이드는 WSL2(Ubuntu) 안에서 OpenClaw를 설치/운영하는 흐름입니다.

0) WSL2 설치 및 확인 (Windows 측)

0-1) WSL2 설치 (관리자 PowerShell)

wsl --install -d Ubuntu-24.04

0-2) 설치 확인

wsl -l -v

• Ubuntu-24.04 가 보이고 VERSION이 2면 OK

0-3) Ubuntu 실행

• 시작 메뉴에서 Ubuntu 실행 또는

wsl -d Ubuntu-24.04

1) (선택) Ubuntu 환경 확인

Ubuntu(WSL) 터미널에서:

lsb_release -a
uname -m

• 일반적으로 x86_64가 출력됩니다(WSL은 PC CPU 아키텍처를 따름).

2) OpenClaw 설치 (WSL2 Ubuntu)

설치 스크립트가 환경을 점검하고 필요한 의존성을 처리합니다.

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

2-1) 설치 확인

openclaw --version

2-2) (자주 발생) openclaw: command not found 해결

설치 위치가 ~/.local/bin 등에 잡혔는데 PATH가 반영되지 않은 경우가 있습니다.

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
which openclaw

zsh를 쓰는 경우:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
which openclaw

3) 온보딩 시작 (Gateway 데몬 설치 권장)

백그라운드로 항상 실행되게 하려면 --install-daemon을 권장합니다.

openclaw onboard --install-daemon

• 원한다면 openclaw onboard만으로도 진행 가능합니다.

4) 위험성 안내(알럿) 확인

온보딩 중 아래 문구가 뜨면 Yes로 이동 후 Enter:

I understand this is powerful and inherently risky. Continue?
│  ○ Yes / ● No

5) 온보딩 모드 선택

일단 빠르게 붙이고 나중에 수정할 거면 QuickStart 추천:

Onboarding mode
│  ● QuickStart (Configure details later via openclaw configure.)
│  ○ Manual

6) 기존 설정값 처리

이미 설정이 있다면 Use existing values, 처음이면 Update values로 세팅:

Config handling
│  ● Use existing values
│  ○ Update values
│  ○ Reset

7) 모델/인증 제공자 선택: OpenAI (Codex OAuth)

ChatGPT(OAuth) 기반으로 연결하려면 OpenAI를 선택합니다. (API Key를 선택하면 OpenAI Platform API 과금 흐름이 될 수 있습니다.)

Model/auth provider
│  ● OpenAI (Codex OAuth + API key)
│  ○ Anthropic
│  ○ Google
│  ○ ...
│  ○ Skip for now

8) OpenAI 인증 방식: Codex (ChatGPT OAuth)

아래에서 OpenAI Codex (ChatGPT OAuth) 선택:

OpenAI auth method
│  ● OpenAI Codex (ChatGPT OAuth)
│  ○ OpenAI API key
│  ○ Back

선택하면 브라우저에서 ChatGPT 로그인/승인이 뜨고, 완료되면 다음 메시지가 보입니다:

Authentication successful. Return to your terminal to continue.

8-1) 기본 모델 선택

가장 최신/권장 모델(예: openai-codex/gpt-5.3-codex)을 선택합니다.

Default model
│  ● Keep current (openai-codex/gpt-5.3-codex)
│  ○ Enter model manually
│  ○ openai-codex/gpt-5.1
│  ○ openai-codex/gpt-5.2-codex
│  ○ openai-codex/gpt-5.3-codex

9) 채널 선택: Telegram

봇과의 소통 채널로 Telegram을 선택합니다.

Select channel (QuickStart)
│  ● Telegram (Bot API) (recommended · configured)
│  ○ Discord (Bot API)
│  ○ Slack (Socket Mode)
│  ○ ...
│  ○ Skip for now

9-1) Telegram 봇 토큰 만들기 (BotFather)

1. Telegram 앱 열기

2. @BotFather 검색

3. /start

4. /newbot

5. 봇 이름(name)과 유저네임(username) 설정

6. 발급된 Bot Token을 OpenClaw가 입력하라고 할 때 터미널에 붙여넣기

10) 스킬(Skills) 설정은 일단 Skip (선택)

처음엔 구동만 목표라면 No로 넘겨도 됩니다.

Configure skills now? (recommended)
│  ○ Yes / ● No

11) Gateway 서비스(데몬) 처리

이미 설치되어 있다면 보통 Restart:

Gateway service already installed
│  ● Restart
│  ○ Reinstall
│  ○ Skip

12) 관리 화면(TUI / Web UI) 선택

웹에서 관리하려면 Open the Web UI 선택을 추천합니다.

How do you want to hatch your bot?
│  ○ Hatch in TUI (recommended)
│  ● Open the Web UI
│  ○ Do this later

기본 Web UI 주소(로컬):

• WSL 내부 기준: http://127.0.0.1:18789/

• Windows 브라우저에서도 보통 그대로 접속 가능: http://127.0.0.1:18789/

13) Telegram 페어링(화이트리스트 승인)

OpenClaw는 기본적으로 승인된 사용자만 Telegram DM 가능합니다.

봇에게 DM을 보내면 아래 메시지가 발생합니다:

OpenClaw: access not configured.

Your Telegram user id: 7******
Pairing code: 2D*****
Ask the bot owner to approve with:
openclaw pairing approve telegram <code>

터미널에서 표시된 code로 승인:

openclaw pairing approve telegram 2D****

승인된 사용자 목록 확인:

openclaw pairing list telegram

14) 완료

이제 Telegram에서 봇에게 질문하면 OpenClaw가 응답합니다.

실행 상태 확인:

openclaw status

로그 확인(선택, 포그라운드 실행):

openclaw gateway --port 18789 --verbose

세션연결이 안되는 경우

토큰이 포함된 URL에 들어가기

openclaw dashboard --no-open

토큰이 나온 URL그대로 넣기

Dashboard URL: http://127.0.0.1:18789/#token=9dce7a3a7eee3xxxxx
Copied to clipboard.
No GUI detected. Open from your computer:
ssh -N -L 18789:127.0.0.1:18789 sori@<host>
Then open:
http://localhost:18789/
http://localhost:18789/#token=9dce7a3a7eee3xxxxxx
Docs:
https://docs.openclaw.ai/gateway/remote
https://docs.openclaw.ai/web/control-ui

추가1. 윈도우에 설치하여 개인파일 Access 못하게 하는법

WSL(Ubuntu)에서:

sudo nano /etc/wsl.conf

아래 내용을 넣고 저장(없으면 새로 작성):

[automount]
enabled = false

저장은 나올때 Ctrl + X -> Y -> Enter

그 다음 Windows PowerShell에서 WSL을 완전히 재시작:

wsl --shutdown

이후 다시 Ubuntu 실행:

wsl -d Ubuntu-24.04

c드라이브 없는지 확인

ls /mnt

추가2. 최신버전에 CLI 연결시 1008 paring required 오류 발생시 해결법

rm -rf ~/.openclaw/identity ~/.openclaw/devices
mkdir -p ~/.openclaw/identity ~/.openclaw/devices

identity 강제 삭제후 Token을 가져와서 device 에 승인하기

TOKEN="$(jq -r '.gateway.auth.token' ~/.openclaw/openclaw.json)"
openclaw devices list --url ws://127.0.0.1:18789 --token "$TOKEN"

추가3. CLI 기본토큰으로 게이트웨이 probe가 안되는경우

TOKEN="$(jq -r '.gateway.auth.token' ~/.openclaw/openclaw.json)"
export OPENCLAW_GATEWAY_TOKEN="$TOKEN"
export OPENCLAW_GATEWAY_URL="ws://127.0.0.1:18789"

openclaw gateway probe
openclaw devices list

추가4. 텔레그램이 계속 먹통인경우 node가 ipv6로 전송을해서 그런다.

IPv4 주소 뽑기:

getent ahostsv4 api.telegram.org | head -n 1

예를 들어 출력이 149.154.xx.xx STREAM api.telegram.org 이런 식이면, 맨 앞 IP만 사용.

hosts에 추가:

sudo sh -c 'echo "<IPv4주소> api.telegram.org" >> /etc/hosts'

서비스 재시작:

systemctl --user restart openclaw-gateway

===

(팁) WSL2에서 데몬이 기대대로 안 살아있을 때

WSL은 배경 서비스 동작이 PC/설정에 따라 다를 수 있습니다.

• WSL 터미널을 닫으면 프로세스가 종료되는 설정/상황이 있을 수 있음

• 이 경우 아래 중 하나로 운영:

• WSL 터미널을 유지(또는 Windows 시작프로그램/작업 스케줄러로 WSL 실행)

• tmux/screen으로 세션 유지

• systemd 활성화(가능한 WSL 배포판/설정에서)