최 몇 개월간, 'AI 에이전트'는 기술계에서 자주 언급되는 용어가 되었지만, 대부분의 개발자들은 데모, 플러그인, 그리고 개념 수준에 머물러 있습니다. 실제로 로컬/서버에서 실행되고, 실제 권한을 갖추며, 지속적으로 작업을 수행할 수 있는 에이전트는 드뭅니다.
OpenClaw는 현재 몇 안 되는 공학적으로 완성되고, 배포 가능하며, 2차 개발이 가능한 오픈소스 AI 에이전트 프레임워크 중 하나입니다.
이 글에서는 비전을 말하거나 허황된 이야기를 할 것이 아니라, 어떻게 설치하고 실행하며, 어떻게 문제를 피할지에만 집중합니다.
OpenClaw란 정확히 무엇인가? 먼저 정의부터 명확히 하겠습니다
한 문장으로 설명하자면:
OpenClaw는 로컬이나 서버에 배포할 수 있는 오픈소스 AI 에이전트 프레임워크로, Gateway(통신), Dashboard(제어판), 그리고 Skills(기능 플러그인) 세 가지 핵심 모듈을 갖추고 있습니다.
ChatGPT/플러그인과의 근본적인 차이점은 다음과 같습니다:
| 비교 항목 | 일반 AI 도구 | OpenClaw |
|---|---|---|
| 실행 위치 | 클라우드 | 로컬/VPS |
| 권한 | 제한됨 | 제어 가능한 높은 권한 |
| 지속 실행 | 불가능 | 가능 |
| 자동 실행 | 약함 | 강력함 |
| 2차 개발 | 거의 불가능 | 완전히 가능 |
따라서 OpenClaw는 "챗봇"이 아니라 진정한 의미의 AI 실행체입니다.
왜 "신중한 설치"가 필수적인가?
많은 사람들이 첫 배포에 실패하는 이유는 기술력 부족 때문이 아니라, 그 위험한 경계선을 명확히 이해하지 못하기 때문입니다.
OpenClaw의 능력은 다음과 같지만 이에 국한되지 않습니다:
- 로컬 파일 읽기/쓰기
- 시스템 명령 호출
- 외부 API 요청
- 장시간 백그라운드 실행
- Gateway를 통한 Telegram/Discord 연동
이것이 "고권한 에이전트"라는 의미입니다.
따라서: ❌ 일반적인 업무용 PC에 직접 설치하지 마세요 ✅ 강력히 권장: 독립된 VPS/Docker/격리 환경
배포 환경 선택 (이 부분이 나중에 과정을 원활하게 만듭니다)
권장 구성 (실전 사용 가능)
- 시스템: Ubuntu 20.04 / 22.04
- CPU: 2코어 이상 (4코어가 더 안정적)
- 메모리: 4GB 이상 (8GB가 더 편리함)
- 용도: OpenClaw만 실행하고 다른 서비스와 혼용하지 않음
Windows도 실행 가능하지만, 유도 및 데모용으로는 Linux가 더 전문적이고 안정적이며 범용적입니다.
기본 환경 준비 (단 하나도 생략할 수 없는 단계)
1️⃣ 시스템 업데이트 & 기본 도구 설치
sudo apt update
sudo apt install -y git curl unzip
2️⃣ Node.js 설치 (OpenClaw 필수 요구사항)
공식 요구사항은 Node 18+이며, nvm 사용을 권장합니다:
curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install 18
nvm use 18
검증:
node -v
npm -v
3️⃣ (선택적이지만 권장) pnpm 설치
소스 코드 배포 및 2차 개발에 기본적으로 사용됩니다:
npm install -g pnpm
OpenClaw 설치 (두 가지 방식 중 하나 선택)
방식 1: CLI 전역 설치 (가장 빠름)
다음에 적합합니다:
- 빠르게 실행하고 싶은 경우
- 소스 코드를 수정하지 않을 경우
npm install -g openclaw
검증:
openclaw --version
버전 번호가 보이면 CLI 설치가 성공한 것입니다.
방식 2: 소스 코드 배포 (전문가 / 2차 개발자용)
다음에 적합합니다:
- UI를 수정하고 싶은 경우
- 자체 시스템과 연동하고 싶은 경우
- 사용자 정의 skills를 작성하고 싶은 경우
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm build
가장 중요한 단계: Onboard 초기화 (여기서 많은 사람들이 막힙니다)
OpenClaw는 설치만으로 바로 사용할 수 없으며, 반드시 onboarding을 실행해야 합니다.
CLI 설치 방식:
openclaw onboard --install-daemon
소스 코드 방식:
pnpm openclaw onboard --install-daemon
이 단계에서 다음 작업이 수행됩니다:
- Gateway 초기화
- 로컬 구성 생성
- 실행 서비스(daemon) 등록
- Dashboard 바인딩
- 에이전트 ID 생성
90%의 문제는 "올바르게 onboard하지 않은" 데서 발생합니다
Gateway가 정상적으로 실행 중인지 확인
openclaw gateway status
정상적인 경우 다음과 같은 결과가 표시됩니다:
- running
- healthy
- listening on port xxx
그렇지 않다면 로그를 직접 확인하세요:
openclaw gateway logs
Dashboard 시작 (여기서 "전문성"을 보여줄 수 있습니다)
openclaw dashboard
다음과 같은 내용을 볼 수 있습니다:
- 에이전트 상태
- 대화 기록
- Skills 관리
- Gateway 연결 상태
- 시스템 로그
많은 유입은 이 Dashboard 스크린샷을 통해 이루어집니다
Skills(기능 플러그인)를 어떻게 이해해야 할까요?
Skills를 다음과 같이 이해할 수 있습니다:
AI가 호출할 수 있는 "함수 + 권한 집합"
예를 들어:
- 블록체인 데이터 조회
- 내부 API 호출
- 스크립트 실행
- Telegram 메시지 발송
- 서버 상태 읽기
초보자를 위한 권장 순서:
- 읽기 전용 skills
- 알림/조회용 skills
- 실행형 skills (나중에 고려)
처음부터 root 권한을 주지 마세요
가장 흔한 6가지 함정 (유저 유입을 위해 작성)
1. Gateway가 시작되지 않음
- Node 버전이 맞지 않음
- 포트가 이미 사용 중
- onboard가 완료되지 않음
2. Dashboard가 열리지 않음
- 방화벽에서 포트가 허용되지 않음
- 서버에 포트 매핑이 없음
- 서비스가 실행 중이지 않음
3. Skill이 작동하지 않음
- 권한이 부여되지 않음
- 구성이 다시 로드되지 않음
- 스키마에 맞지 않는 작성 방식
4. 에이전트 행동을 제어할 수 없음
- skills 권한이 너무 큼
- prompt에 제한이 없음
- 샌드박스가 구성되지 않음
5. 계속해서 오류가 발생하지만 원인을 모름
- gateway 로그를 확인하지 않음
- dashboard 로그를 확인하지 않음
6. 생산 서버에 직접 설치
- 이것이 가장 위험한 방법입니다
"설치 성공"의 기준은 무엇인가? (검수 기준)
다음 5가지 조건을 모두 만족하면, 당신이 "OpenClaw를 다룰 줄 안다"고 말할 수 있습니다:
✅ CLI 정상 작동 ✅ Gateway 실행 중 ✅ Dashboard에 접속 가능 ✅ 최소 1개의 skill 활성화 가능 ✅ 에이전트가 완전한 작업을 한 번 수행 가능