OpenClaw 리눅스 설치 완전 가이드

OpenClaw은 TypeScript 기반으로 작성된 프로젝트로, 설치 자체는 비교적 간단하지만 몇 가지 핵심 단계를 정확히 따르는 것이 중요하다. 이 가이드는 Ubuntu 24.04 LTS 기준으로 작성되었다.

---

사전 준비: 보안 원칙 먼저

설치 전 반드시 알아야 할 사항이 있다. OpenClaw은 실험적 소프트웨어이며 완전히 안전하지 않다. 개인 기기나 민감한 데이터가 있는 장치에는 절대 설치하지 않아야 한다. VPS, 가상 머신, 또는 개인 기기와 분리된 전용 물리 장치에 설치하는 것을 권장한다. 또한 절대 root 계정으로 설치하지 않아야 한다.

---

Step 1. Node.js 설치

OpenClaw은 Node.js 24(권장) 또는 Node.js 22.16 이상을 요구한다. 터미널을 열고 아래 명령어를 순서대로 실행한다.

# 시스템 패키지 업데이트
sudo apt update && sudo apt upgrade -y

# Node.js 24 설치 (NodeSource 공식 스크립트 이용)
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt install -y nodejs

# 설치 확인
node -v   # v24.x.x 출력되어야 함
npm -v

---

Step 2. OpenClaw 설치

npm, pnpm, bun 중 원하는 패키지 매니저로 설치할 수 있다.

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

💡 리눅스에서 EACCES 권한 오류가 발생하면 sudo를 붙이거나, npm의 전역 디렉터리를 홈 폴더로 변경하는 것이 더 안전합니다.

---

Step 3. 온보딩 마법사 실행

openclaw onboard 명령은 게이트웨이, 워크스페이스, 채널, 스킬 설정을 단계별로 안내하는 공식 권장 방식이다. --install-daemon 옵션을 붙이면 systemd 유저 서비스로 등록되어 부팅 후에도 자동으로 실행된다.

openclaw onboard --install-daemon

 

실행하면 대화형 설정 화면이 나타난다. 주요 선택 항목은 다음과 같다.

 

① 네트워크 바인딩 선택 보안을 위해 루프백(Loopback) 네트워크 인터페이스에 게이트웨이를 바인딩하는 것을 선택하세요. 0.0.0.0을 선택하면 로컬 네트워크 내 모든 기기에서 접근 가능해져 보안상 위험합니다.

 

② AI 모델 제공자 선택 Anthropic(Claude), OpenAI(GPT), 로컬 모델 등을 선택할 수 있습니다. 이후 해당 서비스의 API 키를 붙여 넣으면 인증이 완료됩니다.

 

③ 채널(메신저) 연동 WhatsApp, Telegram, Discord 등 원하는 채널을 선택합니다. 예를 들어 WhatsApp을 선택하면 QR 코드가 표시되며, WhatsApp 앱에서 설정 > QR 코드 아이콘 > 코드 스캔을 통해 연결합니다.

 

④ 스킬(Skills) 설정 처음이라면 일단 건너뛰고(No) 나중에 추가할 수 있습니다. 설치 후 openclaw skills 명령으로 언제든지 관리 가능합니다.

 

모든 설정이 완료되면 재시작 여부를 묻는 화면이 나오고, Restart를 선택하면 OpenClaw가 온라인 상태가 된다.

---

Step 4. 웹 UI 접속 및 토큰 입력

설정이 완료되면 OpenClaw Web UI 접속 주소인 http://127.0.0.1:18789가 화면에 표시된다. 액세스 토큰도 함께 표시되므로 복사해 둔다. 브라우저에서 해당 주소에 접속한 뒤, Web UI의 설정 항목에 복사한 토큰을 붙여 넣으면 게이트웨이와 연결된다.

---

Step 5. 정상 동작 확인

openclaw --version      # 버전 확인
openclaw doctor         # 설정 이상 유무 진단
openclaw gateway status # 게이트웨이 실행 상태 확인

 

openclaw doctor 명령은 설정 문제를 점검하고, openclaw gateway status는 게이트웨이가 정상 실행 중인지 확인해 준다. 세 명령어 모두 정상 출력이 나오면 설치가 완료된 것이다.

---

설치 후 보안 강화

커뮤니티 플러그인(스킬)은 설치 전 반드시 검토한다. 멀웨어가 포함된 것들이 있으므로 Cisco Skill Scanner 등으로 스캔하는 것이 좋다. 또한 터미널, 파일 삭제, git push 등 돌이키기 어려운 작업에는 exec_approval 플래그를 설정해 AI가 실행 전 사람의 승인을 받도록 구성한다.

---

마치며

전체 설치 흐름을 요약하면 Node.js 설치 → npm으로 openclaw 설치 → onboard 마법사 실행 → API 키·채널 연동 → 웹 UI 확인 순서이다. 처음에는 복잡해 보이지만 온보딩 마법사가 대부분을 대화형으로 안내해주기 때문에 터미널에 익숙하다면 30분 이내에 완료할 수 있다. 설치 후 연결한 메신저로 메시지를 보내보자. AI가 바로 응답한다면 성공이다. 🦞