🦞 02. 시작하기

Agent/🚀 OpenClaw/images/openclaw-02-시작-diagram.svg

설치 후 10분 안에 막히는 구간을 끝내는 페이지다. 공식 Getting Started 기준으로 **딱 3단계(Node 확인 → OpenClaw 설치 → 온보딩/게이트웨이 확인)**만 통과하면 바로 채팅이 시작된다. 이 문서는 그 3단계를 운영체제별로 나누고, 각 단계에서 자주 막히는 오류를 바로 잡는 방법까지 함께 정리한다.

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

flowchart LR
A[Node 버전 확인] --> B[OpenClaw 설치]
B --> C[온보딩 + 게이트웨이 시작]
C --> D[대시보드 접속]
D --> E[첫 메시지 전송]

칠판 판서형 치트시트

1. Node 24 권장, 22.14+도 지원 — node -v로 먼저 확인
2. 설치는 curl ... install.sh | bash 한 줄 + 셸 재시동
3. 온보딩은 openclaw onboard --install-daemon (2분)
4. 확인은 gateway status + openclaw dashboard 두 개면 충분
5. 막히면 openclaw doctor를 먼저 돌려라

30초 진단표: 지금 바로 해결

증상	바로 실행	끝나면
openclaw: command not found	PATH 재로딩 → exec bash -l	온보딩
pairing required	로컬 게이트웨이로 전환 → gateway restart	devices approve
device token mismatch	토큰 캐시 백업 → gateway restart	openclaw tui
Relay 제어 불가	탭에서 Relay ON 배지 확인	12편 심화

빠른 이동

• 처음부터 따라하기: 아래 운영체제별 블록부터 순서대로 실행
• 설치 오류 먼저 해결: OpenClaw 설치 오류 복구
• 설치 후 바로 다음 편: 🦞 03. 핵심개념
• 더 빠른 설치 경로(1클릭): 🦞 38. 1클릭 설치 가이드
• 트러블슈팅 전체: Troubleshooting 허브

🎬 영상으로 따라하기

영상을 켜두고 이 문서의 블록을 위에서 아래로 한 줄씩 실행하면 된다. 원격 설정에서 나오는 IP·경로·계정명은 반드시 본인 환경값으로 교체한다.

---

Node 버전: 24와 22 중 무엇을 선택할까

공식 Getting Started 기준으로 Node 24 권장, Node 22.14+도 지원이다. 처음 세팅하는 장비라면 Node 24로 가는 게 가장 단순하다.

상황	권장 버전	이유
완전 신규 세팅	Node 24	공식 기본값, 호환성 이슈 최소
기존 자동화가 Node 22 기반	Node 22.14+	기존 스크립트 호환 유지
nvm으로 여러 버전 관리 중	현재 프로젝트에 맞춤	nvm use로 전환

핵심: Node 18/20만 깔려 있다면 전역 덮어쓰기보다 nvm으로 버전을 분리하는 편이 안전하다. 한 장비에서 Node를 마구 덮어쓰면 OpenClaw 문제가 아니라 PATH가 꼬이는 문제가 먼저 터진다.

---

실행 원칙

• 명령은 한 줄씩 실행한다
• 블록은 한 블록씩 순서대로 실행한다
• 한 줄 체이닝(... bash && openclaw onboard ...)은 피한다
• 막히면 **openclaw doctor**를 먼저 돌려 원인을 좁힌다

---

Ubuntu 빠른 실행 (bash)

1) 사전 확인

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

2) NO_NODE/NO_NPM이면 Node 설치

curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
source ~/.bashrc
nvm install 24
nvm use 24
node -v   # v24.x 확인
npm -v

기존 환경이 Node 22 기반이면 nvm install 22로 대체해도 된다.

3) OpenClaw 설치

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

4) 온보딩 + 게이트웨이 시작

openclaw onboard --install-daemon
openclaw gateway status

onboard --install-daemon은 모델 제공자 선택, API 키 입력, 로컬 게이트웨이 설정을 대화형으로 진행한다. 약 2분이면 끝난다.

5) 대시보드 확인

openclaw dashboard

브라우저에서 Control UI가 열리면 설치가 완료된 것이다. 여기서 첫 메시지를 보내 응답이 오는지 확인한다.

6) openclaw를 못 찾을 때

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

---

MacBook 빠른 실행 (zsh)

1) 사전 확인

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

2) NO_NODE/NO_NPM이면 Node 설치

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

3) OpenClaw 설치

curl -fsSL https://openclaw.ai/install.sh | bash
exec zsh -l
which openclaw
openclaw -V

4) 여전히 안 되면 (실전 복구)

ls -l "$(npm prefix -g)/bin/openclaw"
npm i -g openclaw@latest
export PATH="$(npm prefix -g)/bin:$PATH"
rehash
which openclaw
openclaw -V

5) 온보딩 + 게이트웨이 + 대시보드

openclaw onboard --install-daemon
openclaw gateway status
openclaw dashboard

---

Windows 빠른 실행 (PowerShell)

공식 Getting Started에서 WSL2를 권장하지만, 네이티브 Windows도 지원한다.

1) 설치

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

2) 온보딩 + 확인

openclaw onboard --install-daemon
openclaw gateway status
openclaw dashboard

WSL2에서는 Ubuntu 블록을 그대로 따라가면 된다. 자세한 내용은 Windows 가이드 참조.

---

Synology NAS (DSM) 빠른 실행

DSM에서 자주 막히는 지점은 두 가지다.

• nvm이 현재 셸에서 로드되지 않아 nvm install이 안 되는 문제
• 글로벌 npm 권한(EACCES)으로 npm i -g openclaw가 실패하는 문제

핵심은 .profile에서 nvm을 안정적으로 로드하고, ~/.npmrc의 prefix/globalconfig 충돌을 제거하는 것이다.

1) Node 설치 전 nvm 로드

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && . "$NVM_DIR/bash_completion"
 
nvm install 22
nvm use 22
nvm alias default 22
node -v
npm -v

node -v가 v22.x로 보이고 nvm ls에서 활성 버전에 *가 붙으면 다음 단계로 진행한다.

2) 설정 영구 적용

cat >> ~/.profile <<'EOF'
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && . "$NVM_DIR/bash_completion"
EOF
 
source ~/.profile

3) ~/.npmrc prefix 충돌 제거 (중요)

source ~/.profile 시 아래 경고가 뜨면 먼저 충돌을 정리한다.

Your user's .npmrc file ... has a globalconfig and/or a prefix setting, which are incompatible with nvm

nvm use --delete-prefix v22.22.0 --silent
npm config delete prefix
npm config delete globalconfig
cat ~/.npmrc   # prefix=, globalconfig= 줄이 남아 있으면 직접 삭제
source ~/.profile

4) OpenClaw 설치 + 확인

nvm use v22.22.0
npm i -g openclaw@latest
which openclaw
openclaw -V
openclaw doctor
openclaw onboard --install-daemon
openclaw gateway status

5) installer의 PATH 경고 해결 (DSM 필수)

Synology DSM은 .bashrc가 없는 경우가 많아 .profile에 넣는 것이 정석이다.

cat >> ~/.profile <<'EOF'
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && . "$NVM_DIR/bash_completion"
export PATH="$NVM_DIR/versions/node/$(nvm version default)/bin:$PATH"
EOF
 
source ~/.profile
hash -r
which node && which npm && which openclaw

6) 여전히 안 되면

nvm ls
npm config get prefix
npm config get globalconfig
echo "$PATH"

정상 기준: nvm ls에서 v22.22.0 옆에 * 표시, npm config get prefix가 nvm 경로를 가리키고, which openclaw가 nvm 버전의 npm bin 경로를 가리키면 성공이다.

---

온보딩 직후 필수 2단계

openclaw onboard --install-daemon이 끝난 직후 아래 두 단계를 먼저 처리한다.

1) TUI 디바이스 페어링 승인

openclaw devices list
openclaw devices approve --latest
openclaw tui

2) Telegram 첫 DM 페어링 승인

봇이 DM으로 보여준 코드가 있으면:

openclaw pairing approve telegram <PAIRING_CODE>

코드를 못 봤으면 openclaw pairing list telegram으로 확인 후 승인한다.

---

자주 막히는 오류 3가지 (실전 복구)

① pairing required

에러: gateway connect failed: Error: pairing required

원인은 대부분 원격 게이트웨이에 붙으려는데 디바이스 승인이 안 된 상태다.

로컬로 즉시 복구:

openclaw config get gateway.remote.url
openclaw config unset gateway.remote.url
openclaw gateway start
openclaw gateway status

원격을 계속 쓸 때: 게이트웨이 있는 쪽에서 openclaw devices approve --latest 실행.

② device token mismatch

에러: unauthorized: device token mismatch (rotate/reissue device token)

원인은 보통 오래된 로컬 디바이스 토큰 캐시다.

복구 순서:

openclaw config unset gateway.remote.url
openclaw config unset gateway.remote.token
openclaw config unset gateway.remote.password
 
# macOS LaunchAgent 환경변수 정리
launchctl unsetenv OPENCLAW_GATEWAY_TOKEN 2>/dev/null || true
launchctl unsetenv OPENCLAW_GATEWAY_PASSWORD 2>/dev/null || true
 
# 오래된 토큰 캐시 백업
STATE_DIR="${OPENCLAW_STATE_DIR:-$HOME/.openclaw}"
TS="$(date +%s)"
mkdir -p "$STATE_DIR/identity/backup-$TS"
mv "$STATE_DIR/identity/device-auth.json" "$STATE_DIR/identity/backup-$TS/" 2>/dev/null || true
mv "$STATE_DIR/identity/device.json" "$STATE_DIR/identity/backup-$TS/" 2>/dev/null || true
 
openclaw gateway restart
openclaw gateway status
openclaw tui

그래도 안 되면 openclaw devices approve --latest로 승인을 다시 시도한다.

③ 브라우저 Relay 인증 충돌 / 연결 실패

증상: 확장 프로그램으로 로그인은 됐는데 브라우저 연결이 안 됨.

이 이슈는 계정 로그인 문제보다 Relay 탭 연결 상태(ON 배지) 문제인 경우가 많다.

5분 점검 순서:

1. OpenClaw를 실행한 같은 로컬 PC의 Chrome인지 확인
2. 제어할 탭에서 Relay 아이콘을 눌러 배지 ON 상태로 전환
3. Chrome 프로필이 여러 개면 우선 1개만 열고 재시도
4. 게이트웨이 재시작 후 탭 새로고침: openclaw gateway restart
5. 그래도 안 되면 확장 재설치 + 브라우저 재로그인 후 다시 ON 탭 연결

관련 문서: 12. 브라우저 릴레이 연동 구조

---

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

아래 3줄이 모두 정상 응답하면 설치는 끝이다.

openclaw -V
openclaw gateway status
openclaw dashboard

• openclaw -V → 버전 숫자가 보이면 설치 경로 인식 성공
• gateway status → 게이트웨이가 18789 포트에서 리스닝 중이면 정상
• dashboard → 브라우저에서 Control UI가 열리면 전체 구동 완료

---

완료 후 다음 단계

flowchart LR
A[설치 완료] --> B{다음에 뭘 할까?}
B --> C[핵심 개념 이해]
B --> D[채널 연결]
B --> E[도구 살펴보기]
C --> F[03. 핵심개념]
D --> G[Telegram / Discord / WhatsApp]
E --> H[Browser / Skills / Cron]

읽기 순서 추천

1. 🦞 03. 핵심개념 — Workspace·Heartbeat·보안 구조
2. 🦞 06. Cron Job — 정기 작업 자동화
3. 🦞 18. 텔레그램 5분 복구 — 채널 연결 후 가장 자주 쓰는 복구법
4. 🦞 12. 브라우저 릴레이 — 브라우저 자동화 설정
5. 🦞 21. Archive PARA+Z — 파일 정리 체계

문제가 생기면

• 설치 오류 복구
• gateway token mismatch 해결
• Troubleshooting 허브
• Agent 허브

---

작성일: 2026-02-02 수정일: 2026-03-29 (Node 24 권장 반영, Windows 설치 경로 추가, 칠판 치트시트·Mermaid 추가, 공식 Getting Started/onboard 기준 동기화, 대시보드 확인 단계 추가)