🦞 01. 설치

Agent/01-Series/02-에이전트플랫폼/OpenClaw/images/openclaw-01-설치-diagram.svg

안 쓰는 PC를 바로 업무용 AI 작업기로 바꾸고 싶다면, 이 글은 설치 전에 길을 잘못 드는 순간만 먼저 잘라주는 1편이다. 공식 Getting Started는 OpenClaw를 5분 안에 올릴 수 있다고 안내하지만, 실제로 초보자가 더 자주 막히는 구간은 설치 명령 자체보다 장비 선택, Ubuntu 준비, Node 버전, PATH 반영 쪽이다.

핵심은 단순하다. 새 PC를 세팅하는 사람은 1~4단계부터, 이미 Ubuntu가 깔린 사람은 02편의 5단계부터 거의 바로 시작하면 된다. OpenClaw는 권한이 강한 도구라서, 평소 쓰는 메인 PC보다 분리된 장비나 별도 환경에서 시작하는 편이 안전하다. 이 문서에서는 초보자가 가장 자주 헷갈리는 시작점, 준비 순서, 실패 신호를 한 번에 정리한다.

안내: 본문은 생성형 AI로 초안을 정리하고, OpenClaw 공식 문서와 실제 설치 흐름을 교차 확인해 보정했습니다.

⚡ 먼저 이것부터: 나는 어디서 시작하면 될까?

결론부터 말하면, 이미 Ubuntu가 돌아가는 내 컴퓨터라면 5단계부터 시작해도 됩니다. 반대로 아직 장비나 운영체제가 준비되지 않았다면, 설치 명령을 먼저 복붙하는 것보다 01편에서 준비 경로를 자르는 편이 훨씬 덜 헤맨다.

시작점 빠른 선택

• A. 완전 처음 / 안 쓰는 PC에 새로 깔기
  → 1 → 2 → 3 → (4 선택) → 5 → 6 → 7

• B. 내 컴퓨터에 Ubuntu 이미 설치됨
  → 5 → 6 → 7 (1~3 건너뛰기 가능)

• C. VS Code/OpenCode는 아직 안 쓸 예정
  → 4단계는 선택사항 (나중에 붙여도 됨)

즉, 내 컴퓨터가 이미 Ubuntu 준비 상태라면 바로 02편으로 넘어가는 판단이 맞다. 01편은 “준비 경로를 줄이는 문서”라고 생각하면 이해가 쉽다.

칠판 판서형 치트시트

1. 새 PC면 1~4단계부터, 기존 Ubuntu면 02편으로 바로 이동
2. 01편은 환경 준비, 02편은 OpenClaw 설치와 첫 실행
3. VS Code/OpenCode는 선택사항, 나중에 붙여도 됨
4. 설치 확인은 which openclaw / openclaw -V / openclaw gateway status 3줄이면 끝

90초 판단표: 누가 무엇을 어떤 순서로 하면 되나

처음 읽는 사람은 설명을 다 보기 전에 내가 어떤 루트인지 먼저 결정하면 된다.

지금 내 상태	지금 할 일	먼저 안 해도 되는 것
안 쓰는 PC에 처음 세팅	USB 만들기 → Ubuntu 설치 → 기본 설정	OpenClaw 설치 명령 복붙
Ubuntu가 이미 있음	Node 버전 확인 → 02편으로 이동	USB/BIOS 작업
Node 18/20만 깔려 있음	nvm으로 24 또는 22.14+ 준비	전역 npm 재설치 단정
VS Code/OpenCode는 나중	4단계 생략 후 OpenClaw 먼저	확장 설치 강행

공식 Getting Started 기준으로는 설치 → onboarding → gateway 확인이 기본 순서다. 이 글은 그 전에, 그 순서로 바로 가도 되는 사람인지 먼저 가르는 필터 역할을 한다.

🚦 01편에서 02편으로 바로 넘어가는 클릭 경로

• 환경 준비만 필요하면: 이 문서(01) 끝까지 확인 후 02로 이동
• 빠르게 설치만 하고 싶으면: 아래 링크 순서로 바로 이동

1. 🦞 02. 시작하기(5~7단계)
2. 문제 생기면: 18. 텔레그램 5분 복구
3. 전체 허브로 돌아가기

---

⚡ 5분 빠른 체크리스트

• (신규 설치 시) USB 8GB 이상 준비
• (신규 설치 시) Ubuntu 24.04 ISO 다운로드 완료
• curl, git 설치 가능 인터넷 환경 확인
• 설치 후 openclaw gateway status 정상 확인
• openclaw dashboard가 열리는지 확인
• 막히면 openclaw doctor 1회 실행
• Memory 플러그인 활성화까지 완료

---

✅ 설치 성공 판정 (10초 체크)

여기서 헷갈리기 쉬운 포인트가 하나 있다. 01편만 끝낸 상태와 01편을 읽다가 바로 설치까지 끝낸 상태의 성공 판정은 다르다.

A. 01편 범위만 끝냈다면

아래 3가지만 맞으면 충분하다.

• Ubuntu가 정상 부팅된다.
• 터미널에서 curl, git 같은 기본 도구가 잡힌다.
• 다음 문서(02편)로 넘어갈 준비가 됐다.

B. 이 문서에서 바로 설치까지 이어서 했다면

공식 Getting Started와 Gateway CLI 기준으로, 아래 3줄이 통과되면 설치 확인은 거의 끝이다.

which openclaw
openclaw -V
openclaw gateway status

• which openclaw에 경로가 나오면 설치 경로 인식 성공
• openclaw -V가 버전을 보여주면 바이너리 정상
• openclaw gateway status가 정상 응답하면, 온보딩 뒤 로컬 Gateway 확인까지 이어진 상태다

C. 설치는 끝났는데 “어디까지 된 건지” 헷갈릴 때 보는 4줄

공식 Getting Started, Gateway CLI, doctor 기준으로는 아래 순서로 보면 거의 안 헤맨다.

which openclaw
openclaw -V
openclaw gateway status
openclaw doctor

• 앞 2줄만 통과하고 gateway status에서 멈추면, 설치는 됐지만 온보딩 또는 Gateway 쪽이 아직 안 끝난 상태일 가능성이 크다.
• gateway status는 서비스 상태와 RPC 응답을 같이 보기에, 단순히 바이너리가 있는지보다 한 단계 더 실제 상태에 가깝다.
• openclaw doctor는 설정 꼬임·채널 문제·서비스 상태를 한 번에 좁히는 데 유용하다. 특히 초보자는 원인을 추측하기보다 먼저 한 번 돌려서 범위를 줄이는 편이 빠르다.

실전에서는 이 구분이 중요하다. openclaw 명령이 보인다고 해서 설치가 완전히 끝난 것은 아니다. 바이너리 확인 → Gateway 확인 → doctor 확인 순서로 보면, “설치 문제”와 “온보딩/서비스 문제”를 빨리 분리할 수 있다.

여기서 자주 헷갈리는 실패 신호 4개

처음 설치할 때는 “안 된다”보다 어느 단계에서 멈췄는지를 나누는 편이 훨씬 빠르다.

1. USB 부팅 자체가 안 된다
   → BIOS/UEFI에서 부팅 순서가 USB보다 내장 디스크가 먼저일 가능성이 크다.
2. 우분투는 켜졌는데 curl·git 설치가 안 된다
   → 네트워크 연결 또는 패키지 저장소 갱신(sudo apt update)부터 다시 봐야 한다.
3. 설치는 끝났는데 openclaw 명령을 못 찾는다
   → PATH 반영 또는 셸 재시작 문제일 가능성이 높다.
4. openclaw는 보이는데 openclaw gateway status가 비정상이다
   → 설치 실패라기보다 온보딩 미완료, Gateway 미기동, 또는 설정 손상 쪽일 가능성이 더 크다. 공식 onboard CLI 기준으로 로컬 온보딩은 gateway.mode=local을 써야 하므로, 이 값이 빠진 상태를 정상으로 넘기지 말고 openclaw onboard --install-daemon 또는 openclaw doctor로 먼저 수습하는 편이 안전하다.

즉, 초보자 기준으로는 부팅 문제 / 네트워크 문제 / PATH 문제 / Gateway 분기 문제 네 갈래로 나누면 대부분 정리된다.

---

🚧 초보자가 가장 자주 막히는 2가지 (실전 사례)

사례 1) 설치는 됐는데 openclaw: command not found

• 원인: 셸 PATH가 갱신되지 않음
• 해결:

exec bash -l
export PATH="$(npm prefix -g)/bin:$PATH"
hash -r
openclaw -V

사례 2) Ubuntu 설치 후 한글 입력이 안 됨

• 원인: IBus Hangul 미설정
• 해결: 3단계 명령 실행 후, 재부팅 뒤 Input Sources에 Korean(Hangul) 추가

사례 3) 설치 스크립트는 끝났는데 gateway status에서 멈춤

• 상황: openclaw -V는 되는데, openclaw gateway status가 정상 응답을 주지 않음
• 흔한 원인: 온보딩을 아직 안 했거나, 서비스 설치가 덜 끝났거나, 설정 파일이 중간에 꼬임
• 빠른 복구 순서:

openclaw onboard --install-daemon
openclaw gateway status
openclaw doctor

• 검증 포인트: gateway status가 응답하고, 이어서 openclaw dashboard가 브라우저에서 열리면 설치 단계는 사실상 통과로 봐도 된다.
• 교훈: 이 경우는 “설치가 아예 안 됐다”기보다 설치 다음 단계가 멈춘 것인 경우가 많다.

---

📋 전체 로드맵 (초보자용)

1단계: USB 부팅 디스크 만들기 (신규 설치할 때만)
2단계: 우분투 설치 (신규 설치할 때만)
3단계: 기본 설정 (신규 설치할 때만)
4단계: VS Code + OpenCode 설치 (선택)
5단계: OpenClaw 설치 (핵심)
6단계: 웹 인터페이스 접속
7단계: 기억(Memory) 활성화 (권장)

---

Node 버전은 24와 22 중 무엇을 고르면 되나

공식 Getting Started 기준으로는 Node 24 권장, Node 22.14+도 지원이다. 그래서 새로 시작하는 사람은 먼저 아래 기준으로 고르면 된다.

• 완전 신규 세팅: 공식 기본값에 맞춰 Node 24로 가면 가장 단순하다.
• 기존 자동화/가이드와 맞춰야 함: 이미 22 기반으로 굴러가는 스크립트가 있으면 22.14+로 맞추는 편이 덜 흔들린다.
• 지금 Node 18/20을 쓰고 있음: 전역 덮어쓰기보다 nvm으로 버전을 나눠 쓰는 편이 안전하다.

실전에서는 여기서 많이 갈린다. 같은 장비에서 Node를 마구 덮어쓰면 OpenClaw 문제가 아니라 기존 npm 글로벌 경로와 PATH가 꼬이는 문제가 생긴다. 그래서 설치보다 먼저 nvm을 쓰는 이유가 여기 있다.

미니 사례 1) 기존 개발 노트북에 바로 설치했다가 PATH만 꼬인 경우

• 상황: 기존 Node 18 작업환경이 있는 노트북에 바로 설치
• 실제 문제: OpenClaw 자체보다 npm prefix -g와 셸 PATH가 섞임
• 복구: nvm으로 OpenClaw용 Node를 분리하고 새 로그인 셸에서 다시 확인
• 교훈: “설치 실패”처럼 보여도, 실제로는 버전 격리 문제인 경우가 많다

미니 사례 2) 안 쓰는 미니 PC에 새로 올렸더니 오히려 더 빨리 끝난 경우

• 상황: 메인 업무 환경 대신 분리된 장비에 새 Ubuntu 설치
• 실제 장점: 기존 Node/npm 설정 충돌이 거의 없어 설치 경로가 단순함
• 실제 흐름: BIOS/USB 구간만 넘기면 이후는 공식 순서대로 빠르게 진행됨
• 교훈: 처음엔 번거로워 보여도, 분리 환경이 전체 작업 시간은 줄이는 경우가 많다

🚀 내 컴퓨터 바로 설치 루트 (요약)

이미 OS 준비가 끝난 상태라면, 아래만 따라가도 됩니다.

Ubuntu (bash)

command -v node >/dev/null || echo NO_NODE
command -v npm >/dev/null || echo NO_NPM
command -v openclaw >/dev/null || echo NO_OPENCLAW

NO_NODE 또는 NO_NPM이 보이면:

curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22
node -v
npm -v

curl -fsSL https://openclaw.ai/install.sh | bash
exec bash -l
which openclaw
openclaw -V
openclaw onboard --install-daemon
openclaw gateway status

공식 Onboarding CLI 설명대로 openclaw onboard --install-daemon은 관리형 로컬 Gateway 설치 경로를 함께 탄다. 그리고 공식 Gateway CLI 기준으로 openclaw gateway status가 살아 있으면, 이제 설치가 아니라 연결/페어링/대시보드 확인 단계로 넘어가면 된다.

설치가 됐는데 openclaw를 못 찾으면:

export PATH="$(npm prefix -g)/bin:$PATH"
hash -r
which openclaw
openclaw -V

자세한 5~7단계 설명은 02편에서 이어집니다. → 🦞 02. 시작하기

---

1단계: USB 부팅 디스크 만들기 (~20분)

필요한 것

• USB 메모리: 최소 8GB (빈 거)
• 컴퓨터: 인터넷 연결 가능한 거 (지금 쓰고 있는 컴퓨터로 OK)
• 다운로드 받을 파일: Ubuntu Desktop 24.04 LTS

단계별

1.1 Ubuntu 다운로드

1. 다음 사이트 접속: https://ubuntu.com/download/desktop
2. Ubuntu 24.04 LTS 버전 다운로드
3. ISO 파일 (약 4GB) 다운로드됨 → 기다려야 함

1.2 USB 부팅 도구 설치

• Windows: Rufus (https://rufus.ie/)
• Mac: BalenaEtcher (https://etcher.balena.io/)
• Linux: BalenaEtcher 또는 Startup Disk Creator

1.3 USB에 우분투 담기 (예시: Rufus)

1. USB를 컴퓨터에 연결
2. Rufus 실행
3. “장치”에서 USB 선택
4. “선택” 버튼 클릭 → 다운로드한 Ubuntu ISO 파일 선택
5. “시작” 클릭 → “삭제 모드” 확인 → OK
6. 완료될 때까지 기다림

⚠️ 주의: USB의 모든 데이터가 삭제됩니다!

---

2단계: 우분투 설치 (~40분)

BIOS 진입 방법

컴퓨터 부팅할 때 키를 연타:

브랜드	진입 키
Dell	F2
HP	F10
Lenovo	F2 / Enter
Samsung	F2 / F10
ASUS	F2 / DEL
Mac	Option/Alt 키

단계별

2.1 USB로 부팅

1. USB를 안 쓰는 컴퓨터에 연결
2. 컴퓨터 켜기
3. BIOS/UEFI 진입
4. 부팅 순서(Boot Order) 설정 → USB를 1순위로
5. 저장 후 재부팅

2.2 Ubuntu 설치 시작

1. “Try Ubuntu” (시험) 또는 “Install Ubuntu” (설치) 선택
2. 언어: 한국어 선택 → 설치 클릭

2.3 설치 옵션 선택

• 키보드 레이아웃: Korean
• 설치 유형:
  • 디스크 지우고 Ubuntu 설치 (초보자 추천)
  • 또는 공간을 만들어 설치 (데이터 보존 필요 시)
• 사용자 설정:
  • 이름: (자유롭게)
  • 컴퓨터 이름: (자유롭게, 예: openclaw)
  • 사용자 이름: (영문 소문자, 예: user)
  • 비밀번호: (반드시 기억할 것!)

2.4 설치 완료

• 설치 진행 → 완료되면 재부팅
• USB 제거 후 Enter

---

3단계: 기본 설정 (~30분)

3.1 첫 부팅 & 업데이트

터미널 열기 (Ctrl+Alt+T):

## 시스템 업데이트
sudo apt update && sudo apt upgrade -y
 
## 필요한 도구 설치
sudo apt install -y git curl wget

3.2 한글 입력기 설치

## 한글 입력기 (IBus + Hangul)
sudo apt install -y ibus-hangul ibus-gtk ibus-gtk3
 
## 재부팅 후 설정
## Settings → Keyboard → Input Sources → Korean (Hangul) 추가

---

4단계: VS Code + OpenCode 플러그인 설치 (~15분)

VS Code와 OpenCode 플러그인을 사용하면 OpenClaw와 함께 코딩 워크플로우를 훨씬 편하게 운영할 수 있습니다.

💡 왜 필요한가? OpenClaw는 채팅/자동화를 담당하고, VS Code + OpenCode는 코드 편집/실행 환경을 담당합니다.

4.1 VS Code 설치

# Ubuntu 기준
sudo snap install code --classic

설치 후 실행:

code --version

4.2 OpenCode 플러그인 설치

1. VS Code 실행
2. Extensions(확장) 열기 (Ctrl+Shift+X)
3. OpenCode 검색 후 설치
4. 설치 후 VS Code 재시작

4.3 기본 확인

• VS Code가 정상 실행되는지
• OpenCode 확장이 활성화되는지
• 프로젝트 폴더를 열어 AI 보조 기능이 보이는지

---

✅ 여기까지가 01편 범위 (환경 준비)

01편은 **1~4단계(환경 준비)**까지를 다룹니다.

• 1~3단계: 우분투 설치/기본 세팅
• 4단계: VS Code + OpenCode(선택)

OpenClaw 설치와 첫 실행은 다음 문서에서 이어집니다.

➡️ 다음: 🦞 02. 시작하기 (5~7단계)

30초 이동 버튼

• 지금 바로 설치로 넘어가기 → 02. 시작하기
• 막히면 즉시 복구 가이드 → 18. 텔레그램 5분 복구
• 전체 흐름 다시 보기 → OpenClaw 허브

---

📊 전체 소요 시간 (01편: 1~4단계)

단계	예상 시간	난이도
USB 디스크 만들기	20분	⭐☆☆☆☆
우분투 설치	40분	⭐⭐☆☆☆
기본 설정	30분	⭐⭐☆☆☆
VS Code + OpenCode 설치(선택)	15분	⭐☆☆☆☆
총합	~1시간 30분

OpenClaw 설치/실행(5~7단계)은 02편에서 진행합니다.

---

📚 참고 링크

• Ubuntu 다운로드: https://ubuntu.com/download/desktop
• Rufus (Windows용): https://rufus.ie/
• VS Code: https://code.visualstudio.com/
• OpenClaw 공식 문서: https://docs.openclaw.ai

---

📚 다음 읽기

• 🦞 02. 시작하기 — 설치 직후 첫 세팅
• 🦞 03. 핵심개념 — Workspace·Heartbeat·보안 구조
• 🦞 38. 1클릭 설치 가이드 — 더 빠른 설치 경로

---

작성일: 2026-02-02 수정일: 2026-04-14 (설치 완료 판정 4줄 + gateway status/doctor 분기 + 온보딩 미완료 사례 보강)