소스 코드에서 빌드하는 이유
대부분의 사용자는 npm install -g openclaw@latest로 빠르게 OpenClaw을 설치할 수 있습니다. 그러나 일부 상황에서는 소스 코드에서 빌드하는 것이 더 나은 선택입니다: 코드 기여를 통해 버그를 수정하거나 새 기능을 추가하고 싶은 경우, 안정 릴리스 대신 최신 개발 버전을 사용해야 하는 경우, OpenClaw의 내부 구현을 깊이 이해하고 싶은 경우, 또는 특정 요구사항에 맞게 소스 코드를 커스터마이징해야 하는 경우입니다.
이 글에서는 git clone부터 빌드 완료까지의 전체 과정을 자세히 소개합니다.
사전 요구사항
소스 코드에서 OpenClaw을 빌드하려면 다음 도구가 필요합니다:
- Node.js 22+: OpenClaw의 최소 실행 요구사항입니다. WhatsApp 및 Telegram 연결 시 알려진 버그가 있으므로 Bun을 사용하지 마세요
- pnpm: OpenClaw 프로젝트는 pnpm을 패키지 관리자로 사용합니다
- Git: 소스 코드 저장소를 복제하는 데 사용합니다
- C/C++ 빌드 툴체인: 일부 네이티브 종속성의 컴파일이 필요합니다
Node.js 22 설치
Node.js를 아직 설치하지 않았다면, nvm으로 관리하는 것을 권장합니다:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22
버전 확인:
node --version # v22.x.x가 표시되어야 합니다
pnpm 설치
Node.js에 내장된 corepack으로 pnpm을 활성화합니다:
corepack enable
corepack prepare pnpm@latest --activate
또는 npm으로 설치합니다:
npm install -g pnpm
설치 확인:
pnpm --version
빌드 툴체인 설치
Ubuntu/Debian의 경우:
sudo apt install -y build-essential python3
macOS의 경우:
xcode-select --install
소스 코드 저장소 복제
GitHub에서 OpenClaw 저장소를 복제합니다:
git clone https://github.com/openclaw/openclaw.git
cd openclaw
최신 개발 버전을 사용하려면:
git checkout dev
특정 안정 버전을 기반으로 빌드하려면:
git tag -l
git checkout v1.0.0 # 실제 버전 번호로 대체하세요
종속성 설치
pnpm으로 모든 프로젝트 종속성을 설치합니다:
pnpm install
OpenClaw은 monorepo 프로젝트이며, pnpm이 워크스페이스 내 각 패키지 간의 종속성 관계를 자동으로 처리합니다. 설치 과정에서 일부 네이티브 Node.js 모듈을 컴파일해야 할 수 있으므로, 앞서 C/C++ 빌드 툴체인을 설치해야 합니다.
네이티브 빌드 승인
일부 종속성에는 컴파일이 필요한 네이티브 코드가 포함되어 있습니다. pnpm은 보안상의 이유로 이러한 빌드를 명시적으로 승인하도록 요구합니다:
pnpm approve-builds -g
이 명령은 네이티브 컴파일이 필요한 모든 패키지를 나열하고 확인을 요청합니다. 목록을 검토하고 이상이 없으면 승인하세요.
프로젝트 빌드
OpenClaw의 빌드는 두 단계로 나뉩니다: 먼저 프론트엔드 UI를 빌드하고, 그 다음 전체 프로젝트를 빌드합니다.
프론트엔드 Dashboard 빌드
pnpm ui:build
이 명령은 OpenClaw의 관리 패널 프론트엔드 코드를 컴파일하며, 머신 성능에 따라 보통 1-3분이 소요됩니다.
메인 프로젝트 빌드
pnpm build
이 명령은 TypeScript 소스 코드를 컴파일하고, 각 모듈을 번들링하며, 최종 실행 가능한 결과물을 생성합니다.
빌드가 완료되면 프로젝트 루트 디렉토리에서 컴파일된 결과물을 확인할 수 있습니다.
빌드 결과 검증
테스트를 실행하여 빌드가 올바른지 확인합니다:
pnpm test
그런 다음 OpenClaw 시작을 시도합니다:
pnpm start
또는 빌드된 CLI를 직접 실행합니다:
node ./dist/cli.js --version
전역 명령으로 연결
npm으로 설치한 것처럼 어디서든 openclaw 명령을 사용하려면, pnpm의 link 기능을 사용할 수 있습니다:
pnpm link --global
이후 시스템 어디에서든 실행할 수 있습니다:
openclaw --version
openclaw doctor
초기 설정
OpenClaw을 처음 실행할 때, 가이드 프로그램을 실행합니다:
openclaw onboard --install-daemon
가이드 프로그램은 AI 모델 설정, 채팅 플랫폼 연결 설정을 안내하며, 운영 체제에 따라 데몬 프로세스를 설치합니다(macOS의 경우 LaunchAgent, Linux의 경우 systemd 서비스).
설정 파일은 ~/.openclaw/openclaw.json에 저장됩니다.
개발 모드
코드 기여를 위해 개발하는 경우, 개발 모드로 시작할 수 있습니다:
pnpm dev
개발 모드에서는 핫 리로드가 활성화되어, 소스 코드를 수정하면 자동으로 재컴파일 및 서비스 재시작이 이루어져 개발 효율성이 크게 향상됩니다.
프로젝트 구조 개요
프로젝트 구조를 이해하면 수정하려는 코드를 찾는 데 도움이 됩니다:
openclaw/
├── packages/
│ ├── core/ # 코어 엔진, 메시지 라우팅 및 AI 모델 스케줄링
│ ├── cli/ # 명령줄 도구
│ ├── ui/ # Dashboard 프론트엔드
│ ├── whatsapp/ # WhatsApp 커넥터
│ ├── telegram/ # Telegram 커넥터
│ ├── discord/ # Discord 커넥터
│ └── ... # 기타 플랫폼 커넥터
├── pnpm-workspace.yaml
└── package.json
소스 코드 업데이트
업스트림 저장소에 업데이트가 있을 때, 최신 코드를 가져와서 다시 빌드할 수 있습니다:
git pull origin main
pnpm install
pnpm approve-builds -g
pnpm ui:build
pnpm build
로컬 수정 사항이 있다면, 먼저 stash하거나 브랜치에서 작업하여 병합 충돌을 피하는 것이 좋습니다.
일반적인 빌드 문제
pnpm install 실패
Node.js 버전이 22+ 이상인지, pnpm 버전이 충분히 새로운지 확인하세요. 캐시를 정리한 후 다시 시도합니다:
pnpm store prune
rm -rf node_modules
pnpm install
네이티브 모듈 컴파일 실패
빌드 툴체인이 완전히 설치되었는지 확인하세요. Ubuntu에서는 build-essential과 python3이 설치되어 있어야 합니다.
ui:build 메모리 부족
프론트엔드 빌드는 메모리를 많이 소모할 수 있습니다. Node.js 메모리 제한을 늘려보세요:
NODE_OPTIONS="--max-old-space-size=4096" pnpm ui:build
빌드 후 실행 오류
openclaw doctor를 실행하여 환경 설정을 확인하고, 모든 종속성 버전이 호환되는지 확인하세요.
정리
소스 코드에서 OpenClaw을 빌드 및 설치하는 것은 직접 npm으로 설치하는 것보다 단계가 많지만, 완전한 제어 권한을 갖게 됩니다. 오픈소스 기여에 참여하든, 개발 버전의 새로운 기능을 사용하든, 특정 시나리오에 맞게 OpenClaw을 깊이 커스터마이징하든, 소스 코드 빌드는 필수적인 스킬입니다. 이 과정을 마스터하면 OpenClaw의 최신 개발 진행 상황을 따라가고 커뮤니티 기여에 적극적으로 참여할 수 있습니다.