2부·6장 npm 한 줄 설치와 onboarding 마법사
2부·6장 npm 한 줄 설치와 onboarding 마법사
지난 장에서 우리는 준비물을 끝냈다. 이제 정말 설치할 차례다. 여기서 가장 중요한 사실부터 말하자. OpenClaw 설치는 생각보다 짧고, 헷갈리는 지점은 설치 그 자체보다 설치 직후 무엇을 해야 하는지에 있다. npm install -g openclaw@latest만 치고 끝났다고 생각하면, 마치 오븐만 사 놓고 빵이 왜 안 나오냐고 묻는 셈이 된다.
OpenClaw는 CLI를 깔아야 하고, 그다음 Gateway를 백그라운드에서 살아 있게 만들어야 하며, 마지막으로 온보딩 마법사에서 두뇌와 채널을 연결해야 비로소 "일하는 에이전트"가 된다.12 이 장에서는 그 흐름을 가장 빠른 경로로 끝낸다.
오늘 할 일은 딱 네 단계다
이번 장의 목표는 복잡한 선택지를 늘어놓는 것이 아니다. 가장 짧은 성공 루트를 밟는 것이다.
첫째, CLI를 설치한다. 둘째, 온보딩 마법사를 실행한다. 셋째, --install-daemon으로 Gateway를 자동 시작 서비스에 등록한다. 넷째, 설치가 제대로 되었는지 확인한다.
여기서 기억할 문장은 하나면 충분하다.
설치 명령은 반쪽이고, 온보딩이 나머지 반쪽이다.
가장 빠른 길: 설치 스크립트 한 번에 끝내기
공식 문서는 가장 빠른 설치 경로로 인스톨러 스크립트를 권장한다. 이 스크립트는 운영체제를 감지하고, 필요하면 Node를 확인하거나 설치하고, OpenClaw CLI를 준비한 뒤, 곧바로 온보딩까지 이어 준다.1 처음 설치라면 솔직히 이 길이 제일 편하다.
macOS, Linux, WSL2에서는 다음 한 줄이면 된다.
curl -fsSL https://openclaw.ai/install.sh | bash네이티브 Windows PowerShell에서는 다음 명령을 쓴다.
iwr -useb https://openclaw.ai/install.ps1 | iex이 방식이 좋은 이유는 단순하다. 초보자가 가장 자주 실수하는 Node 버전, 설치 경로, 온보딩 진입을 한 번에 정리해 주기 때문이다.1 "나는 npm을 잘 아니까 수동 설치로 갈래"라고 생각해도 괜찮다. 하지만 첫 설치에서는 자존심보다 성공 경험이 더 중요하다.
다만 이 장의 제목이 괜히 npm 한 줄 설치가 아니다. 인스톨러가 가장 빠른 길이라면, npm 설치는 무슨 일이 벌어지는지 더 잘 보이는 길이다. 그래서 다음 절에서는 수동 설치 루트를 기준으로 설명하겠다.
핵심 실습: npm 한 줄 설치
이미 Node를 직접 관리하고 있다면, OpenClaw CLI 설치는 정말 한 줄이다.1
npm install -g openclaw@latest설치가 끝났다면 바로 버전부터 확인하자.
openclaw --version여기서 버전이 정상 출력되면 CLI는 들어온 것이다. 하지만 아직 OpenClaw가 "부화"한 것은 아니다. 지금 상태는 공구함을 샀을 뿐, 전기도 연결하지 않은 상태에 가깝다.
다음 한 줄이 진짜 시작이다.
openclaw onboard --install-daemon공식 npm 패키지 설명도 온보딩을 권장 경로로 안내한다. 이 마법사가 Gateway, workspace, channels, skills 설정을 단계별로 묶어 주기 때문이다.2
왜 --install-daemon이 그렇게 중요한가
이 옵션은 이름만 보면 사소해 보이지만, 실제로는 설치 성공률을 크게 바꾼다. --install-daemon은 Gateway를 백그라운드 서비스로 등록한다. macOS에서는 LaunchAgent, Linux와 WSL2에서는 systemd 사용자 서비스, 네이티브 Windows에서는 Scheduled Task 또는 대체 시작 항목 방식으로 관리된다.13
쉽게 말해, 터미널을 닫아도 에이전트의 심장이 계속 뛰게 만드는 옵션이다.
이걸 빼면 어떻게 될까. 그때부터는 OpenClaw를 쓸 때마다 "어, 왜 응답이 없지?" 하고 확인하게 된다. 대부분의 경우 이유는 간단하다. Gateway가 꺼져 있기 때문이다. 초보자에게는 이 함정이 꽤 치명적이다. 채널 문제인지, API 문제인지, 모델 문제인지 헷갈리기 때문이다.
그래서 첫 설치에서는 웬만하면 이렇게 기억하면 된다.
npm install -g openclaw@latest
openclaw onboard --install-daemon이 두 줄이 기본 세트다.
온보딩 마법사는 무엇을 해 주는가
"마법사"라는 표현 때문에 안내 화면 정도로 오해하기 쉽지만, 실제로는 OpenClaw를 쓸 수 있는 상태로 바꾸는 설정 도우미에 가깝다. 공식 설명에 따르면 이 과정에서 Gateway, workspace, 채널, 스킬, 모델 인증 같은 핵심 요소를 한 번에 엮는다.2
처음 실행하면 보통 이런 질문들이 나온다.
1. Gateway를 어디서 돌릴 것인가
대부분의 독자는 로컬을 선택하면 된다. 지금 당장 내 노트북이나 WSL2 안에서 돌아가는 OpenClaw 하나를 먼저 살리는 것이 중요하다. 원격 서버나 VPS는 나중에 옮겨도 늦지 않다.
첫날부터 원격 배포를 하려는 마음은 이해하지만, 그 선택은 네트워크와 서비스 관리라는 새로운 난이도를 추가한다. 오늘은 에이전트를 내 손으로 깨우는 날이지, 인프라 설계 면접을 보는 날이 아니다.
2. 어떤 모델 프로바이더를 붙일 것인가
이 부분은 지난 장에서 이미 결정을 내려두었다. Anthropic이든 OpenAI든 DeepSeek든, 여기서는 망설이지 말고 준비해 둔 키를 넣으면 된다. 중요한 것은 "제일 좋은 모델"이 아니라 "지금 응답하는 모델"이다.
일부 설정 흐름에서는 API 키를 직접 붙여 넣고, 일부는 OAuth 기반 인증을 지원한다. 헤드리스 서버에서 OAuth가 번거로운 경우에는 로컬에서 먼저 인증한 자격 파일을 옮기는 방식도 안내된다.4
3. 첫 채널을 연결할 것인가
처음에는 Telegram 하나면 충분하다. Telegram은 봇 토큰 방식이라 구조가 단순하고, 첫 연결 확인용으로 빠르다. WhatsApp은 편하지만 QR 로그인과 세션 관리가 더 개입하므로, "빨리 성공해 보기" 목적에는 Telegram이 유리하다.45
채널 연결을 아직 안 하고 싶다면 일단 건너뛰고 대시보드에서 먼저 테스트해도 된다. 실제로 공식 설치 가이드들은 설치 확인용으로 대시보드와 Gateway 상태 확인을 함께 권한다.1
4. 백그라운드 서비스까지 등록할 것인가
여기서는 고민하지 말고 Yes 쪽으로 가면 된다. 앞서 설명한 --install-daemon이 이 단계와 연결되어 있다. 재부팅 후에도 계속 돌아가게 하려면 이 등록이 필요하다.14
가장 현실적인 권장 순서
처음 설치하는 독자라면, 아래 순서가 실패 확률이 가장 낮다.
CLI 설치
온보딩 실행
채널은 Telegram 하나만 연결
스킬 추가 설치는 나중으로 미루기
설치 검증 후 그다음 장으로 넘어가기
이 순서가 좋은 이유는 "문제의 범위"가 좁기 때문이다. 한 번에 너무 많이 열면, 어디에서 꼬였는지 찾는 데 시간이 더 든다. 첫날의 승리는 화려한 멀티채널이 아니라, 내가 보낸 메시지에 OpenClaw가 답하는 순간이다.
설치 직후 바로 해 볼 검증 3종 세트
설치가 끝났다면 감으로 넘어가지 말고 확인해야 한다. 공식 문서가 권하는 기본 점검은 아래 세 가지다.1
openclaw --version
openclaw doctor
openclaw gateway status각 명령은 이런 의미를 갖는다.
openclaw --version은 CLI가 제대로 잡혔는지 본다. openclaw doctor는 설정, 경로, 구성 문제를 훑는다. openclaw gateway status는 Gateway가 실제로 떠 있는지 확인한다. 셋 중 하나라도 이상하면, 다음 장의 텔레그램 테스트로 넘어가지 말고 여기서 잡는 편이 낫다.
여유가 있다면 대시보드도 열어 보자.
openclaw dashboard또는 브라우저에서 아래 주소를 직접 열면 된다.
http://127.0.0.1:18789/이 화면이 열리면 감정적으로도 안심이 된다. 이제 "뭔가 설치된 것 같다"가 아니라, "정말 살아 있다"가 되기 때문이다.4
macOS, Linux, Windows에서 보이는 차이
겉으로는 같은 명령을 쓰지만, 운영체제마다 체감 포인트는 조금 다르다.
macOS와 Linux
보통 가장 매끄럽다. npm install -g 후 openclaw onboard --install-daemon까지 가면 큰 분기 없이 흐르는 경우가 많다. macOS에서는 launchd, Linux에서는 systemd로 자동 시작이 붙는다.1
단, macOS에서는 Homebrew로 전역 libvips가 들어가 있는 경우 sharp 설치가 꼬일 수 있다. 이때는 사전 빌드 바이너리를 강제로 쓰는 우회가 공식 문서에 안내되어 있다.1
SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latestWindows WSL2
이 책의 1차 독자 중 Windows 사용자는 아마 가장 많을 것이다. 그리고 가장 많이 듣는 질문도 이것이다. "PowerShell로 바로 깔면 안 되나요?"
된다. 다만 편하다고는 장담하기 어렵다. 공식 문서는 여전히 WSL2가 더 안정적인 경로라고 본다.13 이유는 명확하다. OpenClaw의 CLI와 Gateway, 그리고 나중에 붙일 여러 도구와 스킬이 Linux 환경과 더 자연스럽게 맞물리기 때문이다.
WSL2에서는 특히 systemd가 켜져 있어야 daemon 설치가 자연스럽다. 이미 지난 장에서 준비했다면, 여기서는 Ubuntu 터미널 안에서 그대로 다음 두 줄만 치면 된다.
npm install -g openclaw@latest
openclaw onboard --install-daemon만약 native Windows로 가는 경우, Scheduled Task 생성이 거부되면 사용자 Startup 폴더 기반 자동 시작으로 대체될 수 있다.3 즉, 돌아가긴 하지만 WSL2가 여전히 더 예측 가능하다.
openclaw not found가 나올 때
이 오류는 생각보다 흔하다. 설치는 되었는데 셸이 실행 파일을 못 찾는 경우다. 공식 문서는 이런 순서로 진단하라고 안내한다.1
node -v
npm prefix -g
echo "$PATH"보통 문제는 전역 npm의 bin 경로가 PATH에 안 들어가 있어서 생긴다. macOS나 Linux에서는 아래처럼 셸 시작 파일에 추가하면 해결되는 경우가 많다.1
export PATH="$(npm prefix -g)/bin:$PATH"그다음 새 터미널을 열면 된다. 설치가 실패한 게 아니라, 길 안내 표지판이 빠진 경우라고 생각하면 이해하기 쉽다.
pnpm과 bun은 언제 쓰면 좋을까
공식 문서는 npm 외에도 pnpm과 bun 설치를 지원한다.1 하지만 첫 설치에서는 욕심을 줄이는 편이 좋다.
pnpm은 설치 속도와 디스크 사용 면에서 장점이 있지만, 빌드 스크립트 승인을 따로 해 줘야 하는 지점이 있다. 예를 들어 pnpm add -g openclaw@latest 뒤에 pnpm approve-builds -g를 실행해야 하는 흐름이 생길 수 있다.6 익숙한 사용자에게는 별것 아니지만, 처음 설치하는 독자에게는 "왜 한 번에 안 되지?"라는 불안 포인트가 된다.
bun도 가능은 하지만, 채널 조합에 따라 이슈가 있다는 안내가 커뮤니티 가이드에 보인다. 특히 Telegram이나 WhatsApp 같은 채널을 빨리 붙여 볼 계획이라면 첫 설치는 Node.js 경로가 더 무난하다.4
이 장의 결론은 간단하다. 첫날은 npm 또는 공식 인스톨러, 실험은 둘째 날부터다.
Docker 대안 경로: 설치를 깔끔하게 격리하고 싶다면
여기까지 읽고도 이런 생각이 들 수 있다.
"내 노트북 전역 환경에 뭔가를 설치하는 게 싫다."
그 감각은 아주 건강하다. 특히 보안을 중요하게 보는 운영자라면 더 그렇다. 이런 경우 Docker는 꽤 괜찮은 우회로다. 일부 가이드들은 OpenClaw를 컨테이너로 먼저 맛보는 방법으로 아래 같은 예시를 제시한다.7
docker pull ghcr.io/openclaw/openclaw:latest
docker run -it ghcr.io/openclaw/openclaw:latest openclaw --help이 경로의 장점은 분명하다. 호스트 환경을 덜 오염시키고, 지우기도 쉽고, 실험용 인스턴스를 따로 만들기 좋다. "한 번 돌려 보고 아니다 싶으면 깨끗하게 지우고 싶다"는 사람에게 잘 맞는다.
하지만 첫 사용자 경험이라는 관점에서는 단점도 있다. 채널 연결, 상태 저장, 백그라운드 서비스, 로컬 파일 접근 같은 문제가 곧바로 등장한다. 즉, Docker는 설치를 깔끔하게 만들지만, 초보자에게는 개념을 하나 더 추가한다. 컨테이너라는 층이 생기기 때문이다.
그래서 권장 기준은 이렇다.
개인 노트북에서 빠르게 첫 대화까지 가고 싶다면 npm 또는 인스톨러가 낫다. 반대로 VPS, 홈서버, 격리된 실험 환경에서 운영할 생각이라면 Docker가 의미가 커진다. 실무적으로 말하면, Docker는 처음 배우는 사람의 최단 경로라기보다 운영 감각이 있는 사람의 정리된 경로에 가깝다.
설치 시간을 30분 안으로 줄이는 팁
설치에 오래 걸리는 사람과 빨리 끝내는 사람의 차이는 실력보다 분기 처리에 있다. 계속 선택지를 넓히면 시간이 늘어난다. 처음에는 오히려 단순할수록 좋다.
오늘 기준으로 가장 빠른 루트는 이렇다.
운영체제는 이미 준비된 macOS, Linux, 또는 WSL2만 사용한다.
설치 방법은 인스톨러 또는 npm 둘 중 하나만 고른다.
모델 프로바이더는 지난 장에서 정한 하나만 붙인다.
채널은 Telegram 하나만 연결한다.
스킬 설치는 건너뛴다.
설치 직후
doctor와gateway status만 확인한다.
이렇게 하면 설치가 프로젝트가 아니라 체크리스트가 된다.
지금 바로 따라 하는 10분 버전
정말 최소한의 경로만 남기면, 실습은 아래처럼 끝난다.
먼저 설치한다.
npm install -g openclaw@latest다음으로 온보딩을 시작한다.
openclaw onboard --install-daemon온보딩에서는 로컬 Gateway, 준비해 둔 모델 인증, Telegram 채널 정도만 설정한다. 그리고 끝나면 아래를 확인한다.
openclaw --version
openclaw doctor
openclaw gateway status브라우저에서 http://127.0.0.1:18789/가 열리면 성공이다. 이쯤 되면 OpenClaw는 더 이상 설치 중인 소프트웨어가 아니다. 이미 당신의 메신저를 기다리는 에이전트다.
이 장의 함정 정리
설치 장에서 초보자가 가장 많이 빠지는 함정은 세 가지다.
첫째, CLI 설치만 하고 온보딩을 안 한다. 둘째, 온보딩은 했지만 --install-daemon 없이 끝낸다. 셋째, 설치 확인 없이 곧바로 Telegram부터 붙인다.
이 세 가지를 피하면 설치는 놀랄 만큼 부드럽다. 반대로 셋 중 하나라도 빠지면, 모든 문제가 채널 문제처럼 보인다. 사실은 Gateway가 안 살아 있거나, 인증이 비어 있거나, 경로가 안 잡힌 것뿐인데 말이다.
설치는 기술적인 의식이 아니다. 순서를 지키는 일이다. OpenClaw는 한 줄로 깔 수 있지만, 한 줄로 완성되지는 않는다. 그다음 한 줄, openclaw onboard --install-daemon, 그 한 줄이 당신의 바닷가재를 진짜로 움직이게 만든다.
다음 장에서는 이제 Telegram으로 들어가 실제로 "안녕"이라고 말해볼 것이다. 그때부터는 설치가 아니라 대화다.
참고
5Install - OpenClaw Documentation
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.