OpenClaw 완전 설치 가이드: 환경 준비부터 첫 실행까지

2026-06-08 업데이트: OpenClaw 공식 설치 문서를 기준으로 Node 버전(권장 v24, 최소 v22.14+), 원클릭 스크립트, onboard 절차를 다시 확인하고 같은 시리즈의 추가 읽을거리도 보완했습니다. 명령어와 포트는 공식 문서를 기준으로 합니다.

OpenClaw 설치 과정은 예상보다 순조로웠습니다. Mac, Linux, Windows 중 무엇을 사용하든 가이드를 따라가면 큰 문제에 부딪힐 가능성이 높지 않습니다. 명령줄에 익숙하지 않지만 한 번 써 보고 싶은 분을 위해 설치 경험을 체계적으로 정리했습니다.

저비용으로 ‘새우 키우기’: ArkClaw로 AI Agent를 누구나 부담 없이

최근 큰 인기를 끌고 있는 OpenClaw(랍스터)는 유용하지만 설정 과정이 만만치 않습니다. ByteDance Volcano Engine의 ArkClaw는 이 진입 장벽을 크게 낮췄습니다. 서버나 Token 설정 때문에 씨름할 필요 없이 한 번의 클릭으로 24시간 온라인 상태를 유지하면서 브라우저를 제어하고, 스크립트를 실행하고, 캘린더를 관리하는 ‘AI 일꾼’을 가질 수 있습니다.

특히 가격이 저렴합니다. 월 이용료는 9.9위안이며, 제 초대 코드 ZLKUK54M을 사용해 여기에서 가입하면 8.9위안입니다. 프로그래머라면 Coding Plan Pro를 이용해 무료로 사용할 수도 있습니다.

OpenClaw란 무엇인가요?

설치를 시작하기 전에 OpenClaw가 무엇인지 먼저 살펴보겠습니다. 간단히 말해 OpenClaw는 ChatGPT, Claude 같은 대규모 언어 모델을 Telegram이나 WhatsApp처럼 자주 사용하는 채팅 도구에 연결해 주는 오픈 소스 AI 어시스턴트 플랫폼입니다.

굳이 로컬에 설치할 이유가 있는지, 웹 버전 AI를 바로 쓰면 되지 않는지 궁금할 수 있습니다.

각 방식에는 저마다 장점이 있습니다. 로컬에 설치하면 다음과 같은 일을 할 수 있습니다.

• 데이터와 개인정보를 직접 관리할 수 있습니다.
• 다양한 기능과 Skills를 자유롭게 맞춤 설정할 수 있습니다.
• AI를 자신의 워크플로에 연결할 수 있습니다.
• 설정에 공을 들인다면 클라우드 서비스에 전혀 의존하지 않고 로컬 모델도 사용할 수 있습니다.

저에게 가장 매력적인 점은 AI를 Telegram에 연결할 수 있다는 것입니다. 평소 채팅하듯 바로 호출할 수 있어 앱을 오갈 필요가 없습니다.

준비 작업: 시스템 확인하기

솔직히 OpenClaw의 시스템 요구 사항은 꽤 부담이 적습니다. 그래도 시작하기 전에 몇 가지를 확인해야 합니다.

운영체제 호환성

OpenClaw는 macOS와 Linux를 네이티브로 지원합니다. Windows의 경우 공식 설치 문서에서 네이티브 Windows와 WSL2를 모두 안내합니다. 아래 Linux 명령을 그대로 사용하려면 대체로 WSL2가 가장 간편합니다.

WSL2는 Windows 안에서 가벼운 Linux 환경을 실행하는 방식입니다. 사용하려면 PowerShell을 열고 다음 명령 하나로 설치를 시작하면 됩니다.

wsl --install

설치 후 컴퓨터를 재시작하세요. 그다음 PowerShell에서 wsl을 입력하면 Linux 환경으로 들어갈 수 있습니다.

하드웨어 요구 사항

하드웨어 측면에서도 OpenClaw는 까다롭지 않습니다. 공식 권장 사양은 다음과 같습니다.

• 메모리: 8GB면 충분하고 16GB면 더 좋습니다.
• 저장 공간: 최소 20GB의 여유 공간이 필요합니다(SSD 사용을 권장하며 체감 성능이 훨씬 좋아집니다).

기본적으로 브라우저를 원활하게 실행할 수 있는 컴퓨터라면 OpenClaw도 무리 없이 실행할 수 있습니다. 저는 메모리 8GB인 오래된 MacBook을 사용하는데도 꽤 원활하게 작동했습니다.

Node.js 환경

가장 중요한 단계입니다. OpenClaw는 Node.js 기반이므로 먼저 Node를 설치해야 합니다. 공식 설치 문서에 따르면 Node 24를 권장하며 **최소 Node 22.14+**가 필요합니다. 원클릭 설치 스크립트는 버전이 부족할 때 이를 알려 주거나 해결을 도와줍니다.

nvm으로 직접 버전을 관리한다면 일상적인 개발과 실행 용도로 24를 설치하는 것이 좋습니다.

macOS에 Node.js 설치하기

Mac 사용자에게 가장 간단한 방법은 Homebrew를 사용하는 것입니다.

# Homebrew가 없다면 먼저 설치합니다
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 이어서 Node.js를 설치합니다
brew install node

Linux에 Node.js 설치하기

Linux에서는 nvm(Node Version Manager)을 권장합니다. 서로 다른 Node.js 버전을 쉽게 전환할 수 있기 때문입니다.

# nvm 설치
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 터미널을 재시작한 뒤 Node.js 설치(24 권장)
nvm install 24
nvm use 24

Windows(WSL2)에 Node.js 설치하기

WSL2에서는 Linux와 같은 방법으로 nvm을 사용하면 됩니다.

설치가 끝나면 버전을 확인합니다.

node --version

v22.14+ 또는 v24.x(권장)가 표시되면 현재 공식 요구 사항을 충족합니다.

패키지 관리자: npm과 pnpm 중 무엇을 선택할까요?

Node.js를 설치하면 npm(Node Package Manager)도 함께 설치됩니다. OpenClaw는 npm만으로도 문제없이 사용할 수 있습니다.

pnpm을 알고 있다면 이것을 사용해도 됩니다. pnpm은 npm과 비교해 다음과 같은 장점이 있습니다.

• 설치 속도가 더 빠릅니다.
• 디스크 공간을 더 적게 차지합니다.
• 의존성 관리가 더 엄격합니다.

일반 사용자라면 어느 쪽을 사용해도 괜찮습니다. 저는 pnpm에 익숙하지만 전적으로 개인 취향의 문제입니다.

pnpm을 설치하려면 다음 명령을 실행하세요.

npm install -g pnpm

OpenClaw 설치 시작하기

준비 작업이 끝났으니 이제 본격적으로 시작하겠습니다. OpenClaw는 여러 설치 방법을 제공하며, 권장 순서대로 소개하겠습니다.

방법 1: 공식 설치 스크립트(가장 권장)

가장 간단한 방법으로, 명령 하나면 충분합니다.

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

이 스크립트는 다음 작업을 자동으로 처리합니다.

• 시스템 환경 확인
• 필수 의존성 설치
• OpenClaw CLI 다운로드 및 설치
• 초기 설정 실행 안내

전체 과정은 네트워크 속도에 따라 약 1~2분이 걸립니다. 처음 설치할 때 터미널에 로그가 빠르게 쌓이는 모습을 보니 꽤 성취감이 들었습니다.

방법 2: npm 전역 설치

패키지 관리자를 선호한다면 npm으로 바로 설치할 수 있습니다.

npm install -g openclaw@latest

@latest는 최신 버전을 설치하도록 지정합니다. 설치가 끝나면 터미널에서 바로 openclaw 명령을 사용할 수 있습니다.

방법 3: pnpm 전역 설치

pnpm을 사용한다면 다음과 같이 실행합니다.

pnpm add -g openclaw@latest

npm과 효과는 같고 사용하는 도구만 다릅니다.

방법 4: 소스 코드에서 설치하기(고급)

직접 손보고 싶거나 OpenClaw에 코드를 기여할 계획이라면 GitHub에서 소스 코드를 복제할 수 있습니다.

# 저장소 복제
git clone https://github.com/openclaw/openclaw.git

# 디렉터리로 이동
cd openclaw

# 의존성 설치
pnpm install

# 빌드
pnpm ui:build

이 방법은 개발자에게 적합하며 일반 사용자에게는 권장하지 않습니다.

초기 설정: OpenClaw 실행 준비하기

OpenClaw를 설치한 직후에는 바로 사용할 수 없으며 먼저 설정 마법사를 한 번 실행해야 합니다. 중요한 단계이지만 어렵지는 않습니다.

onboard 마법사 실행하기

터미널에 다음 명령을 입력합니다.

openclaw onboard --install-daemon

이 명령은 대화형 설정 마법사를 시작합니다. --install-daemon 매개변수는 OpenClaw를 시스템 서비스로 설치한다는 뜻입니다. 그러면 부팅할 때 자동으로 실행되므로 매번 직접 시작할 필요가 없습니다.

이어서 마법사가 몇 가지 질문을 차례로 표시합니다.

1. 실행 모드 선택

원격 서버에 배포할 생각이 아니라면 보통 **로컬 모드(Local gateway)**를 선택하면 됩니다.

2. AI 모델 설정

사용할 AI 제공업체를 선택해야 합니다. 현재 지원하는 항목은 다음과 같습니다.

• OpenAI(GPT-5 등)
• Anthropic(Claude 시리즈)
• 로컬 모델(추가 설정 필요)

OpenAI 또는 Anthropic API 키가 있다면 여기에 입력합니다. 없다면 우선 건너뛰고 나중에 설정해도 됩니다.

API 키를 받는 방법은 다음과 같습니다.

• OpenAI: platform.openai.com에서 계정을 만든 뒤 API keys 페이지에서 생성합니다.
• Anthropic: console.anthropic.com에서 가입한 뒤 마찬가지로 API 설정에서 생성합니다.

3. 작업 디렉터리 설정

마법사가 OpenClaw 설정과 데이터를 저장할 위치를 묻습니다. 기본 경로는 ~/.openclaw/이며, 일반적으로 Enter 키를 눌러 기본값을 사용하면 됩니다.

4. 메시지 채널 연결

AI와 대화할 채팅 플랫폼을 선택하는 단계입니다. 현재 지원하는 항목은 다음과 같습니다.

• Telegram: 먼저 Telegram에서 @BotFather를 찾아 bot을 만들고 token을 받아야 합니다.
• WhatsApp: QR 코드가 생성되며 휴대전화의 WhatsApp으로 스캔하여 연결합니다.
• 건너뛰기: Web 인터페이스만 사용하려면 일단 건너뛸 수 있습니다.

저는 Telegram을 선택했으며 설정 과정은 아주 간단했습니다.

1. Telegram에서 @BotFather를 검색합니다.
2. /newbot 명령을 보냅니다.
3. 안내에 따라 bot의 이름을 지정합니다.
4. 생성된 token을 복사합니다.
5. OpenClaw 설정에 붙여 넣습니다.

5. 데몬 설치

마지막으로 마법사가 데몬을 설치할지 묻습니다. ‘예’를 선택하면 OpenClaw가 백그라운드에서 계속 실행되므로 터미널을 닫아도 영향을 받지 않습니다.

전체 설정에는 약 5~10분이 걸리며, 대부분의 시간은 API 키를 받고 채팅 채널을 설정하는 데 사용됩니다.

직접 설정하기(선택 사항)

설정을 세부적으로 조정하려면 설정 파일을 편집할 수 있습니다.

nano ~/.openclaw/openclaw.json

이 파일은 JSON 형식이며 모든 설정 항목을 포함합니다. 하지만 대부분의 사용자에게는 마법사 설정으로 충분하므로 직접 수정할 필요가 없습니다.

첫 실행: 정상 작동 확인하기

설정을 마치면 OpenClaw를 시작할 수 있습니다.

Gateway 실행하기

앞에서 데몬을 설치하지 않았다면 직접 실행해야 합니다.

openclaw gateway --port 18789

18789는 기본 포트이며 다른 값으로 바꿀 수 있습니다. 정상적으로 시작되면 다음과 비슷한 출력이 표시됩니다.

✓ OpenClaw Gateway started on http://localhost:18789

Web 인터페이스 접속하기

브라우저를 열고 다음 주소로 이동합니다.

http://localhost:18789

OpenClaw 제어 화면이 표시되어야 합니다. 인터페이스는 간결하며 주로 다음 영역으로 구성됩니다.

• Chat: 채팅 테스트 영역
• Agents: AI Agent 관리
• Skills: 다양한 Skill 플러그인 설정
• Settings: 시스템 설정

대화 테스트하기

Chat 페이지에서 ‘안녕하세요’ 또는 ‘자기소개를 해 주세요’ 같은 메시지를 보내 보세요.

모든 설정이 올바르면 AI가 답변할 것입니다. 처음 답변을 확인하면 꽤 설렙니다. 바로 자신이 직접 구축한 AI 어시스턴트입니다!

자주 발생하는 문제 해결

소프트웨어를 설치하다 보면 작은 문제가 생기기 마련입니다. 자주 마주치는 문제를 정리했으니 해결할 때 참고하세요.

Node.js 버전이 맞지 않는 경우

증상: openclaw 명령을 실행하면 Node 버전이 호환되지 않는다는 오류가 표시됩니다.

해결 방법: Node.js 버전을 확인하여 v22.14 이상인지 확인합니다(v24 권장).

node --version

버전이 너무 낮다면 Node.js를 다시 설치하거나 업그레이드하세요.

WSL2 설정 문제(Windows 사용자)

증상: Windows에서 설치할 때 여러 오류가 발생합니다.

해결 방법: WSL2가 올바르게 설치되어 있고 최신 버전으로 업데이트되었는지 확인합니다.

wsl --update

API 키가 유효하지 않은 경우

증상: API 키를 설정했지만 AI가 답변하지 않거나 오류가 발생합니다.

해결 방법:

• 키를 정확히 복사했는지 확인합니다(앞뒤에 불필요한 공백이 없어야 합니다).
• API 계정에 잔액이 있는지 확인합니다(OpenAI와 Anthropic 모두 충전이 필요합니다).
• 키를 새로 생성해 봅니다.

포트가 이미 사용 중인 경우

증상: Gateway를 시작할 때 포트 18789가 이미 사용 중이라는 메시지가 표시됩니다.

해결 방법: 다른 포트를 사용하거나 해당 포트를 사용하는 프로세스를 찾아 종료합니다.

# 18789 포트를 사용하는 프로세스 확인
lsof -i :18789

# 다른 포트로 실행
openclaw gateway --port 18790

권한 문제

증상: 설치할 때 권한이 부족하다는 메시지가 표시됩니다.

해결 방법: Linux/Mac 사용자는 sudo를 사용해야 할 수 있으며, 디렉터리 권한도 확인해야 합니다.

# 쓰기 권한 확보
chmod -R 755 ~/.openclaw

보안 주의 사항

OpenClaw를 설치한 후에는 몇 가지 보안 사항에 주의해야 합니다.

1. 포트를 노출하지 마세요: 포트 18789는 기본적으로 localhost에서만 수신합니다. 절대로 공개 인터넷에 노출하지 마세요. 노출하면 누구나 여러분의 AI에 접근할 수 있습니다.
2. API 키를 보호하세요: 설정 파일의 API 키는 민감한 정보입니다. 다른 사람과 공유하거나 Git 저장소에 커밋하지 마세요.
3. 원격 접속에는 SSH 터널을 사용하세요: 다른 기기에서 접속하려면 포트를 직접 개방하지 말고 SSH 터널을 사용하세요.

# 다른 컴퓨터에서 SSH를 통해 접속
ssh -L 18789:localhost:18789 user@your-server

관련 글

• OpenClaw 설정 상세 가이드: openclaw.json 완전 정복
• OpenClaw 아키텍처 심층 분석: 3계층 설계와 확장 실전
• OpenClaw vs ChatGPT: 기술 아키텍처, 비용, 개인정보 보호 비교

마치며

여기까지 따라왔다면 OpenClaw 설치를 성공적으로 마쳤을 것입니다. 전체 과정을 다시 정리해 보겠습니다.

다음 단계에서는 다음과 같은 작업을 할 수 있습니다.

• Skills 기능을 살펴보고 AI에 다양한 기능을 추가합니다.
• Telegram이나 WhatsApp을 연결해 채팅 앱에서 AI를 호출해 봅니다.
• 관심이 있다면 사용자 정의 Skill을 개발하는 방법을 알아봅니다.
• 공식 문서에서 더 많은 고급 기능을 확인합니다.

솔직히 OpenClaw는 오픈 소스 프로젝트이지만 이미 상당히 완성도 높은 경험을 제공합니다. 설치 중 문제가 발생하면 GitHub Issues 페이지를 확인해 보세요. 커뮤니티도 꽤 활발합니다.

마지막으로 한 가지 말씀드리겠습니다. 이런 도구를 처음 접하면 다소 복잡하게 느껴질 수 있지만 한 번 설치해 보면 생각보다 별것 아니라는 점을 알게 됩니다. 서두르지 말고 문제가 생기면 충분히 검색해 보세요. 대부분 해결할 수 있습니다.

즐겁게 사용하세요!

---